<!-- source_url: https://docs.mynexusapi.com/v1/guias/emision-04 | last_updated: 2026-11-19 -->

# Nota de crédito

Emite una nota de crédito para devolver dinero, aplicar un descuento posterior o anular total o parcialmente una factura autorizada.

Un comprobante autorizado no se puede editar ni borrar. Cuando necesitas
devolver dinero, conceder un descuento después de facturar o anular una venta,
emites una nota de crédito que apunta a la factura original y dice cuánto se
acredita al comprador.

Esta guía explica cómo identificar la factura que modificas, te da un ejemplo
mínimo de devolución parcial listo para enviar y describe cada campo con las
reglas que valida la API. El endpoint, las cabeceras, el
[secuencial](/v1/guias/glosario) automático y las reglas comunes a todos los
tipos están en [Comprobantes electrónicos](/v1/guias/emision).

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Los ejemplos usan
> `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/datos-de-prueba).

La ruta de emisión fija el tipo `04`. Si quieres comprobar el cuerpo antes de
emitir, usa la ruta de validación, que aplica las mismas reglas y no consume
cupo.

```
POST /v1/contribuyentes/{identificacion}/notas-credito
POST /v1/contribuyentes/{identificacion}/notas-credito/validar
```

No envíes `infoTributaria.tipoDocumento`. La validación
se explica en [Validar sin emitir](/v1/guias/emision#validar-sin-emitir).

## Conceptos

La factura a la que **apunta** la nota de crédito es el documento modificado o
[sustento](/v1/guias/glosario). Además del valor que se acredita al comprador,
la nota indica por qué se acredita.

- Los valores de la nota son **positivos**: representan lo que devuelves o
  descuentas. No envíes importes negativos, porque la API responde 422.
- El comprador es el mismo de la factura original.
- La nota lleva sus propias líneas (`detalles`) con lo que se acredita, sus
  impuestos y sus totales. No lleva pagos.

## Cuándo la emites

Emite una nota de crédito en situaciones como estas:

- **Devolución parcial**: el cliente devuelve uno de los productos que compró.
  La nota lleva solo la línea devuelta.
- **Devolución total o anulación de la venta**: se revierte toda la factura. La
  nota lleva todas las líneas y su valor es igual al total de la factura.
- **Descuento posterior a la venta**: un descuento por pronto pago o una
  bonificación por volumen que concedes después de facturar. La nota lleva una
  línea con el valor del descuento y su IVA.
- **Corrección de un precio cobrado de más**: la nota acredita la diferencia.

Para cobrar un valor **adicional** sobre una factura, como intereses o
recargos, usa una [nota de débito](/v1/guias/emision-05), no una nota de crédito.

## Referencia al documento modificado

Con cuatro campos de `info` identificas la factura que modificas. Cópialos de
tu registro de la factura original, porque la API **no los busca ni los
completa** por ti.

| Campo | De dónde sale | Formato | Ejemplo |
|---|---|---|---|
| `codDocModificado` | Tipo del comprobante original. Casi siempre una factura. | Hasta 2 dígitos, completados con ceros a la izquierda. | `"01"` |
| `numDocModificado` | Número de la factura: `estab-ptoEmi-secuencial`. Es lo que se imprime en el RIDE y lo que devuelve `numeroDocumento` en el seguimiento. | `ddd-ddd-ddddddddd` (3, 3 y 9 dígitos separados por guiones). | `"002-001-000000123"` |
| `fechaEmisionDocSustento` | `fechaEmision` de la factura original. | `dd/MM/yyyy`. | `"01/10/2026"` |
| `totalDocumentoSustento` | `importeTotal` de la factura original. Opcional, pero recomendado. | Número con 2 decimales. | `115.00` |

El campo `numDocModificado` admite algunas variantes de formato:

- Si un segmento tiene menos dígitos, la API lo completa con ceros:
  `"2-1-123"` se toma como `"002-001-000000123"`. Te recomendamos enviar el
  formato completo para evitar dudas.
- También se acepta sin guiones si tiene entre 10 y 15 dígitos, como
  `"002001000000123"`.
- Si envías solo el secuencial, como `"123"` o `"000000123"`, la API lo
  rechaza, porque no supone el establecimiento ni el punto de emisión.

Si envías `totalDocumentoSustento`, la API comprueba que `valorModificacion` no
lo supere. Si emites varias notas de crédito para una misma factura, controla en
tu sistema que su suma no supere el total de la factura, porque la API no lleva
el saldo acumulado de las notas anteriores.

## Ejemplo mínimo

Este ejemplo es una devolución parcial. De la factura 002-001-000000123 del
01/10/2026, con un total de 115.00, el cliente devuelve un servicio de 20.00 con
IVA 15 %. Guarda el JSON como `comprobante.json`, porque lo usan los ejemplos de
[Envío](#envio).

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "NOTACREDITO-2026-0001",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "codDocModificado": "01",
    "numDocModificado": "002-001-000000123",
    "fechaEmisionDocSustento": "01/10/2026",
    "totalDocumentoSustento": 115.00,
    "totalSinImpuestos": 20.00,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 20.00,
        "valor": 3.00
      }
    ],
    "valorModificacion": 23.00,
    "moneda": "DOLAR",
    "motivo": "DEVOLUCION PARCIAL DEL SERVICIO"
  },
  "detalles": [
    {
      "codigoInterno": "SERV-001",
      "descripcion": "DEVOLUCION SERVICIO DE MANTENIMIENTO",
      "cantidad": 1,
      "precioUnitario": 20.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 20.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 20.00,
          "valor": 3.00
        }
      ]
    }
  ]
}
```

