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

# Nota de débito

Emite una nota de débito para cobrar intereses, recargos u otros ajustes al alza sobre una factura que ya emitiste.

La nota de débito aumenta lo que el comprador te debe por un comprobante ya
emitido, sin anularlo.

Esta guía te da un ejemplo mínimo listo para enviar, explica cómo se calculan
sus totales y describe cada campo con las reglas que valida la API. El
endpoint, las cabeceras 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).

Envías la nota de débito a su endpoint de emisión. El tipo lo fija la ruta, así
que el cuerpo no lleva `infoTributaria.tipoDocumento`.

```
POST /v1/contribuyentes/{identificacion}/notas-debito
Cabeceras: X-Api-Key, Idempotency-Key, Content-Type: application/json

POST /v1/contribuyentes/{identificacion}/notas-debito/validar
Cabeceras: X-Api-Key, Content-Type: application/json
```

La ruta `/validar` comprueba el cuerpo sin emitirlo, sin `Idempotency-Key` y sin
consumir cupo. Responde 200 con `valido` en `true` y `errores` vacío, o el mismo
error que daría la emisión, como se explica en
[Validar sin emitir](/v1/guias/emision#validar-sin-emitir).

## Conceptos

- **Documento modificado**: el comprobante que la nota de débito incrementa,
  normalmente una factura. Lo identificas con su tipo en `codDocModificado`, su
  número en `numDocModificado` y su fecha en `fechaEmisionDocSustento`.
  Cópialos de tu registro, porque usamos los datos que envías sin buscarlos ni
  corregirlos.
- **Motivos**: en lugar de líneas de productos, la nota de débito lleva en
  `motivos` una lista de razones, cada una con su valor **sin impuestos**.
- **Un solo IVA**: todos los motivos comparten la tarifa de IVA declarada en
  `info.impuestos`. Con esa tarifa calculas el IVA de cada motivo y envías su
  suma.

Los demás términos, como [RUC](/v1/guias/glosario),
[secuencial](/v1/guias/glosario), [clave de acceso](/v1/guias/glosario) o
[RIDE](/v1/guias/glosario), están explicados en el [Glosario](/v1/guias/glosario).

## Cuándo la emites

Estos son los casos habituales en los que emites una nota de débito:

- Intereses por mora: el cliente pagó una factura después del vencimiento.
- Gastos de cobranza, de envío o bancarios que cobras después de la venta.
- Un ajuste de precio al alza que no incluiste en la factura original.

Si en lugar de aumentar necesitas **disminuir** el valor, por una devolución o un
descuento posterior, emite una [Nota de crédito](/v1/guias/emision-04).

## Antes de empezar

- [ ] Una API Key de pruebas en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea tu sandbox](/v1/guias/sandbox).
- [ ] En el ambiente de pruebas puedes llamar desde cualquier IP. En producción, la IP desde la que llamas debe estar registrada para tu API Key, como se explica en [Autenticación](/v1/guias/autenticacion).
- [ ] El valor `identificacion` de tu contribuyente, que obtienes con [`GET /v1/contexto`](/v1/guias/consulta-contexto). En los ejemplos es `0123456789001`.
- [ ] El tipo `05` habilitado para ese contribuyente, es decir, que aparezca en `tiposComprobante` del contexto.
- [ ] Los datos del documento modificado: tipo, número `ddd-ddd-ddddddddd` y fecha de emisión.

## Ejemplo mínimo

