Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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, un estado en autorizado.
  • Por qué es asíncrono. El SRI puede tardar segundos o minutos en responder. Por eso no te hacemos esperar: te damos un idOperacion y puedes seguir la operación por consulta o por webhook.
  • Un estado y un código. estado responde cómo va o cómo terminó la operación, y codEstado, un número de 4 dígitos cuyo primer dígito coincide con el estado, 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.

SRIPlataformaTu sistemaalt[Autorizado][Rechazado por el SRI][No se pudo emitir]alt[Formato o totales inválidos][Comprobante válido]POST /facturas o la ruta de su tipo con Idempotency-Key400 o 422, no se crea la operación202 Accepted, estado recibidoComprobante firmadoRespuesta del SRIWebhook document.authorizedWebhook document.rejectedWebhook document.failedGET /v1/operaciones/{idOperacion}, en cualquier momento200 con estado, codEstado y errores
SRIPlataformaTu sistemaalt[Autorizado][Rechazado por el SRI][No se pudo emitir]alt[Formato o totales inválidos][Comprobante válido]POST /facturas o la ruta de su tipo con Idempotency-Key400 o 422, no se crea la operación202 Accepted, estado recibidoComprobante firmadoRespuesta del SRIWebhook document.authorizedWebhook document.rejectedWebhook document.failedGET /v1/operaciones/{idOperacion}, en cualquier momento200 con estado, codEstado y errores
  1. Envías el comprobante a la ruta de su tipo, por ejemplo POST /v1/contribuyentes/{identificacion}/facturas para una factura, con la cabecera Idempotency-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 incluye infoTributaria.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.
  2. Recibes 202 Accepted con estado en recibido, el codEstado 1001 o 1002, el idOperacion y urlEstado, la URL completa del seguimiento. Con 1001 la claveAcceso todavía es null, 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 trae autorizado (2001). Si ya se conoce un rechazo definitivo, rechazado (3xxx) o rechazo_configuracion (4xxx), la respuesta es un 422 con el mismo cuerpo: codEstado, msgError y errores. Un reintento con la misma Idempotency-Key y el mismo cuerpo responde con el mismo idOperacion y el estado actual de la operación.
  3. Obtenemos el resultado del SRI. Mientras no hay un resultado final, el estado sigue en recibido, con el codEstado 1001 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.
  4. La operación llega a un estado final: autorizado si el SRI lo autorizó, o rechazado, rechazo_configuracion, error o cancelado con un codEstado que explica la causa, la descripción del código en msgError y el detalle en errores.
  5. 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:

  1. Busca la fila de rechazado con el codEstado 3002 en Estados y qué hacer. Es un estado final y el SRI no llegó a evaluar el comprobante.
  2. Lee errores, que te dice qué dato corregir; msgError solo trae la descripción general del código. Muéstralos a quien revisa el comprobante, pero decide en tu código con estado y codEstado.
  3. Corrige el comprobante y reenvíalo con claves nuevas. Si quieres conservar el número, envía el mismo estab, ptoEmi y secuencial.

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.rejected y document.failed sin consultar en bucle.
  • Primeros pasos: recorre el ciclo completo con una factura de prueba.
  • Errores: qué significa cada codEstado y si se reintenta o se corrige.
No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

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

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

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

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

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