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 ennumDocModificadoy su fecha enfechaEmisionDocSustento. 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
motivosuna 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
identificacionde tu contribuyente, que obtienes conGET /v1/contexto. En los ejemplos es0123456789001. - El tipo
05habilitado para ese contribuyente, es decir, que aparezca entiposComprobantedel contexto. - Los datos del documento modificado: tipo, número
ddd-ddd-dddddddddy 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:
- Guarda
idOperacionjunto a la nota en tu sistema. - Consulta
GET /v1/operaciones/{idOperacion}, como se explica en Seguimiento de una operación, o espera el webhook. - Cuando su
estadoseaautorizado, la operación trae laclaveAccesoreal de 49 dígitos y puedes descargar el RIDE y el XML. Si esrechazadoorechazo_configuracion, elcodEstadote dice la causa yerroresel detalle; corrígela y emite de nuevo con unaIdempotency-Keynueva y unareferenciaExternanueva. Si elcodEstadoes 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#
- Seguimiento de una operación: consulta si el SRI autorizó la nota y obtiene su clave de acceso.
- Webhooks: recibe el resultado sin consultar periódicamente.
- Nota de crédito: disminuye el valor de un comprobante en lugar de aumentarlo.
- Catálogos: códigos de identificación, tarifas de IVA y formas de pago.