La tabla muestra cómo se calcula cada total del ejemplo.

| Campo | Cálculo | Valor |
|---|---|---|
| `detalles[0].precioTotalSinImpuesto` | 1 x 20.00 - 0 | 20.00 |
| `detalles[0].impuestos[0].valor` | 20.00 x 15 / 100 | 3.00 |
| `totalConImpuestos[0]` | Suma de las líneas con IVA 15 % (`4`) | base 20.00, valor 3.00 |
| `totalSinImpuestos` | Suma de `precioTotalSinImpuesto` | 20.00 |
| `valorModificacion` | `totalSinImpuestos` + IVA + ICE = 20.00 + 3.00 | 23.00 |
| Control de saldo | 23.00 no supera `totalDocumentoSustento` (115.00) | Correcto |

`valorModificacion` ocupa en la nota de crédito el lugar de `importeTotal`: es el
total que se acredita al comprador, con impuestos. Las líneas y los impuestos se
calculan igual que en
[Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales).

## Envío

Envía el `comprobante.json` del ejemplo mínimo con cualquiera de estos
ejemplos. Todos usan como `Idempotency-Key` la misma `referenciaExterna`,
NOTACREDITO-2026-0001, así que repetir el envío no emite otra nota.

```bash
curl -s -i -X POST \
  "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito" \
  -H "X-Api-Key: $ECUAFACT_API_KEY" \
  -H "Idempotency-Key: NOTACREDITO-2026-0001" \
  -H "Content-Type: application/json" \
  -d @comprobante.json
# 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion}
```

```csharp
using System.Net.Http;
using System.Text;

string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/notas-credito");
peticion.Headers.Add("Idempotency-Key", "NOTACREDITO-2026-0001");
peticion.Content = new StringContent(
    await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json");

using HttpResponseMessage respuesta = await http.SendAsync(peticion);
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
```

```python
import json
import os
import requests

with open("comprobante.json", encoding="utf-8") as archivo:
    cuerpo = json.load(archivo)

r = requests.post(
    "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito",
    headers={
        "X-Api-Key": os.environ["ECUAFACT_API_KEY"],
        "Idempotency-Key": "NOTACREDITO-2026-0001",
    },
    json=cuerpo,
    timeout=30,
)
print(r.status_code, r.text)
```

```javascript
// Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs
import { readFile } from 'node:fs/promises';

const res = await fetch(
  'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ECUAFACT_API_KEY,
      'Idempotency-Key': 'NOTACREDITO-2026-0001',
      'Content-Type': 'application/json'
    },
    body: await readFile('comprobante.json', 'utf8')
  });
console.log(res.status, await res.text());
```

```php
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
        'Idempotency-Key: NOTACREDITO-2026-0001',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'),
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $estado . ' ' . $cuerpo . PHP_EOL;
```

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .header("Idempotency-Key", "NOTACREDITO-2026-0001")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json"))))
    .build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
```

```csharp-sdk
using Ecuafact.Sdk;

