Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Nota de débito POST

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.

Importante

Ambiente de pruebas: sin validez fiscal. Los ejemplos usan https://api-sandbox.mynexusapi.com y los 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.

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, secuencial, clave de acceso o RIDE, están explicados en el 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.

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.
  • 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.
  • El valor identificacion de tu contribuyente, que obtienes con GET /v1/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.

{
  "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.

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}
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()}");
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)
// 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
$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;
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());
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}");
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}")
// 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
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;
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());
# 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, 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, 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. 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.
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.
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.
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, 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.

{
  "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. 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, 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, o espera el webhook.
  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.

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

Atención

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#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.