Este ejemplo es una nota de débito por intereses y gastos de cobranza sobre la
factura 001-001-000000123, con IVA 15 %. Guarda el JSON como
`comprobante.json`, porque lo usan los ejemplos de [Envío](#envio).

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "ND-2026-0001",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "001",
    "ptoEmi": "001",
    "secuencial": "000000000"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CLIENTE DE PRUEBAS",
    "codDocModificado": "01",
    "numDocModificado": "001-001-000000123",
    "fechaEmisionDocSustento": "01/10/2026",
    "totalSinImpuestos": 30.00,
    "impuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 30.00,
        "valor": 4.50
      }
    ],
    "valorTotal": 34.50,
    "pagos": [
      {
        "formaPago": "20",
        "total": 34.50,
        "plazo": 15,
        "unidadTiempo": "dias"
      }
    ]
  },
  "motivos": [
    {
      "razon": "INTERESES POR MORA",
      "valor": 20.00
    },
    {
      "razon": "GASTOS DE COBRANZA",
      "valor": 10.00
    }
  ],
  "infoAdicional": [
    {
      "nombre": "email",
      "valor": "cliente@example.com"
    }
  ]
}
```

Con `"secuencial": "000000000"` te asignamos el siguiente número de la serie
001-001 de notas de débito, y omitir el campo tiene el mismo efecto.

### Cómo se calculan los totales

| Paso | Cálculo | Resultado | Campo |
|---|---|---|---|
| 1. Suma los valores de los motivos (sin IVA) | 20.00 + 10.00 | 30.00 | `info.totalSinImpuestos` y `info.impuestos[0].baseImponible` |
| 2. IVA de cada motivo, redondeado a 2 decimales | 20.00 x 15 / 100 = 3.00; 10.00 x 15 / 100 = 1.50 | 3.00 y 1.50 | No se envía; solo lo calculas para sumarlo en el paso 3. |
| 3. Suma los IVA de los motivos | 3.00 + 1.50 | 4.50 | `info.impuestos[0].valor` |
| 4. Total de la nota | 30.00 + 4.50 | 34.50 | `info.valorTotal` |
| 5. Reparte el total en formas de pago | 34.50 | 34.50 | suma de `info.pagos[].total` |

El IVA se redondea **por motivo**, a 2 decimales y con la mitad hacia arriba, y
después se suma. Si lo calculas sobre el total y no por motivo, puede diferir en
un centavo, y la API responde 422.

## Envío

Envía el `comprobante.json` del ejemplo mínimo con cualquiera de estos
ejemplos. Todos usan como `Idempotency-Key` la misma `referenciaExterna`,
ND-2026-0001.

```bash
curl -s -i -X POST \
  "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-debito" \
  -H "X-Api-Key: $ECUAFACT_API_KEY" \
  -H "Idempotency-Key: ND-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-debito");
peticion.Headers.Add("Idempotency-Key", "ND-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-debito",
    headers={
        "X-Api-Key": os.environ["ECUAFACT_API_KEY"],
        "Idempotency-Key": "ND-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-debito',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ECUAFACT_API_KEY,
      'Idempotency-Key': 'ND-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-debito');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
        'Idempotency-Key: ND-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-debito"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .header("Idempotency-Key", "ND-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 System.Text.Json;
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

var client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

NotaDebitoRequest comprobante = JsonSerializer.Deserialize<NotaDebitoRequest>(
    await File.ReadAllTextAsync("comprobante.json"))!;

EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "ND-2026-0001");
Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}");
```

```python-sdk
import json
import os

from ecuafact import NotaDebitoRequest, EcuafactClient, EcuafactClientOptions

client = EcuafactClient(EcuafactClientOptions(
    base_address="https://api-sandbox.mynexusapi.com/",
    api_key=os.environ["ECUAFACT_API_KEY"],
))

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

resultado = client.emitir_en("0123456789001", comprobante, "ND-2026-0001")
print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}")
```

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

const client = new EcuafactClient({
  baseAddress: 'https://api-sandbox.mynexusapi.com/',
  apiKey: process.env.ECUAFACT_API_KEY
});

const comprobante = JSON.parse(await readFile('comprobante.json', 'utf8'));
const resultado = await client.emitirNotaDebitoEn('0123456789001', comprobante, 'ND-2026-0001');
console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`);
```

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

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

// $comprobante: NotaDebitoRequest con la estructura de esta pagina (como armarlo: SDK PHP).
$resultado = $client->emitirEn('0123456789001', $comprobante, 'ND-2026-0001');
echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL;
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.contracts.NotaDebitoRequest;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

NotaDebitoRequest comprobante = new ObjectMapper()
    .readValue(Files.readString(Path.of("comprobante.json")), NotaDebitoRequest.class);

EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "ND-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 nota.
ecuafact emitir comprobante.json --entorno sandbox
```

