En esta página
Nota de crédito POST
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 automático 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.
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.
Conceptos#
La factura a la que apunta la nota de crédito es el documento modificado o sustento. 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, 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.
{
"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.
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.
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}
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()}");
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)
// 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
$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;
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());
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}");
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}")
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
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;
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());
# 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. 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. |
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. |
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. 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. |
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.
{
"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.
{
"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:
{
"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, 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} o espera el
webhook. 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. |
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.
Siguientes pasos#
- Seguimiento de una operación: confirma si el SRI autorizó la nota.
- Factura: repasa los campos y cálculos de la factura que modificas.
- Nota de débito: cobra un valor adicional sobre una factura.
- Descarga el ejemplo de solicitud: cuerpo de nota de crédito listo para ensayar.