En esta página
Comprobantes electrónicos POST
Emite los seis comprobantes del SRI con una ruta por tipo y una estructura JSON común, y sigue después su autorización.
Puedes emitir todos los comprobantes electrónicos, desde la factura hasta el
comprobante de retención, con el mismo flujo. Eliges la ruta según el tipo,
envías el JSON del comprobante, la API lo valida y te responde 202 Accepted
con un idOperacion; el resultado del SRI llega después, y puedes consultarlo o
recibirlo por webhook.
En esta página encuentras lo que comparten los seis tipos: las rutas y sus cabeceras, la estructura del cuerpo, las reglas de formato, cómo cuadrar los totales, la respuesta, cómo validar un comprobante sin emitirlo, los mensajes de validación y cómo reintentar sin emitir dos veces. Los campos propios de cada tipo están en su guía, que encuentras en Cómo elegir el tipo de comprobante.
Importante
Ambiente de pruebas: sin validez fiscal. Todos los ejemplos de esta página usan
https://api-sandbox.mynexusapi.com y los datos de prueba.
Para agentes#
Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.
Pega este prompt en un agente de programación con acceso a la terminal:
Construye en este proyecto la emisión de comprobantes con la API de Ecuafact y valida un comprobante de prueba antes de emitirlo. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, instálala con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/emision.md antes de escribir código; no inventes campos. Reutiliza el lenguaje y el SDK de Ecuafact que el proyecto ya use; si no usa ninguno, recomiéndame el SDK de su lenguaje (o el CLI ecuafact para probar, o el MCP para operar mi cuenta), con una frase de motivo y espera mi respuesta; HTTP directo solo si lo prefiero. Averigua de dónde salen los datos en este proyecto y mapea cada dato a la guía, sin inventar campos: el tipo se elige con la guía de su comprobante, los importes se calculan con las reglas de la guía y el secuencial puede omitirse. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno; nunca la pegues en el chat ni la imprimas. Valida con POST /v1/contribuyentes/{identificacion}/{tipo}/validar antes de emitir, donde {tipo} es la ruta del comprobante (facturas, liquidaciones-compra, notas-credito, notas-debito, guias-remision, retenciones), y no envíes infoTributaria.tipoDocumento en el cuerpo; solo si valida, emite con POST /v1/contribuyentes/{identificacion}/{tipo}, una Idempotency-Key estable y una referenciaExterna propia. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide siempre por estado y codEstado, usa urlEstado tal cual y lee errores como arreglo. Ejecuta una validación y una emisión de prueba e informa solo el resultado de la validación, el estado y el codEstado de la emisión, y cualquier acción que yo deba hacer.
Conceptos#
Si ya emitiste comprobantes electrónicos, puedes pasar directamente al Endpoint. Si no, estos son los conceptos que usa el resto de la página.
- Un comprobante electrónico es el documento fiscal que el SRI, la autoridad tributaria del Ecuador, debe autorizar para que tenga validez. Puede ser una factura, una liquidación de compra, una nota de crédito, una nota de débito, una guía de remisión o un comprobante de retención.
- La emisión es asíncrona. Tú envías el comprobante, la API lo valida y responde 202 Accepted, con lo que el comprobante queda recibido, todavía no autorizado. El resultado del SRI llega segundos o minutos después, y lo conoces por seguimiento o por webhook.
- Cada comprobante tiene un número con la forma
estab-ptoEmi-secuencial, por ejemplo002-001-000000124. Se compone del establecimiento y el punto de emisión, de 3 dígitos cada uno, y del secuencial, un consecutivo de 9 dígitos dentro de esa serie. - La clave de acceso es el número de 49 dígitos que identifica al comprobante ante el SRI. No la envías: te la asignamos nosotros y la ves en el seguimiento o en el webhook.
- El RIDE, el PDF del comprobante, se descarga cuando el comprobante ya está autorizado.
Endpoint#
La emisión tiene una ruta por tipo de comprobante. El tipo lo fija la ruta y no
el cuerpo: no envíes infoTributaria.tipoDocumento, y info solo lleva los
campos de ese tipo. Elige la ruta según el comprobante que emites.
| Tipo | Código | Ruta de emisión | Ruta de validación |
|---|---|---|---|
| Factura | 01 |
POST /v1/contribuyentes/{identificacion}/facturas |
POST /v1/contribuyentes/{identificacion}/facturas/validar |
| Liquidación de compra | 03 |
POST /v1/contribuyentes/{identificacion}/liquidaciones-compra |
POST /v1/contribuyentes/{identificacion}/liquidaciones-compra/validar |
| Nota de crédito | 04 |
POST /v1/contribuyentes/{identificacion}/notas-credito |
POST /v1/contribuyentes/{identificacion}/notas-credito/validar |
| Nota de débito | 05 |
POST /v1/contribuyentes/{identificacion}/notas-debito |
POST /v1/contribuyentes/{identificacion}/notas-debito/validar |
| Guía de remisión | 06 |
POST /v1/contribuyentes/{identificacion}/guias-remision |
POST /v1/contribuyentes/{identificacion}/guias-remision/validar |
| Comprobante de retención | 07 |
POST /v1/contribuyentes/{identificacion}/retenciones |
POST /v1/contribuyentes/{identificacion}/retenciones/validar |
Todas las rutas usan las mismas cabeceras. El siguiente es el ejemplo de una
factura; cambia facturas por el segmento del tipo que emites.
POST /v1/contribuyentes/{identificacion}/facturas
X-Api-Key: <API Key>
Idempotency-Key: <valor estable por intencion>
Content-Type: application/json
| Nombre | Dónde | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
identificacion |
Ruta | string | Sí | El valor contribuyentes[].identificacion de GET /v1/contexto. Es la identificación completa del contribuyente, la misma que envías en infoTributaria.ruc; en pruebas, 0123456789001. |
X-Api-Key |
Cabecera | string | Sí | Tu API Key. |
Idempotency-Key |
Cabecera | string | Sí | Identifica la intención de emitir este comprobante. Admite hasta 128 caracteres entre letras y dígitos ASCII y - _ . : /. Su uso se explica en Reintentos y duplicados. |
Content-Type |
Cabecera | string | Sí | application/json, o application/xml / text/xml si envías el XML del SRI. |
X-Additional-Info |
Cabecera | string | No | Texto tuyo que identifica la solicitud cuando pides soporte. Sus reglas están en Límites. |
El cuerpo admite hasta 2 MiB y 32 niveles de anidamiento JSON. Si es mayor, la
API responde 413 con el codEstado 3006 (cuerpo_excedido).
Cuerpo JSON o XML#
Los seis endpoints de emisión y sus seis validaciones aceptan el mismo
comprobante en JSON o en el XML del SRI. En los dos casos la ruta fija el tipo,
y el Content-Type de tu petición indica el formato del cuerpo.
| Regla | JSON | XML |
|---|---|---|
Content-Type |
application/json |
application/xml o text/xml |
| Tipo de comprobante | Lo fija la ruta | La raíz y infoTributaria.codDoc deben coincidir con la ruta |
| Tamaño máximo | 2 MiB | 2 MiB |
| Validación, cupo e idempotencia | Sí | Sí, con las mismas reglas |
| Firma | La hace la plataforma | Se ignora la firma del XML; la plataforma vuelve a firmar |
origenReferencia |
Lo envías tú | xml-sri |
referenciaExterna |
La envías tú | La claveAcceso si no es cero; si no, codDoc-estab-ptoEmi-secuencial |
El XML puede estar firmado o sin firmar, porque la API descarta <ds:Signature>.
En infoTributaria puedes dejar los elementos propios del XML del SRI
(ambiente, tipoEmision, razonSocial, nombreComercial, claveAcceso,
codDoc, dirMatriz, agenteRetencion, contribuyenteRimpe y
regimenMicroempresas), que se ignoran. Cualquier otro elemento que no
pertenezca al contrato se rechaza con un 400 y el codEstado 3003
(solicitud_invalida). La retención debe usar el XML 2.0 con docsSustento; el
XML 1.0 que trae impuestos en la raíz responde 422 con el codEstado 3002
(comprobante_invalido).
curl -X POST "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \
-H "X-Api-Key: $ECUAFACT_API_KEY" \
-H "Idempotency-Key: factura-xml-001" \
-H "Content-Type: application/xml" \
--data-binary @factura.xml
La respuesta es la misma que con JSON: un 202 con el estado recibido o el
rechazo con su codEstado. En las rutas /validar el XML se envía igual y la
Idempotency-Key se ignora.
Antes de empezar#
- Una API Key de pruebas. 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; si no lo está, la API responde 403 con el
codEstado3010 (ip_no_autorizada). - La
identificaciondel contribuyente, que obtienes deGET /v1/contexto. - El tipo de comprobante habilitado, es decir, que aparezca en
contribuyentes[].tiposComprobantedel contexto. - La variable de entorno
ECUAFACT_API_KEYcon tu API Key, para ejecutar los ejemplos.
Cómo elegir el tipo de comprobante#
Elige el tipo según lo que necesitas documentar. Cada uno tiene su guía, con sus campos propios y un ejemplo completo listo para copiar.
| Si quieres... | Emite | Código SRI | Guía |
|---|---|---|---|
| Cobrar una venta de bienes o servicios | Factura | 01 |
Factura |
| Documentar una compra a quien no puede emitirte factura (persona natural sin RUC, proveedor del exterior sin domicilio en Ecuador) | Liquidación de compra | 03 |
Liquidación de compra |
| Devolver dinero, aplicar un descuento posterior o anular total o parcialmente una factura ya autorizada | Nota de crédito | 04 |
Nota de crédito |
| Cobrar un valor adicional sobre una factura ya emitida (intereses por mora, recargos, gastos de cobranza) | Nota de débito | 05 |
Nota de débito |
| Acompañar el traslado de mercadería de un lugar a otro | Guía de remisión | 06 |
Guía de remisión |
| Dejar constancia de los impuestos que retienes al pagar a un proveedor | Comprobante de retención | 07 |
Comprobante de retención |
Un comprobante autorizado no se edita. Si una factura autorizada tiene un error, revierte su efecto con una nota de crédito y, si corresponde, emite una factura nueva y correcta.
Estructura del comprobante#
Todos los tipos usan la misma estructura JSON. El tipo lo fija la ruta que
llamas, así que el cuerpo no lleva infoTributaria.tipoDocumento. Lo que cambia
de un tipo a otro son los campos que admite info y la colección de líneas.
| Clave | Tipo | Obligatorio | Contenido |
|---|---|---|---|
origenReferencia |
string | Sí | Nombre estable del sistema que emite, por ejemplo MiERP. Se explica en origenReferencia y referenciaExterna. |
referenciaExterna |
string | Sí | Identificador del documento en tu sistema, por ejemplo FACTURA-2026-0001. |
infoTributaria |
object | Sí | Identidad del comprobante: emisor y serie. Sus campos están en la tabla siguiente. |
info |
object | Sí | Cabecera del comprobante. Solo admite los campos del tipo de la ruta; con un campo de otro tipo, la API responde 422. |
detalles |
array | Según tipo | Líneas de factura (01), liquidación de compra (03) y nota de crédito (04). |
motivos |
array | Según tipo | Motivos de la nota de débito (05). |
destinatarios |
array | Según tipo | Destinatario y mercadería de la guía de remisión (06). |
docsSustento |
array | Según tipo | Documento sustento y retenciones del comprobante de retención (07). |
infoAdicional |
array | No | Hasta 15 objetos { "nombre", "valor" } (cada uno de 1 a 300 caracteres) que se imprimen en el RIDE. |
Si envías una colección que no corresponde al tipo, por ejemplo motivos en una
factura, la API responde 422 con el codEstado 3002 (comprobante_invalido) y el
mensaje $.motivos: Campo no soportado en este contrato.
infoTributaria#
El tipo de comprobante no va en este objeto: lo fija la ruta. Envía solo el RUC del emisor y la serie del documento.
| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
ruc |
string | Sí | RUC del emisor, de 5 a 13 dígitos. Envía la misma identificacion de la ruta, que es la identificación completa del contexto; en pruebas, 0123456789001. Si es distinto de la identificación de la ruta, la API responde 422 con el codEstado 3002 (comprobante_invalido). |
estab |
string | Sí | Establecimiento, de hasta 3 dígitos. Se completa con ceros a la izquierda, así que 2 se toma como 002. |
ptoEmi |
string | Sí | Punto de emisión, de hasta 3 dígitos. Se completa con ceros a la izquierda. |
secuencial |
string | No | Secuencial, de hasta 9 dígitos, entre 1 y 999999999. Omítelo y te asignamos el siguiente, como se explica en Secuencial automático. |
No envíes tipoDocumento, claveAcceso, ambiente, tipoEmision, version ni
formato, ni en la raíz ni en infoTributaria. La API no admite esos campos y
responde 422 con el codEstado 3002 (comprobante_invalido), con un detalle en
errores como "$.infoTributaria.tipoDocumento: Campo no soportado en este contrato.".
El tipo lo fija la ruta y el ambiente lo define la URL que llamas; la validación
sin emitir aplica la misma regla.
Qué cambia por tipo#
Cada tipo usa una contraparte, una colección de líneas y una regla de pagos propias. La tabla resume esas diferencias.
| Tipo | Contraparte en info |
Colección | Pagos (info.pagos) |
|---|---|---|---|
01 Factura |
...Comprador (quien te compra) |
detalles con codigoPrincipal |
Obligatorio |
03 Liquidación de compra |
...Proveedor (a quien compras) |
detalles con codigoPrincipal |
Obligatorio |
04 Nota de crédito |
...Comprador de la factura original |
detalles con codigoInterno |
No se envía |
05 Nota de débito |
...Comprador |
motivos |
Obligatorio |
06 Guía de remisión |
Transportista | destinatarios |
No se envía |
07 Comprobante de retención |
...SujetoRetenido |
docsSustento |
Dentro del sustento |
Secuencial automático#
El secuencial es el contador del comprobante dentro de una serie, y puedes
dejar que te lo asignemos o enviar el tuyo. Una serie es la combinación de RUC +
estab + ptoEmi + tipo de comprobante + ambiente: cada serie lleva su propio contador, y
el de pruebas es independiente del de producción.
Lo que envías en secuencial |
Qué número recibe el comprobante |
|---|---|
Nada (omites el campo), "" o solo ceros ("000000000") |
Te asignamos el siguiente número libre de la serie. Te recomendamos esta opción, porque no necesitas llevar el contador en tu sistema. |
Un número ("124" o "000000124") |
Usamos ese número, completado a 9 dígitos. |
Para conocer el número asignado, búscalo en
el seguimiento, que lo devuelve en
numeroDocumento (002-001-000000124). La claveAcceso que trae el
seguimiento, cuando el comprobante ya la tiene, también contiene el secuencial.
Nota
Te recomendamos usar un solo modo por serie. Si mezclas números propios con el automático, el
automático continúa desde el mayor número usado y tus números propios pueden
chocar con uno ya emitido; en ese caso la API responde 409 con el codEstado 3004 (comprobante_duplicado).
origenReferencia y referenciaExterna#
Son los identificadores de tu sistema. Con ellos puedes encontrar la operación desde tu ERP, evitar emitir dos veces el mismo documento y cruzar el comprobante con tu registro contable.
| Campo | Para qué sirve | Formato | Ejemplos |
|---|---|---|---|
origenReferencia |
Nombra el sistema o módulo que emite. Usa siempre el mismo valor desde el mismo sistema. | 1 a 64 caracteres: letras y dígitos ASCII y - _ . : /. Sin espacios. |
MiERP, tienda-web, pos.local-03 |
referenciaExterna |
Identifica el documento dentro de ese sistema, como tu número interno de factura, pedido o nota. | 1 a 128 caracteres, con el mismo alfabeto. | FACTURA-2026-0001, PED/2026/10/0457, NC-00031 |
La pareja origenReferencia + referenciaExterna es única por contribuyente
emisor y por ambiente, y vale para todas las API Key de tu integración: dos RUC
de tu integración pueden usar la misma referencia. Si envías la
misma pareja con el mismo cuerpo, la API la trata como un reintento y
responde 202 con la misma operación. Si la envías con otro cuerpo, responde
409 con el codEstado 3005 (conflicto_idempotencia). Por eso, para corregir un comprobante
rechazado, usa una referenciaExterna nueva, por ejemplo
FACTURA-2026-0001-R1.
Reglas de formato#
Cada dato del comprobante tiene un formato fijo, y la API responde 422 a cualquier valor que no lo cumpla.
| Dato | Formato | Ejemplo correcto | Error común |
|---|---|---|---|
Importes (total, valor, baseImponible...) |
Número JSON con punto decimal y como máximo 2 decimales. | 52.44 |
"52,44" o 52.444 |
cantidad, precioUnitario |
Número JSON, hasta 6 decimales. | 1.0112 |
1.0112345 |
tarifa |
Número JSON de 0 a 99.99, hasta 2 decimales, igual a la tarifa del codigoPorcentaje en el catálogo del SRI. |
15 |
0.15 (es porcentaje, no fracción) |
Códigos (codigoPorcentaje, formaPago, tipos de identificación) |
Cadena JSON. | "01" |
1 (número) |
Identificaciones (ruc, identificacionComprador) |
Cadena de dígitos. | "0123456789" |
123456789 (pierde el cero inicial) |
Fechas fiscales (fechaEmision, fechaEmisionDocSustento) |
dd/MM/yyyy, del 01/01/2000 al 31/12/2099. Envía en fechaEmision la fecha de hoy, porque, salvo en la retención, el comprobante autorizado lleva la fecha del día en que se procesa aunque envíes otra. |
"07/10/2026" |
"2026-10-07" |
| Periodo fiscal (retención) | MM/yyyy. |
"10/2026" |
"2026-10" |
Número de un documento (numDocModificado) |
ddd-ddd-ddddddddd. |
"002-001-000000123" |
"123" (solo el secuencial) |
| Textos | Sin caracteres de control, como saltos de línea o tabuladores, y dentro del máximo de cada campo, que indica la guía de cada tipo. Ningún texto supera 500 caracteres. | "CONSULTORIA MENSUAL" |
Texto vacío o solo espacios en un campo obligatorio |
| Campos de cada objeto | Exactamente los nombres documentados, una sola vez. | "precioUnitario" |
Un campo desconocido o repetido, que la API rechaza con un 422 |
Un número obligatorio que omites no se toma como cero: la API responde 422 con
Campo obligatorio. Por eso, cuando el valor es cero, envía 0 de forma
explícita.
Cómo calcular los totales#
Esta sección cuadra paso a paso los totales de una factura con tres líneas: una con descuento, una con un precio de 4 decimales y una con IVA 0 %. Las reglas son las mismas para la liquidación de compra y, sin propina ni pagos, para la nota de crédito.
Reglas#
| Valor | Fórmula | Redondeo |
|---|---|---|
precioTotalSinImpuesto de la línea |
cantidad x precioUnitario - descuento |
A 2 decimales. |
descuento de la línea |
Importe en dólares, no porcentaje. Un 10 % sobre 37.50 se envía como 3.75. |
Ya con 2 decimales. |
baseImponible del IVA de la línea |
Igual a precioTotalSinImpuesto (más el ICE de la línea, si lo hay). |
2 decimales. |
valor del IVA de la línea |
(cantidad x precioUnitario - descuento) x tarifa / 100, calculado con la base sin redondear. |
A 2 decimales; el 5 sube (0.455 -> 0.46). |
totalConImpuestos[] (cabecera) |
Una fila por cada pareja codigo + codigoPorcentaje: baseImponible = suma de las bases de esas líneas; valor = suma de los valor de esas líneas. |
Suma, sin recalcular. Máximo 2 filas. |
totalSinImpuestos |
Suma de precioTotalSinImpuesto de todas las líneas (ya con el descuento restado). |
Suma. |
totalDescuento |
Suma de descuento de todas las líneas. |
Suma. |
importeTotal |
totalSinImpuestos + suma de los IVA + suma de los ICE + propina. |
Suma. |
pagos[].total |
La suma de todos los pagos es igual a importeTotal. |
Suma. |
Calcula todos los valores en tu sistema antes de enviarlos. La API no calcula ni corrige ninguno: compara lo que envías con estas fórmulas y, si algo no cuadra al centavo, responde 422.
Paso 1: cada línea#
| Línea | Cantidad x precio | Descuento | precioTotalSinImpuesto |
Tarifa | IVA (valor) |
|---|---|---|---|---|---|
| 1. Consultoría | 3 x 12.50 = 37.50 | 2.50 | 37.50 - 2.50 = 35.00 | 15 % (codigoPorcentaje 4) |
35.00 x 15 / 100 = 5.25 |
| 2. Repuesto | 3 x 1.0112 = 3.0336 | 0 | 3.0336 -> 3.03 | 15 % (4) |
3.0336 x 15 / 100 = 0.45504 -> 0.46 |
| 3. Libro | 2 x 4.35 = 8.70 | 0 | 8.70 | 0 % (0) |
0 |
En la línea 2, el IVA se calcula sobre 3.0336, la base sin redondear, y da
0.46. Si lo calcularas sobre 3.03 daría 0.45, y la API respondería
Valor de impuesto no coincide con base y tasa.
Paso 2: impuestos de cabecera#
Agrupa las líneas por codigo + codigoPorcentaje y suma sus bases y sus
valores.
| Grupo | baseImponible |
valor |
|---|---|---|
IVA 15 % (2 + 4) |
35.00 + 3.03 = 38.03 | 5.25 + 0.46 = 5.71 |
IVA 0 % (2 + 0) |
8.70 | 0 |
El valor de cabecera es la suma de los valores de las líneas, 5.71, y no el
15 % de 38.03, que daría 5.70.
Paso 3: totales y pagos#
| Campo | Cálculo | Valor |
|---|---|---|
totalSinImpuestos |
35.00 + 3.03 + 8.70 | 46.73 |
totalDescuento |
2.50 + 0 + 0 | 2.50 |
propina |
Sin propina | 0 |
importeTotal |
46.73 + 5.71 + 0 | 52.44 |
pagos |
20.00 en efectivo (01) + 32.44 con tarjeta de crédito (19) |
52.44 |
El comprobante completo#
Este es el comprobante con los totales del ejemplo. Guárdalo como
comprobante.json, porque lo usan los ejemplos de la sección siguiente.
{
"origenReferencia": "MiERP",
"referenciaExterna": "FACTURA-2026-0001",
"infoTributaria": {
"ruc": "0123456789001",
"estab": "002",
"ptoEmi": "001"
},
"info": {
"fechaEmision": "07/10/2026",
"tipoIdentificacionComprador": "05",
"identificacionComprador": "0123456789",
"razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
"direccionComprador": "DIRECCION DE PRUEBAS",
"totalSinImpuestos": 46.73,
"totalDescuento": 2.50,
"totalConImpuestos": [
{
"codigo": "2",
"codigoPorcentaje": "4",
"tarifa": 15,
"baseImponible": 38.03,
"valor": 5.71
},
{
"codigo": "2",
"codigoPorcentaje": "0",
"tarifa": 0,
"baseImponible": 8.70,
"valor": 0
}
],
"propina": 0,
"importeTotal": 52.44,
"moneda": "DOLAR",
"pagos": [
{
"formaPago": "01",
"total": 20.00
},
{
"formaPago": "19",
"total": 32.44
}
]
},
"detalles": [
{
"codigoPrincipal": "SERV-001",
"descripcion": "CONSULTORIA",
"cantidad": 3,
"precioUnitario": 12.50,
"descuento": 2.50,
"precioTotalSinImpuesto": 35.00,
"impuestos": [
{
"codigo": "2",
"codigoPorcentaje": "4",
"tarifa": 15,
"baseImponible": 35.00,
"valor": 5.25
}
]
},
{
"codigoPrincipal": "REP-002",
"descripcion": "REPUESTO",
"cantidad": 3,
"precioUnitario": 1.0112,
"descuento": 0,
"precioTotalSinImpuesto": 3.03,
"impuestos": [
{
"codigo": "2",
"codigoPorcentaje": "4",
"tarifa": 15,
"baseImponible": 3.03,
"valor": 0.46
}
]
},
{
"codigoPrincipal": "LIB-003",
"descripcion": "LIBRO",
"cantidad": 2,
"precioUnitario": 4.35,
"descuento": 0,
"precioTotalSinImpuesto": 8.70,
"impuestos": [
{
"codigo": "2",
"codigoPorcentaje": "0",
"tarifa": 0,
"baseImponible": 8.70,
"valor": 0
}
]
}
],
"infoAdicional": [
{
"nombre": "Pedido",
"valor": "PED-2026-0457"
}
]
}
El comprobante no lleva secuencial, así que te asignamos el siguiente número
de la serie 002-001. Los códigos de tarifa están en
Catálogos: tarifas de IVA y los de pago en
Catálogos: formas de pago.
Ejemplo de emisión#
Con el JSON de El comprobante completo guardado como
comprobante.json, ejecuta uno de estos ejemplos. Todos envían la misma
Idempotency-Key, así que si repites la petición no se emite un segundo
comprobante.
curl -s -i -X POST \
"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \
-H "X-Api-Key: $ECUAFACT_API_KEY" \
-H "Idempotency-Key: FACTURA-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/facturas");
peticion.Headers.Add("Idempotency-Key", "FACTURA-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/facturas",
headers={
"X-Api-Key": os.environ["ECUAFACT_API_KEY"],
"Idempotency-Key": "FACTURA-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/facturas',
{
method: 'POST',
headers: {
'X-Api-Key': process.env.ECUAFACT_API_KEY,
'Idempotency-Key': 'FACTURA-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/facturas');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
'Idempotency-Key: FACTURA-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/facturas"))
.header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
.header("Idempotency-Key", "FACTURA-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: FacturaRequest con la Estructura del comprobante
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001");
Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado} / codEstado: {resultado.Admission.CodEstado}");
from ecuafact import EcuafactClient
# client: EcuafactClient creado con tu API Key (ver SDK Python)
# comprobante: FacturaRequest con la Estructura del comprobante
resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001")
print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado} / codEstado: {resultado.admission.cod_estado}")
import { EcuafactClient } from "@ecuafact/sdk";
// client: EcuafactClient creado con tu API Key (ver SDK Node.js)
// comprobante: FacturaRequest con la Estructura del comprobante
const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001");
console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado} / codEstado: ${resultado.admission.codEstado}`);
<?php
use Ecuafact\Sdk\EcuafactClient;
// $client: EcuafactClient creado con tu API Key (ver SDK PHP)
// $comprobante: FacturaRequest con la Estructura del comprobante
$resultado = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001');
echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado
. ' / codEstado: ' . $resultado->admission->codEstado . PHP_EOL;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EmisionResultado;
// client: EcuafactClient creado con tu API Key (ver SDK Java)
// comprobante: FacturaRequest con la Estructura del comprobante
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado()
+ " / codEstado: " + resultado.admission().codEstado());
# Resultado esperado: una fila con el estado recibido y el idOperacion de la emisión.
ecuafact emitir comprobante.json --entorno sandbox
Si no le pasas la Idempotency-Key, el SDK la genera por ti y la devuelve en
EmisionResultado. Guárdala, porque debes reutilizarla en cualquier reintento.
Respuesta#
La API responde 202 Accepted con este cuerpo, que tiene la misma forma del seguimiento de la operación:
{
"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": "01",
"numeroDocumento": "002-001-000000124",
"referenciaExterna": "FACTURA-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 del SRI. |
codEstado |
number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Tu sistema debe aceptar los dos valores. |
errores |
array de string | Viene siempre; en una emisión recibida es una lista vacía. |
idOperacion |
string (UUID) | Identificador de la operación. Guárdalo junto a tu documento, porque lo necesitas para el seguimiento y llega en el webhook. |
urlEstado |
string | URL completa del seguimiento, https://<URL del ambiente>/v1/operaciones/{idOperacion}. Puedes llamarla tal como viene. |
ambiente |
number | 1 para pruebas y 2 para producción, según la URL que llamaste. |
tipoDocumento |
string | Tipo de comprobante: 01, 03, 04, 05, 06 o 07. |
numeroDocumento |
string o null |
Número del comprobante con la forma estab-ptoEmi-secuencial. Si omitiste el secuencial, aquí ves el que te asignamos. |
referenciaExterna |
string o null |
La referenciaExterna que enviaste. |
claveAcceso |
string o null |
Clave de acceso de 49 dígitos. Es null con el codEstado 1001 y viene con el 1002. Si es null, la obtienes después en el seguimiento o en el webhook. |
fhRecibido |
string | Fecha y hora en que recibimos la emisión, en ISO 8601 con la zona horaria de Ecuador. |
fhAutorizacion |
string o null |
Fecha y hora de autorización; en el 202 de una emisión nueva es null. |
El campo msgError no aparece porque la emisión no tiene error. Te recomendamos
leer el 202 con la misma lógica que el seguimiento: decide con estado y
codEstado y trata la claveAcceso como opcional mientras el estado sea
recibido.
| Cabecera | Descripción |
|---|---|
Location |
La misma URL completa que urlEstado. |
X-Correlation-Id |
Identificador de la petición. Inclúyelo si pides soporte. |
Un reintento con la misma Idempotency-Key y el mismo cuerpo, o con la misma
origenReferencia + referenciaExterna y el mismo cuerpo, responde un 202 con
el mismo idOperacion y el estado actual de esa operación, sin crear otro
comprobante. El resultado actual de esa operación lo ves siempre en el
seguimiento.
El 202 puede traer autorizado (2001) si la emisión directa ya conoce el
resultado; en ese caso no sigas esperando. Si ya conoce un rechazo definitivo,
rechazado (3xxx, con el detalle del SRI en errores) o rechazo_configuracion
(4xxx), la respuesta no es un 202 sino un 422 con el mismo cuerpo de la
operación: estado, codEstado, msgError, errores, idOperacion y
urlEstado. Un reintento con la misma Idempotency-Key y el mismo cuerpo
devuelve el mismo 422; corrige la causa y emite con una referenciaExterna
nueva. Cuando el 202 trae recibido, el comprobante todavía no está autorizado;
después de recibirlo, sigue estos pasos:
- Guarda
idOperacionjunto a tu documento. - Espera el webhook (
document.authorized,document.rejectedodocument.failed) o consultaGET /v1/operaciones/{idOperacion}mientras suestadosearecibido. - Con
autorizado, descarga el RIDE o el XML. Con cualquier otro estado final, lee elcodEstadoy el detalle deerrores, corrige la causa y reenvía el comprobante como se explica en Reintentos y duplicados.
Cada comprobante que el SRI autoriza o rechaza consume un documento de tu cupo, y uno cancelado lo libera. Una solicitud mal formada (400) no consume cupo, y un 422 por validación consume 1 documento como intento. El detalle está en Consumo y cuotas.
Validar sin emitir#
Antes de emitir puedes comprobar que un comprobante está bien armado. La
validación aplica las mismas reglas que la emisión: la estructura, los formatos,
los totales, los impuestos y los pagos, que infoTributaria.ruc corresponda al
contribuyente de la ruta y que el contribuyente y el tipo de comprobante estén
habilitados para tu API Key. No emite nada, no consume cupo ni usa un número de
la serie, y no necesita Idempotency-Key. Si tu cliente la envía siempre, la
validación la ignora: no la valida ni la guarda, y reutilizarla con otro cuerpo
no produce un 409. Cada validación cuenta para tu
límite de solicitudes por minuto.
Te sirve sobre todo cuando generas los comprobantes de forma automática, por ejemplo desde un archivo o con un asistente de IA: validas el lote completo, corriges lo que falle y emites después solo lo que pasó.
La ruta de validación es la de emisión del tipo con /validar al final. Para una
factura:
POST /v1/contribuyentes/{identificacion}/facturas/validar
X-Api-Key: <API Key>
Content-Type: application/json
El cuerpo y sus límites son los mismos de Endpoint, sin la
cabecera Idempotency-Key. Si el comprobante cumple todas las reglas, la API
responde 200 OK con este cuerpo:
{
"valido": true,
"errores": []
}
| Campo | Tipo | Descripción |
|---|---|---|
valido |
boolean | true cuando el comprobante cumple todas las reglas de la emisión. |
errores |
array de string | Viene siempre y, en una validación correcta, es una lista vacía. |
Si no las cumple, responde el mismo código que daría la emisión, con la forma de
error de toda la API (estado, codEstado, msgError y errores): un 422 con
el codEstado 3002 (comprobante_invalido) y hasta 20 problemas en errores, como se explica
en Errores de validación, o un 403 con el codEstado
3011 (acceso_denegado) si el contribuyente, su RUC o el tipo de comprobante no están
habilitados para tu API Key.
Un 200 significa que, con el contenido que enviaste, la emisión no tendrá
errores de validación. La validación no comprueba tu cupo ni si ya emitiste ese
comprobante, así que al emitir todavía puedes recibir un 429 con el codEstado
4004 si no tienes un paquete vigente con saldo, o la respuesta de un reintento si
ya usaste esa Idempotency-Key. Tampoco es una
autorización del SRI: el resultado fiscal llega solo después de emitir.
Estos ejemplos validan el comprobante.json de
Ejemplo de emisión:
curl -s -X POST "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar" -H "X-Api-Key: $ECUAFACT_API_KEY" -H "Content-Type: application/json" -d @comprobante.json
# 200 OK con valido en true si cumple todas las reglas; si no, el error de la emisión.
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 contenido = new StringContent(
await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json");
using HttpResponseMessage respuesta = await http.PostAsync("/v1/contribuyentes/0123456789001/facturas/validar", contenido);
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/facturas/validar",
headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
json=cuerpo,
timeout=30,
)
print(r.status_code, r.text)
// Node.js 18 o superior. Guarda como validar.mjs y ejecuta: node validar.mjs
import { readFile } from 'node:fs/promises';
const res = await fetch(
'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar',
{
method: 'POST',
headers: {
'X-Api-Key': process.env.ECUAFACT_API_KEY,
'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/facturas/validar');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
'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/facturas/validar"))
.header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
.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());
# Resultado esperado: una fila con el estado valido, o invalido con el error de la API.
ecuafact validar comprobante.json --entorno sandbox
Errores de validación#
Cuando una emisión no pasa la validación, la API responde con el primer
problema que encontró, así que cada respuesta te dice qué corregir. Si el cuerpo
tiene errores y además falta la cabecera Idempotency-Key, primero recibes el
error del cuerpo.
Un 400 con el codEstado 3003 (solicitud_invalida) significa que la petición está
mal formada, porque el JSON está roto o la cabecera Idempotency-Key falta o no
es válida. Un 422 con el codEstado 3002 (comprobante_invalido) significa que la API
entendió la petición,
pero el comprobante no cumple una regla.
Un 400 no consume cupo; un 422 consume 1 documento como intento. Ninguno de los dos usa un número de la serie. Corrige el
dato y reenvía con la misma Idempotency-Key.
Así se ve un error de validación. Tiene la misma forma de la respuesta 202, con
idOperacion, urlEstado, numeroDocumento, claveAcceso y las fechas en
null, porque no se creó ninguna operación:
{
"estado": "rechazado",
"codEstado": 3002,
"msgError": "El comprobante no cumple las validaciones.",
"errores": [
"$.info.pagos[0].unidadTiempo: Obligatoria cuando hay plazo."
],
"idOperacion": null,
"urlEstado": null,
"ambiente": 1,
"tipoDocumento": "01",
"numeroDocumento": null,
"referenciaExterna": "FACTURA-2026-0001",
"claveAcceso": null,
"fhRecibido": null,
"fhAutorizacion": null
}
| Campo | Tipo | Descripción |
|---|---|---|
estado |
string | rechazado en los errores de validación. |
codEstado |
number | Código estable para programar, como 3003 (solicitud_invalida) o 3002 (comprobante_invalido). |
msgError |
string | Descripción general y fija del código. Puedes mostrarla, pero no decidas con ella. |
errores |
array de string | Viene siempre. En 3002 (comprobante_invalido) trae hasta 20 mensajes, uno por problema, cada uno con la ruta del campo y, cuando corresponde, la posición de la línea o del impuesto ($.info.pagos[0].unidadTiempo, $.detalles[3].impuestos[0].valor). En 3003 (solicitud_invalida) trae el detalle de los parámetros o del cuerpo que no se pudo leer; puede ser más de uno. En los demás errores es una lista vacía. Corrige todos los que puedas y reenvía; los que no se hayan podido validar aparecerán en la siguiente respuesta. |
ambiente, tipoDocumento y referenciaExterna |
Vienen con el valor de tu petición cuando la API pudo leerlo; si no, son null. |
Mensajes de validación frecuentes#
Estos son los mensajes de errores que aparecen con más frecuencia al emitir
cualquier tipo de comprobante.
Mensaje (en errores) |
Causa | Qué hacer |
|---|---|---|
Campo no soportado en este contrato. |
Un campo que la API no conoce en ese objeto, como claveAcceso, ambiente, un campo de info, una colección o un código de línea de otro tipo (motivos o codigoInterno en una factura), o un nombre mal escrito. |
Quita el campo o corrige su nombre; envía solo los campos y la colección de la guía del tipo, según Qué cambia por tipo. |
Valor o tipo inválido. |
Un tipo JSON incorrecto: un número donde va una cadena ("estab": 2) o un texto donde va un número. A veces añade qué se esperaba, por ejemplo Valor o tipo inválido: se esperaba texto. |
Envía los códigos como cadena y los importes como número. |
Campo obligatorio. / Texto vacio o longitud excedida. |
Falta un campo obligatorio, está vacío o supera su largo. | Completa el campo indicado en la ruta. |
Numero fuera de rango. |
Un número negativo o demasiado grande. | Envía importes positivos: la nota de crédito y la retención también llevan valores positivos. |
La creación de este tipo requiere un contribuyente identificado. |
Tipo de identificación 07 (consumidor final) en un tipo distinto de la factura. |
Identifica a la contraparte con RUC, cédula, pasaporte o identificación del exterior. |
Para una factura mayor a $50, seleccione un cliente con cedula, RUC o pasaporte... |
Una factura a consumidor final (07) con importeTotal mayor que 50. |
Identifica al comprador con RUC, cédula o pasaporte. |
Lista vacia, invalida o demasiado extensa. |
Falta una lista obligatoria (detalles, pagos, totalConImpuestos) o supera su máximo. |
Envía al menos un elemento y respeta el máximo. |
Use dd/MM/yyyy, como el SRI. |
Fecha en otro formato. | Usa 07/10/2026. |
El RUC no corresponde al contribuyente del contexto. |
infoTributaria.ruc no corresponde a la identificacion de la ruta. |
Usa el RUC completo del contribuyente de la ruta. |
Subtotal del detalle no coincide... |
precioTotalSinImpuesto distinto de cantidad x precioUnitario - descuento redondeado. |
Recalcula la línea. |
Valor de impuesto no coincide con base y tasa. |
El IVA de una línea no es la base sin redondear por la tarifa, redondeado a 2 decimales. | Calcula el IVA antes de redondear la base. |
Base IVA debe incluir subtotal e ICE. |
La baseImponible del IVA es distinta de precioTotalSinImpuesto más el ICE de la línea. |
Usa el subtotal de la línea como base. |
Base o valor de impuestos no coincide con detalles. |
Una fila de totalConImpuestos no es la suma de sus líneas. |
Suma bases y valores por codigo + codigoPorcentaje. |
Los impuestos de cabecera no corresponden a los detalles. |
Falta o sobra una fila en totalConImpuestos, o hay dos filas con el mismo codigo + codigoPorcentaje. |
Envía exactamente una fila por grupo de las líneas. |
Totales no coinciden con detalles. |
totalSinImpuestos, totalDescuento o la suma de IVA no cuadra con las líneas. |
Suma de nuevo las líneas. |
total no coincide con subtotal + IVA + ICE + propina. |
El importeTotal, o el valorModificacion en la nota de crédito, está mal calculado. |
Aplica la fórmula del total. |
Pagos no coinciden con total. |
La suma de pagos[].total es distinta de importeTotal. |
Ajusta los pagos al total. |
...importe no admitido; no se redondea silenciosamente. |
Un importe con más de 2 decimales, o cantidad o precio con más de 6. | Redondea en tu sistema antes de enviar. |
Cada guía de tipo agrega los mensajes propios de ese comprobante.
Reintentos y duplicados#
Con la Idempotency-Key puedes reintentar un envío sin emitir dos veces el
mismo comprobante. Usa un valor estable por intención, como tu número interno del documento
(FACTURA-2026-0001) o un UUID v4 que guardas junto al documento antes de
enviarlo. La API recuerda la clave durante 7 días, por integración y por
ambiente.
| Situación | Qué envías | Resultado | Qué hacer |
|---|---|---|---|
| Timeout, error de red o 5xx sin respuesta clara | La misma Idempotency-Key y el mismo cuerpo. |
202 con el mismo idOperacion si el primer intento llegó, o con una operación nueva si nunca llegó. |
Continúa con el seguimiento de ese idOperacion. |
| Reenvío accidental del mismo documento | La misma Idempotency-Key y el mismo cuerpo. |
202 con el mismo idOperacion. |
No hagas nada; no se emitió otro comprobante. |
Misma Idempotency-Key con un cuerpo distinto |
La clave repetida y el cuerpo cambiado. | 409 con el codEstado 3005 (conflicto_idempotencia). |
Si es otro documento, usa otra clave. Si es una corrección, sigue la fila del rechazo que corresponda. |
Misma origenReferencia + referenciaExterna con un cuerpo distinto, o con otro tipo de comprobante |
Una clave nueva y una referencia que ya usó otro comprobante. | 409 con el codEstado 3005 (conflicto_idempotencia). |
Usa una referenciaExterna nueva para el documento corregido. |
Número (estab-ptoEmi-secuencial) de un comprobante autorizado, pendiente o rechazado por el SRI |
Un secuencial propio que ya se usó. |
409 con el codEstado 3004 (comprobante_duplicado). |
No reenvíes, porque ese número ya existe. Si el comprobante anterior fue rechazado por el SRI, emite con un secuencial nuevo; omite secuencial para que se asigne el siguiente. |
Corregir un comprobante que no se emitió: estado rechazado con el codEstado 3002, rechazo_configuracion con cualquier código 4xxx, o error con el 5006 (entrega_no_posible) |
El cuerpo corregido, una nueva Idempotency-Key, una nueva referenciaExterna y, para conservar el número, el mismo estab, ptoEmi y secuencial en infoTributaria. |
202, que puede traer el mismo idOperacion. Si corriges el contenido tras un rechazo, cuenta como otro envío y consume 1 documento; si reenvías con el mismo número tras un error 5006, no consume otro, como se explica en Consumo y cuotas. |
Sigue la operación como siempre. |
Reenviar una operación cancelado |
Una nueva Idempotency-Key y una nueva referenciaExterna; puedes usar el mismo número. |
202 con estado en recibido y el codEstado 1001 o 1002. |
Sigue la operación. Si envías la misma referenciaExterna y el mismo cuerpo, la API devuelve la operación cancelada y no emite. |
Corregir un comprobante rechazado por el SRI (estado rechazado con el codEstado 3001) |
El cuerpo corregido, una nueva Idempotency-Key y una nueva referenciaExterna, sin secuencial para que se asigne automáticamente. |
202 con una operación nueva. | Emite con un secuencial nuevo, porque si reutilizas el mismo número la API responde 409 con el codEstado 3004 (comprobante_duplicado). |
estado error con el codEstado 5007 (resultado_no_confirmado) o 5001 (error_interno) |
Nada todavía. | - | No reemitas, porque el comprobante podría existir. Búscalo en el seguimiento y escribe a soporte con el idOperacion. |
Si omitiste el secuencial y quieres conservar el número al reenviar, búscalo
en el numeroDocumento de la respuesta 202 o del seguimiento; si no lo
necesitas, deja que se asigne el siguiente.
Atención
No generes una Idempotency-Key nueva para reintentar un envío cuyo resultado
no conoces (timeout). Si el primer intento llegó, la clave nueva emite un
segundo comprobante, con otro número y otro cupo consumido.
Estados de este endpoint#
Esta tabla reúne todas las respuestas posibles de la emisión. Todas, incluidos los errores, traen la forma de la respuesta 202 que se explica en Respuesta.
codEstado |
HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 1001, 1002 o 2001 | 202 | La API recibió el comprobante, o reintentaste con la misma Idempotency-Key o la misma referencia y el mismo cuerpo. El 2001 indica que la autorización ya se conoce. |
Guarda idOperacion y sigue la operación; un reintento no emite otro comprobante y trae el estado actual. |
3003 (solicitud_invalida) |
400 | El JSON o el XML está mal formado, o la Idempotency-Key falta o no es válida. |
Corrige la petición y reenvía. |
3002 (comprobante_invalido) |
422 | El comprobante no cumple una regla de estructura o fiscal; el detalle viene en errores. |
Corrige el campo indicado. Consume 1 documento como intento. |
| 3xxx o 4xxx | 422 | La emisión directa ya conoce un rechazo definitivo (rechazado o rechazo_configuracion); el cuerpo trae el codEstado, el msgError y el detalle en errores. |
Corrige la causa según el codEstado y emite con una referenciaExterna nueva. |
3006 (cuerpo_excedido) |
413 | El cuerpo supera 2 MiB. | Reduce el cuerpo, con menos líneas o textos más cortos. |
3004 (comprobante_duplicado) |
409 | Ya existe un comprobante con ese número (estab-ptoEmi-secuencial) autorizado, pendiente o rechazado 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, o la misma origenReferencia + referenciaExterna, con otro cuerpo. |
Reutiliza el cuerpo original o usa una clave y referencia nuevas para el documento nuevo. |
4004 (cupo_agotado) |
429 | No quedan documentos en tus paquetes vigentes. | Compra un paquete en el portal y no reintentes en bucle. Revisa Consumo. |
3009 (credenciales_invalidas) |
401 | La API Key falta o 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 revisa proxies o balanceadores entre tu sistema y la API. |
3011 (acceso_denegado) |
403 | El contribuyente o el tipo de comprobante no están habilitados para tu integración. | Revisa la identificacion y los tiposComprobante del contexto. |
5005 (limite_solicitudes) |
429 | Superaste el límite de solicitudes por minuto. | Espera lo que indica Retry-After y reintenta con la misma Idempotency-Key. Es el único 429 que se reintenta; el 4004 no. |
3003 (solicitud_invalida) |
415 | El Content-Type no es application/json, application/xml ni text/xml, por ejemplo porque falta la cabecera. |
Envía el Content-Type que corresponda al cuerpo. |
5001 (error_interno) / 5002 (servicio_no_disponible) |
500 / 503 | Ocurrió un error interno o el servicio no está disponible. | Reintenta con la misma Idempotency-Key y el mismo cuerpo. |
El catálogo completo está en Errores.
Siguientes pasos#
- Factura: campos de la factura y ejemplos con varias tarifas, descuento y pago a crédito.
- Seguimiento de una operación: consulta el resultado del SRI con tu
idOperacion. - Webhooks: recibe el resultado sin consultar.
- Errores: catálogo de
codEstadoy si se reintenta o se corrige.