Si repites exactamente la misma solicitud, con la misma `Idempotency-Key` y el
mismo cuerpo, por ejemplo tras un timeout, la API no crea otra nota. Responde
202 con el mismo `idOperacion` y el estado actual de la operación.

## Estructura del comprobante

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

### Raíz

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `origenReferencia` | string | Sí | Nombre de tu sistema de origen, de hasta 64 caracteres entre letras y dígitos ASCII y `- _ . : /`. |
| `referenciaExterna` | string | Sí | Identificador estable del documento en tu sistema, de hasta 128 caracteres con el mismo alfabeto. Repítelo igual en cada reintento. |
| `infoTributaria` | object | Sí | Identidad del comprobante, descrita en la tabla `infoTributaria`. |
| `info` | object | Sí | Cabecera de la nota. Su detalle está en la tabla `info`. |
| `motivos` | array | Sí | De 1 a 1000 motivos. Su detalle está en la tabla `motivos`. |
| `infoAdicional` | array | No | Hasta 15 objetos `{nombre, valor}`. Su detalle está en la tabla `infoAdicional`. |

No envíes `detalles`, `destinatarios` ni `docsSustento`, porque son de otros
tipos y la API responde 422 con `Campo no soportado en este contrato.` Tampoco envíes `claveAcceso`, `ambiente`, `tipoEmision`,
`version` ni `formato`, porque la API no los admite.

### `infoTributaria`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `ruc` | string | Sí | RUC del emisor, de 5 a 13 dígitos. Debe ser igual a la `identificacion` de la ruta; por ejemplo, `0123456789001`. |
| `estab` | string | Sí | Código del [establecimiento](/v1/guias/glosario), de hasta 3 dígitos. Se completa con ceros, así que `"1"` se toma como `"001"`. |
| `ptoEmi` | string | Sí | Código del [punto de emisión](/v1/guias/glosario), de hasta 3 dígitos. |
| `secuencial` | string | No | Si lo omites o envías `"000000000"`, te asignamos el siguiente número de la serie, que forman `estab`, `ptoEmi`, el tipo `05` y el ambiente. Si envías un número de hasta 9 dígitos, entre 1 y 999999999, usamos ese número. |

El tipo de comprobante lo fija la ruta del endpoint, así que `infoTributaria` no
lleva `tipoDocumento`.

