En esta página
Ciclo de vida del comprobante
Un comprobante pasa de recibido a un resultado final, autorizado o no; aquí ves cada estado y qué hacer en él.
Cuando nos envías un comprobante, te respondemos de inmediato con un
identificador de operación y, a partir de ahí, nos encargamos de obtener su
autorización ante el SRI. Esta página explica ese recorrido: qué significa cada
valor de estado, qué indica el codEstado que lo acompaña y qué debe hacer
tu sistema en cada caso.
Te recomendamos leerla antes de programar el seguimiento o los webhooks. Al terminar sabrás cuándo un comprobante tiene validez fiscal, cuándo hay que esperar, cuándo corregir y cuándo no debes reenviar.
Conceptos#
- Recibido no es autorizado. Cuando la API responde
202 Accepted, el comprobante quedó recibido, pero todavía no tiene validez fiscal. Solo cuenta el resultado del SRI (Servicio de Rentas Internas, la autoridad tributaria de Ecuador), es decir, unestadoenautorizado. - Por qué es asíncrono. El SRI puede tardar segundos o minutos en
responder. Por eso no te hacemos esperar: te damos un
idOperaciony puedes seguir la operación por consulta o por webhook. - Un estado y un código.
estadoresponde cómo va o cómo terminó la operación, ycodEstado, un número de 4 dígitos cuyo primer dígito coincide con elestado, precisa el resultado y explica la causa cuando no terminó autorizada. Tu sistema decide con los dos.
Todos los términos están en el Glosario.
Cómo funciona#
El diagrama resume el recorrido de una emisión, desde el envío hasta el webhook con el resultado, y los pasos de abajo lo explican.
- Envías el comprobante a la ruta de su tipo, por ejemplo
POST /v1/contribuyentes/{identificacion}/facturaspara una factura, con la cabeceraIdempotency-Key. Hay una ruta por tipo de documento: facturas, liquidaciones de compra, notas de crédito, notas de débito, guías de remisión y retenciones. El tipo lo fija la ruta, así que el cuerpo no incluyeinfoTributaria.tipoDocumento. Si el formato, la estructura o los totales fallan, recibes un 400 o un 422 y no se crea ninguna operación; el 400 no consume cupo y el 422 descuenta un documento como intento. - Recibes
202 Acceptedconestadoenrecibido, elcodEstado1001 o 1002, elidOperacionyurlEstado, la URL completa del seguimiento. Con 1001 laclaveAccesotodavía esnull, y con 1002 ya viene en la respuesta; tu sistema debe aceptar los dos casos. Si ya se conoce la autorización al responder, el 202 traeautorizado(2001). Si ya se conoce un rechazo definitivo,rechazado(3xxx) orechazo_configuracion(4xxx), la respuesta es un422con el mismo cuerpo:codEstado,msgErroryerrores. Un reintento con la mismaIdempotency-Keyy el mismo cuerpo responde con el mismoidOperaciony el estado actual de la operación. - Obtenemos el resultado del SRI. Mientras no hay un resultado final, el
estadosigue enrecibido, con elcodEstado1001 o, cuando el comprobante ya tiene clave de acceso, 1002. El resultado puede tardar desde unos segundos hasta varios minutos, y no tienes que hacer nada para que avance. - La operación llega a un estado final:
autorizadosi el SRI lo autorizó, orechazado,rechazo_configuracion,errorocanceladocon uncodEstadoque explica la causa, la descripción del código enmsgErrory el detalle enerrores. - Te enteras del resultado por webhook, que se
configura en el Portal del Cliente en Integración > Eventos, o por
seguimiento con
GET /v1/operaciones/{idOperacion}. Te recomendamos usar el webhook como vía principal y la consulta como respaldo.
Valores de estado#
estado |
Final | Qué significa |
|---|---|---|
recibido |
No | Recibimos el comprobante, pasó nuestras validaciones y todavía no tiene un resultado final. El codEstado es 1001 mientras no tiene clave de acceso y 1002 cuando ya la tiene. |
autorizado |
Sí | El SRI autorizó el comprobante, que en producción tiene validez fiscal. fhAutorizacion puede venir null, porque algunas autorizaciones no traen fecha. |
rechazado |
Sí | El comprobante no se autorizó por su contenido: lo rechazó el SRI, con el codEstado 3001 (rechazo_sri), o no cumplió una regla de la validación fiscal, con el 3002 (comprobante_invalido). |
rechazo_configuracion |
Sí | No se pudo emitir porque falta o está mal una configuración del emisor: su configuración ante el SRI, la firma electrónica o el cupo. |
error |
Sí | No se pudo emitir por un fallo inesperado o porque algo impidió de forma definitiva que se autorice. |
cancelado |
Sí | La plataforma canceló el envío de forma automática. El comprobante no se emitió y no consumió cupo. |
Estados y qué hacer#
Cada fila es un resultado que puedes ver en el seguimiento y en los webhooks. En la columna "Qué hacer", "claves
nuevas" significa una Idempotency-Key nueva y una referenciaExterna nueva.
estado |
codEstado |
Webhook | Qué hacer |
|---|---|---|---|
recibido |
1001 o 1002 | - o, si no pudimos confirmar a tiempo el resultado, el aviso operation.requires_attention |
Espera el webhook o consulta de nuevo, cada 10 segundos al inicio y luego cada pocos minutos. No reenvíes. |
autorizado |
2001 | document.authorized |
Marca el comprobante como autorizado, guarda la claveAcceso y descarga el RIDE. |
rechazado |
3001 | document.rejected |
Es un rechazo del SRI, y su mensaje viene en errores. Corrige el dato y emite otro comprobante con claves nuevas y el secuencial automático. Si reenvías el mismo número, la API responde 409 con el codEstado 3004 (comprobante_duplicado). |
rechazado |
3002 | document.failed |
Corrige el dato que indica errores y reenvía con claves nuevas. Puedes conservar el número. |
rechazo_configuracion |
4001, 4002, 4003 o 4004 | document.failed |
Corrige la configuración del emisor (su estado en Cuenta > Contribuyentes, la firma electrónica con Reemplazar firma en esa misma pantalla o el cupo, que repones comprando un paquete) y reenvía con claves nuevas y el mismo número. |
error |
5006 | document.failed |
El comprobante no se creó. Reenvíalo con claves nuevas y el mismo número. |
error |
5007 o 5001 | document.failed |
No reemitas, porque el comprobante podría existir. Búscalo en el seguimiento y escribe a soporte con el idOperacion. |
cancelado |
6001 | Ninguno; lo ves en el seguimiento | Reenvía con claves nuevas; puedes usar el mismo número. Con la misma referenciaExterna y el mismo cuerpo, la API devuelve la operación cancelada y no emite. |
El significado de cada codEstado está en el
catálogo de Errores.
Para conservar el número, envía el mismo estab, ptoEmi y secuencial. Si
dejaste que te asignáramos el secuencial, lo encuentras en el numeroDocumento
del seguimiento. Un reenvío con el mismo número puede responder con el mismo
idOperacion. Si la operación terminó en error con el codEstado 5006, el
reenvío usa el mismo documento y no descuenta otro; si corriges el contenido de
un comprobante ya rechazado, el reenvío descuenta un documento, como se explica
en Consumo y cuotas.
Atención
Ante un tiempo de espera agotado o un error de red en el POST, reintenta con
la misma Idempotency-Key y el mismo cuerpo. Cambiar la clave o la
referenciaExterna en ese momento puede emitir el comprobante dos veces.
Ejemplo: lee una operación rechazada#
Este es el seguimiento de un comprobante que la validación fiscal rechazó antes
de llegar al SRI, tal como lo devuelve GET /v1/operaciones/{idOperacion} con
un 200 OK:
{
"estado": "rechazado",
"codEstado": 3002,
"msgError": "El comprobante no cumple las validaciones.",
"errores": [
"identificacionComprador: El comprador no tiene identificacion."
],
"idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"ambiente": 1,
"tipoDocumento": "01",
"numeroDocumento": "001-001-000000123",
"referenciaExterna": "FAC-ERP-4581",
"claveAcceso": null,
"fhRecibido": "2026-11-09T10:15:00-05:00",
"fhAutorizacion": null
}
Para interpretarlo, sigue estos pasos:
- Busca la fila de
rechazadocon elcodEstado3002 en Estados y qué hacer. Es un estado final y el SRI no llegó a evaluar el comprobante. - Lee
errores, que te dice qué dato corregir;msgErrorsolo trae la descripción general del código. Muéstralos a quien revisa el comprobante, pero decide en tu código conestadoycodEstado. - Corrige el comprobante y reenvíalo con claves nuevas. Si quieres conservar el
número, envía el mismo
estab,ptoEmiysecuencial.
Los campos de esta respuesta se describen uno a uno en Seguimiento de una operación. El código para consultar en bucle con espera, en cURL, .NET, Python, Node.js, PHP y Java, está en Primeros pasos, paso 4.
Reintentos e idempotencia#
La Idempotency-Key identifica una intención de emitir. Con la misma clave y el
mismo cuerpo, la API devuelve el mismo idOperacion y el estado actual de la
operación, sin crear otro comprobante; con la misma clave y otro cuerpo, responde 409 con el
codEstado 3005 (conflicto_idempotencia).
La clave vale por integración (todas tus API Key) y ambiente, y se conserva 7 días. Rotar una API Key no reinicia la idempotencia. Guárdala junto con tu documento; puede ser, por ejemplo, tu número interno de factura o un UUID v4. Un 400 o un 422 no registra la clave, así que en ese caso corrige y reenvía con la misma.
Para una emisión nueva, incluida la corrección de un rechazo o el reenvío de
una operación cancelado, usa una clave nueva y una referenciaExterna nueva.
La pareja origenReferencia + referenciaExterna también identifica la
intención, de modo que con la misma referencia y otro cuerpo la API responde 409
con el codEstado 3005. Tienes más recomendaciones en
Buenas prácticas.
Cupo#
Cada etapa del ciclo afecta al cupo de documentos de una manera distinta:
| Momento | Consume cupo |
|---|---|
| Respuesta 400 | No. |
| Respuesta 422 | Sí; descuenta un documento como intento. |
202 Accepted |
Aparta un documento de tu saldo (reservados) mientras no hay resultado. |
| Autorizado por el SRI | Sí; el documento apartado pasa a consumido. |
rechazado, con el codEstado 3001 o 3002 |
Sí. |
rechazo_configuracion |
Sí. |
error, con el codEstado 5006 o 5007 |
No; el documento sigue apartado y lo usa el reenvío con el mismo número. |
cancelado |
No; el documento apartado se libera. |
| Reenvío de un comprobante rechazado con el mismo contenido | No descuenta un documento adicional. |
| Reenvío de un comprobante rechazado con el contenido corregido | Sí; es un envío nuevo. |
Tu saldo se consulta como se explica en Consumo y cuotas.
Errores frecuentes#
| Error | Por qué pasa | Cómo evitarlo |
|---|---|---|
| Marcar como facturado al recibir el 202 | El 202 solo confirma la recepción. | Espera a que el estado sea autorizado o a recibir el webhook document.authorized. |
| Consultar el estado en un bucle sin espera | Agota tu límite de solicitudes y la API responde 429 con el codEstado 5005 (limite_solicitudes). |
Espera 10 segundos entre consultas y usa webhooks. |
Reenviar con otra Idempotency-Key ante un timeout |
Crea una segunda emisión. | Reintenta con la misma clave y el mismo cuerpo. |
| Reenviar el mismo número tras un rechazo del SRI | La API responde 409 con el codEstado 3004. |
Emite con el secuencial automático. |
Reemitir ante el codEstado 5007 (resultado_no_confirmado) |
El comprobante podría existir y lo duplicarías. | No reemitas. Búscalo en el seguimiento y escribe a soporte con el idOperacion. |
Decidir con msgError o errores |
Son textos legibles que pueden cambiar. | Decide con estado y codEstado, y usa msgError y errores solo para mostrarlos o registrarlos. |
Siguientes pasos#
- Seguimiento de una operación: todos los campos de
GET /v1/operaciones/{idOperacion}. - Webhooks: recibe
document.authorized,document.rejectedydocument.failedsin consultar en bucle. - Primeros pasos: recorre el ciclo completo con una factura de prueba.
- Errores: qué significa cada
codEstadoy si se reintenta o se corrige.