// client: EcuafactClient creado con tu API Key (ver SDK .NET)
// comprobante: NotaCreditoRequest con la nota de credito de esta pagina
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "NOTACREDITO-2026-0001");
Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}");
```

```python-sdk
from ecuafact import EcuafactClient

# client: EcuafactClient creado con tu API Key (ver SDK Python)
# comprobante: NotaCreditoRequest con la nota de credito de esta pagina
resultado = client.emitir_en("0123456789001", comprobante, "NOTACREDITO-2026-0001")
print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}")
```

```javascript-sdk
import { EcuafactClient } from "@ecuafact/sdk";

// client: EcuafactClient creado con tu API Key (ver SDK Node.js)
// comprobante: NotaCreditoRequest con la nota de credito de esta pagina
const resultado = await client.emitirEn("0123456789001", comprobante, "NOTACREDITO-2026-0001");
console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`);
```

```php-sdk
<?php
use Ecuafact\Sdk\EcuafactClient;

// $client: EcuafactClient creado con tu API Key (ver SDK PHP)
// $comprobante: NotaCreditoRequest con la nota de credito de esta pagina
$resultado = $client->emitirEn('0123456789001', $comprobante, 'NOTACREDITO-2026-0001');
echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL;
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EmisionResultado;

// client: EcuafactClient creado con tu API Key (ver SDK Java)
// comprobante: NotaCreditoRequest con la nota de credito de esta pagina
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "NOTACREDITO-2026-0001");
System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado());
```

```bash-cli
# Resultado esperado: una fila con el estado recibido y el idOperacion de la emisión.
ecuafact emitir comprobante.json --entorno sandbox
```

**Resultado esperado.** La API responde 202 con `estado` en `recibido`, el `codEstado` 1001 o 1002 y un `idOperacion`.

## Estructura del comprobante

El cuerpo de la nota de crédito se organiza en bloques, y cada tabla describe
uno.

### Raíz

| Clave | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `origenReferencia` | string | Sí | Nombre de tu sistema, de 1 a 64 caracteres entre letras y dígitos ASCII y `-` `_` `.` `:` `/`. |
| `referenciaExterna` | string | Sí | Tu número interno de la nota, de 1 a 128 caracteres con el mismo alfabeto. |
| `infoTributaria` | object | Sí | Identidad del comprobante. Sus campos están en la tabla siguiente. |
| `info` | object | Sí | Cabecera de la nota, que se describe más abajo. |
| `detalles` | array | Sí | De 1 a 1000 líneas con lo que se acredita. |
| `infoAdicional` | array | No | Hasta 15 objetos `{ "nombre", "valor" }`, cada uno de 1 a 300 caracteres. |

### `infoTributaria`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `ruc` | string | Sí | RUC completo del emisor, de 13 dígitos; en pruebas, `0123456789001`. |
| `estab` | string | Sí | Establecimiento de la nota, de hasta 3 dígitos. Se completa con ceros. Puede ser distinto del de la factura. |
| `ptoEmi` | string | Sí | Punto de emisión de la nota, de hasta 3 dígitos. Se completa con ceros. |
| `secuencial` | string | No | Hasta 9 dígitos. Omítelo y te asignamos el siguiente de la serie de notas de crédito, que es independiente de la serie de facturas. |