### `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. |
| `tipoIdentificacionComprador` | string | Sí | `04` RUC, `05` cédula, `06` pasaporte o `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í | Con `04`, 13 dígitos. Con `05`, 10 dígitos. Con otros tipos, hasta 20 caracteres. |
| `razonSocialComprador` | string | Sí | Nombre o razón social del comprador, hasta 300 caracteres. |
| `direccionComprador` | string | No | Hasta 300 caracteres. |
| `dirEstablecimiento` | string | No | Dirección del establecimiento emisor, hasta 300 caracteres. |
| `telefono` | string | No | Teléfono del comprador, hasta 40 caracteres. |
| `correo` | string | No | Correo del comprador al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se usa el `infoAdicional` llamado `email` o `correo`. |
| `codDocModificado` | string | Sí | Tipo del documento modificado, de 2 dígitos, como `01` para una factura. Los valores están en [Tipos de comprobante](/v1/guias/catalogos#tipos-de-comprobante). |
| `numDocModificado` | string | Sí | Número del documento modificado, `ddd-ddd-ddddddddd`, por ejemplo `001-001-000000123`. |
| `fechaEmisionDocSustento` | string | Sí | Fecha de emisión del documento modificado, `dd/MM/yyyy`. |
| `totalSinImpuestos` | number | Sí | Suma de `motivos[].valor`, con 2 decimales. |
| `impuestos` | array | Sí | Exactamente un IVA. Su detalle está en la tabla `info.impuestos`. |
| `valorTotal` | number | Sí | `totalSinImpuestos` + IVA, con 2 decimales. |
| `moneda` | string | No | `DOLAR` o `USD`. |
| `pagos` | array | Sí | De 1 a 20 formas de pago. Su detalle está en la tabla `info.pagos`. |

La nota de débito no usa `totalConImpuestos`, `valorModificacion`,
`totalDescuento`, `propina` ni `motivo` en singular, y si los envías, la API
responde 422 con `Campo no soportado en este contrato.`

### `motivos`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `razon` | string | Sí | Razón del débito, hasta 300 caracteres. La primera razón se usa como motivo del documento. |
| `valor` | number | Sí | Importe del motivo **sin IVA**, mayor o igual a 0 y con 2 decimales. |

### `info.impuestos`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `codigo` | string | Sí | `"2"`, que es el IVA y el único impuesto admitido en la nota de débito. |
| `codigoPorcentaje` | string | Sí | Código de la tarifa de IVA; `"4"` es 15 %. Los valores están en [Tarifas de IVA](/v1/guias/catalogos#tarifas-de-iva). |
| `tarifa` | number | Sí | Porcentaje de la tarifa, por ejemplo `15`. Con `codigoPorcentaje` `0`, `6` o `7` envía `0`; con cualquier otro, un valor mayor que 0. |
| `baseImponible` | number | Sí | Suma de `motivos[].valor`. |
| `valor` | number | Sí | Suma del IVA de cada motivo, calculado y redondeado por motivo. |

### `info.pagos`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `formaPago` | string | Sí | Código de 2 dígitos. Los valores están en [Formas de pago](/v1/guias/catalogos#formas-de-pago). |
| `total` | number | Sí | Importe pagado con esa forma. La suma de todos los `total` es igual a `valorTotal`. |
| `plazo` | number | No | Número entero mayor o igual a 0. |
| `unidadTiempo` | string | Condicional | Obligatoria si `plazo` es mayor que 0, por ejemplo `dias`, con hasta 20 caracteres. |

### `infoAdicional`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `nombre` | string | Sí | Nombre del dato, hasta 300 caracteres. |
| `valor` | string | Sí | Valor del dato, hasta 300 caracteres. |

Estos datos aparecen en el [RIDE](/v1/guias/glosario), el PDF del comprobante.

## Reglas de cálculo y validaciones

Si alguna regla falla, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`), y `errores`
describe la regla y, cuando aplica, el campo, como en `$.info: Base o valor de impuestos no coincide con detalles.`
Un 422 consume 1 documento como intento, pero no usa un número de la serie, así que corrige el dato y
reenvía.

| Regla | Ejemplo de incumplimiento |
|---|---|
| `info.impuestos` lleva un único elemento con `codigo` `"2"`. | Enviar IVA e ICE, o dos tarifas de IVA. |
| `totalSinImpuestos` = `impuestos[0].baseImponible` = suma de `motivos[].valor`. | Motivos que suman 30.00 y `totalSinImpuestos` 34.50. |
| `impuestos[0].valor` = suma de `redondear(motivo.valor x tarifa / 100, 2)`. | Calcular 4.51 por redondear sobre otro valor. |
| `valorTotal` = `totalSinImpuestos` + `impuestos[0].valor`. | `valorTotal` sin el IVA. |
| Suma de `pagos[].total` = `valorTotal`. | Pagos por 30.00 con `valorTotal` 34.50. |
| Los importes llevan como máximo 2 decimales y la API no los redondea por ti. | `valor: 10.005`. |
| El comprador está identificado; no se admite `07`. | Nota de débito a consumidor final. |
| `numDocModificado` tiene el formato `ddd-ddd-ddddddddd`. | `001001123`. |
| Las fechas van en `dd/MM/yyyy`. | `2026-10-07`. |
| Solo se envían los campos de la nota de débito. | Enviar `detalles` o `info.totalConImpuestos`. |

## Respuesta

Si la solicitud es válida, la API responde 202 Accepted. El comprobante quedó
**recibido**, pero todavía no tiene el resultado del SRI.

```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": "05",
  "numeroDocumento": "001-001-000000001",
  "referenciaExterna": "ND-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](/v1/guias/glosario). Guárdalo, porque lo necesitas 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.

La respuesta trae además estas cabeceras:

| Cabecera | Descripción |
|---|---|
| `Location` | La misma URL completa que `urlEstado`. |
| `X-Correlation-Id` | Identificador de correlación de la solicitud. Cítalo al pedir soporte. |

Después de recibirla, sigue estos pasos:

1. Guarda `idOperacion` junto a la nota en tu sistema.
2. Consulta `GET /v1/operaciones/{idOperacion}`, como se explica en [Seguimiento de una operación](/v1/guias/consulta-operacion), o espera el [webhook](/v1/guias/webhooks).
3. Cuando su `estado` sea `autorizado`, la operación trae la `claveAcceso` real de 49 dígitos y puedes descargar el RIDE y el XML. Si es `rechazado` o `rechazo_configuracion`, el `codEstado` te dice la causa y `errores` el detalle; corrígela y emite de nuevo con una `Idempotency-Key` nueva y una `referenciaExterna` nueva. Si el `codEstado` es 3001 (`rechazo_sri`), usa además el secuencial automático, como se explica en [Reintentos y duplicados](/v1/guias/emision#reintentos-y-duplicados).

## Estados de este endpoint

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

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 1001 o 1002 | 202 | La nota 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 | Falta `Idempotency-Key` o no es ASCII de hasta 128 caracteres, o el JSON o el XML está mal formado. | Corrige la solicitud según `errores` y reenvía. |
| 3002 (`comprobante_invalido`) | 422 | Falta un campo obligatorio, un campo tiene formato inválido (letras en `estab`, `ruc` fuera de 5 a 13 dígitos, fecha que no es `dd/MM/yyyy`) o no se cumple una regla de la nota (totales, IVA, campos de otro tipo, campo desconocido, `ruc` que no corresponde a la ruta). | Corrige el campo indicado en `errores`. Consume 1 documento como intento. |
| 3006 (`cuerpo_excedido`) | 413 | El cuerpo supera 2 MiB. | Reduce `infoAdicional` o el número de motivos. |
| 3009 (`credenciales_invalidas`) | 401 | La API Key falta o no es válida. | Revisa `X-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 revisa proxies entre tu sistema y la API. |
| 3011 (`acceso_denegado`) | 403 | El contribuyente de la ruta o el tipo `05` no están habilitados. | Verifica `GET /v1/contexto`; si falta el tipo, solicita habilitarlo. |
| 3004 (`comprobante_duplicado`) | 409 | Ya existe una nota de débito 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. |
| 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`. |
| 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera lo que indique `Retry-After` y reintenta con la misma `Idempotency-Key`. |
| 4004 (`cupo_agotado`) | 429 | Se agotó el cupo de documentos. | Revisa [`GET /v1/consumo`](/v1/guias/consumo) y compra un paquete. |
| 5002 (`servicio_no_disponible`) | 503 | El servicio no está disponible temporalmente. | Reintenta con la misma `Idempotency-Key` y el mismo cuerpo. |

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).

> [!WARNING]
> Ante un timeout, reintenta con la **misma** `Idempotency-Key` y el mismo cuerpo. Cambiar la clave o la `referenciaExterna` puede emitir dos notas de débito.

## Siguientes pasos

- [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta si el SRI autorizó la nota y obtiene su clave de acceso.
- [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar periódicamente.
- [Nota de crédito](/v1/guias/emision-04): disminuye el valor de un comprobante en lugar de aumentarlo.
- [Catálogos](/v1/guias/catalogos): códigos de identificación, tarifas de IVA y formas de pago.