### `info`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `fechaEmision` | string | Sí | Fecha de la nota, `dd/MM/yyyy`. Envía la fecha de hoy, porque el comprobante autorizado lleva la fecha del día en que se procesa. |
| `dirEstablecimiento` | string | No | Hasta 300 caracteres. |
| `tipoIdentificacionComprador` | string | Sí | `04` RUC, `05` cédula, `06` pasaporte u `08` identificación del exterior. Los valores están en [Catálogos](/v1/guias/catalogos#tipos-de-identificacion). `07`, consumidor final, no se admite. |
| `identificacionComprador` | string | Sí | La del comprador de la factura original. Con `04`, 13 dígitos; con `05`, 10 dígitos; con `06` y `08`, hasta 20 caracteres. |
| `razonSocialComprador` | string | Sí | Hasta 300 caracteres. |
| `direccionComprador` | string | No | Hasta 300 caracteres. |
| `telefono` | string | No | Hasta 40 caracteres. |
| `correo` | string | No | Correo del comprador al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se toma un campo de `infoAdicional` llamado `email` o `correo`. |
| `codDocModificado` | string | Sí | Tipo del documento modificado, normalmente `"01"`. Se explica en [Referencia al documento modificado](#referencia-al-documento-modificado). |
| `numDocModificado` | string | Sí | `ddd-ddd-ddddddddd`. |
| `fechaEmisionDocSustento` | string | Sí | Fecha de la factura original, `dd/MM/yyyy`. |
| `totalDocumentoSustento` | number | No | `importeTotal` de la factura original. Si llega, `valorModificacion` no puede superarlo. |
| `totalSinImpuestos` | number | Sí | Suma de `detalles[].precioTotalSinImpuesto`. |
| `totalConImpuestos` | array | Sí | Una o dos filas, una por cada pareja `codigo` + `codigoPorcentaje` de las líneas, con `baseImponible` y `valor` sumados. `tarifa` es opcional. |
| `valorModificacion` | number | Sí | `totalSinImpuestos` + IVA + ICE. Es el total acreditado. |
| `moneda` | string | Sí | `DOLAR` o `USD`. |
| `motivo` | string | Sí | Razón de la nota, como `DEVOLUCION` o `DESCUENTO POR PRONTO PAGO`, de hasta 300 caracteres. Los saltos de línea se convierten en espacios. |

No envíes `totalDescuento`, `propina`, `importeTotal` ni `pagos`. Si los
envías, aunque lleven `0`, la API responde 422 con
`Campo no soportado en este contrato.`

### `detalles[]`

En la nota de crédito, las líneas usan `codigoInterno` y `codigoAdicional` en
lugar de `codigoPrincipal` y `codigoAuxiliar`.

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `codigoInterno` | string | Sí | Código del bien o servicio, hasta 25 caracteres. Usa el mismo de la factura. |
| `codigoAdicional` | string | No | Hasta 25 caracteres. |
| `descripcion` | string | Sí | Hasta 300 caracteres. |
| `cantidad` | number | Sí | Cantidad acreditada, mayor que 0, hasta 6 decimales. |
| `precioUnitario` | number | Sí | Mayor o igual a 0, hasta 6 decimales, sin IVA. |
| `descuento` | number | Sí | Importe en dólares, con 2 decimales como máximo. Envía `0` si no hay. |
| `precioTotalSinImpuesto` | number | Sí | `cantidad x precioUnitario - descuento`, redondeado a 2 decimales. |
| `impuestos` | array | Sí | Un IVA, con `"2"`, y como máximo un ICE, con `"3"`, cada uno con `codigoPorcentaje`, `tarifa`, `baseImponible` y `valor`. Usa la misma tarifa que tuvo la línea en la factura; las reglas están en [Factura](/v1/guias/emision-01). |
| `detallesAdicionales` | array | No | Hasta 3 objetos `{ "nombre", "valor" }`. |

## Reglas de cálculo y validaciones

Las líneas e impuestos siguen
[Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales). Si una
regla no se cumple, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`). Estos son los errores
típicos de la nota de crédito:

| Error típico | Mensaje (en `errores`) | Qué hacer |
|---|---|---|
| Enviar en `numDocModificado` solo el secuencial. | `$.info.numDocModificado: Indique establecimiento y punto de emision; no se infieren.` | Envía `002-001-000000123`. |
| Enviar `numDocModificado` con otra cantidad de segmentos, como `002-001`. | `$.info.numDocModificado: Use estab-pto-secuencial.` | Usa tres segmentos separados por guiones. |
| Enviar `numDocModificado` con letras o con segmentos demasiado largos. | `Solo se admiten digitos.` / `Longitud excedida.` | Usa como máximo 3, 3 y 9 dígitos. |
| Enviar la fecha del sustento en otro formato. | `$.info.fechaEmisionDocSustento: Use dd/MM/yyyy, como el SRI.` | Usa `01/10/2026`. |
| La nota supera el total de la factura. | `El valor de la nota de credito no puede superar el total del documento que acredita.` | Revisa `valorModificacion` y `totalDocumentoSustento`. |
| Calcular mal `valorModificacion`. | `total no coincide con subtotal + IVA + ICE + propina.` | Calcula `valorModificacion` como `totalSinImpuestos` + IVA + ICE. |
| Enviar `pagos`, `totalDescuento`, `propina` o `importeTotal`. | `$.info.pagos: Campo no soportado en este contrato.` | Quita esos campos. |
| Usar `codigoPrincipal` en las líneas. | `$.detalles[0].codigoPrincipal: Campo no soportado en este contrato.` | Cambia a `codigoInterno`. |
| Identificar al comprador como consumidor final (`07`). | `...requiere un contribuyente identificado.` | Identifica al comprador como en la factura original. |
| Enviar importes negativos. | `Numero fuera de rango.` | Envía valores positivos. |
| Falta `motivo`. | `$.info.motivo: Campo obligatorio.` | Explica la razón de la nota. |
| Calcular mal una línea. | `Subtotal del detalle no coincide con cantidad × precio − descuento.` / `Valor de impuesto no coincide con base y tasa.` | Recalcula la línea como en la [factura](/v1/guias/emision-01#reglas-de-calculo-y-validaciones). |
| Enviar un `totalConImpuestos` que no cuadra con las líneas. | `Base o valor de impuestos no coincide con detalles.` | Suma bases y valores por `codigo` + `codigoPorcentaje`. |
| `totalSinImpuestos` o el IVA no cuadran con las líneas. | `Totales no coinciden con detalles.` | Suma de nuevo las líneas. |

Antes de emitir, te recomendamos comprobar en tu sistema que la factura
modificada exista y esté autorizada, que el comprador coincida con el de la
factura, que la fecha de la nota sea posterior a la de la factura y que la suma
de varias notas no supere la factura. La API **no** hace esas comprobaciones;
algunas puede hacerlas el SRI.

## Más ejemplos

Cada ejemplo es un cuerpo completo. Antes de enviarlo, cambia su
`referenciaExterna` por una que no hayas usado y envía esa misma cadena como
`Idempotency-Key`.

### Devolución total de la factura

Esta nota anula toda la factura 002-001-000000123, de 100.00 más 15.00 de IVA,
es decir, 115.00. Su `valorModificacion` es igual a `totalDocumentoSustento`, lo
que está permitido.

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "NOTACREDITO-2026-0002",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "codDocModificado": "01",
    "numDocModificado": "002-001-000000123",
    "fechaEmisionDocSustento": "01/10/2026",
    "totalDocumentoSustento": 115.00,
    "totalSinImpuestos": 100.00,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 100.00,
        "valor": 15.00
      }
    ],
    "valorModificacion": 115.00,
    "moneda": "DOLAR",
    "motivo": "ANULACION DE LA VENTA"
  },
  "detalles": [
    {
      "codigoInterno": "SERV-001",
      "descripcion": "SERVICIO DE MANTENIMIENTO",
      "cantidad": 1,
      "precioUnitario": 100.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 100.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 100.00,
          "valor": 15.00
        }
      ]
    }
  ]
}
```

### Descuento posterior por pronto pago

El cliente pagó antes de tiempo y le concedes 5.00 de descuento sobre la misma
factura. La nota lleva una línea de 5.00 con IVA 15 %, cuyo IVA es 5.00 x 15 / 100 =
0.75, así que `valorModificacion` es 5.00 + 0.75 = 5.75.

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "NOTACREDITO-2026-0003",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "codDocModificado": "01",
    "numDocModificado": "002-001-000000123",
    "fechaEmisionDocSustento": "01/10/2026",
    "totalDocumentoSustento": 115.00,
    "totalSinImpuestos": 5.00,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 5.00,
        "valor": 0.75
      }
    ],
    "valorModificacion": 5.75,
    "moneda": "DOLAR",
    "motivo": "DESCUENTO POR PRONTO PAGO"
  },
  "detalles": [
    {
      "codigoInterno": "DESC-PP",
      "descripcion": "DESCUENTO POR PRONTO PAGO",
      "cantidad": 1,
      "precioUnitario": 5.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 5.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 5.00,
          "valor": 0.75
        }
      ]
    }
  ]
}
```

## Respuesta

La API responde 202 Accepted con este cuerpo:

```json
{
  "estado": "recibido",
  "codEstado": 1001,
  "errores": [],
  "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "ambiente": 1,
  "tipoDocumento": "04",
  "numeroDocumento": "002-001-000000001",
  "referenciaExterna": "NOTACREDITO-2026-0001",
  "claveAcceso": null,
  "fhRecibido": "2026-11-16T10:15:00-05:00",
  "fhAutorizacion": null
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | string | `recibido`: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación. Normalmente el 202 trae `recibido`, pero si el resultado ya se conoce al responder, trae directamente el estado final (`autorizado` con 2001, `rechazado` con 3xxx o `rechazo_configuracion` con 4xxx), con su `msgError` y su detalle en `errores`. Decide siempre por `estado` y `codEstado`. |
| `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Acepta los dos valores. |
| `errores` | array de string | Viene siempre; en una emisión recibida es una lista vacía, y con un resultado final trae su detalle. |
| `idOperacion` | string (UUID) | Identificador de la operación. Guárdalo para el seguimiento. |
| `urlEstado` | string | URL completa del seguimiento, igual a la cabecera `Location`. Puedes llamarla tal como viene. |
| `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. |
| `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes en el seguimiento o en el webhook. Con 1002 o con un resultado final ya viene en la respuesta. |
| `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. |

Los demás campos, `ambiente`, `tipoDocumento`, `referenciaExterna` y `fhAutorizacion`, tienen la misma forma del [seguimiento de una operación](/v1/guias/consulta-operacion#respuesta), y el campo `msgError` solo aparece cuando el 202 ya trae un resultado final con error.

Un 202 significa que la nota quedó **recibida**, todavía no autorizada. Sigue la
operación con
[`GET /v1/operaciones/{idOperacion}`](/v1/guias/consulta-operacion) o espera el
[webhook](/v1/guias/webhooks). Registra en tu sistema el crédito al cliente solo
cuando su `estado` sea `autorizado`.

## Estados de este endpoint

Esta tabla reúne las respuestas que puedes recibir al emitir una nota de crédito.

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 1001 o 1002 | 202 | La nota de crédito quedó recibida, o reintentaste con la misma `Idempotency-Key` y el mismo cuerpo. | Guarda `idOperacion` y sigue la operación; un reintento trae el estado actual. No reenvíes con otros datos. |
| 3003 (`solicitud_invalida`) | 400 | El JSON está mal formado, o la `Idempotency-Key` falta o no es válida. | Corrige la petición. |
| 3002 (`comprobante_invalido`) | 422 | La nota no cumple una regla; el detalle viene en `errores`. | Corrige según la tabla de errores típicos. Consume 1 documento como intento. |
| 3004 (`comprobante_duplicado`) | 409 | Ya existe una nota de crédito con ese número (`estab`-`ptoEmi`-`secuencial`) autorizada, pendiente o rechazada por el SRI. | Consulta la existente. Si la anterior no se emitió (`document.failed`), puedes reenviar el mismo número con nueva `Idempotency-Key` y `referenciaExterna`; si la rechazó el SRI, emite con un secuencial nuevo (omite `secuencial` para que se asigne el siguiente). |
| 3005 (`conflicto_idempotencia`) | 409 | Usaste la misma `Idempotency-Key` con otro cuerpo, o una `referenciaExterna` que ya usó otro comprobante. | No cambies el cuerpo de un reintento. Para un comprobante nuevo, incluida la corrección de un rechazo, usa otra `Idempotency-Key` y otra `referenciaExterna`. |
| 4004 (`cupo_agotado`) | 429 | Se agotó el cupo. | Compra un paquete de documentos en el Portal del Cliente y no reintentes en bucle. Revisa [Consumo](/v1/guias/consumo). |
| 3009 (`credenciales_invalidas`) | 401 | La API Key no es válida. | Revisa la API Key. |
| 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. | Registra tu IP en **Cuenta > IP permitidas** o llama sin proxies que oculten el origen. |
| 3011 (`acceso_denegado`) | 403 | La nota de crédito no está habilitada para tu integración, o el `ruc` no es el del contribuyente. | Revisa `tiposComprobante` en el contexto y el RUC enviado. |
| 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera los segundos que indica `Retry-After` y reintenta con la misma clave. |

Todos los errores traen la misma forma de la respuesta 202, con `msgError`, el detalle en `errores` y `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Seguimiento de una operación](/v1/guias/consulta-operacion): confirma si el SRI autorizó la nota.
- [Factura](/v1/guias/emision-01): repasa los campos y cálculos de la factura que modificas.
- [Nota de débito](/v1/guias/emision-05): cobra un valor adicional sobre una factura.
- [Descarga el ejemplo de solicitud](/downloads/v1/ejemplos/example-04.json): cuerpo de nota de crédito listo para ensayar.
