Ciclo de vida de un comprobante

Un comprobante nace cuando lo aceptamos y termina cuando el SRI decide. Entre medio pasa por pocos estados, y cada uno te dice exactamente qué hacer.

Los estados describen al comprobante, no a nuestros procesos internos: firmar o encolar no son estados. Cada comprobante guarda en status_transitions cuándo llegó a cada estado.

Lo que hacemos por ti entre estadosCopiar enlace a esta sección

1. Firmamos el XML con tu certificado (en Sandbox, con uno de práctica).
2. Lo enviamos al servicio de recepción del SRI. Si el SRI no responde, reintentamos con esperas cada vez más largas: un corte del SRI nunca pierde tu comprobante.
3. Consultamos la autorización: a los pocos segundos, y después cada vez más espaciado, hasta cada 10 minutos.
4. Al autorizarse, guardamos el XML autorizado, generamos el RIDE, lo enviamos por correo (en Producción) y te avisamos por webhook.

Consultar ahoraCopiar enlace a esta sección

Si no quieres esperar la siguiente consulta, POST /v1/ec/documents/{id}/refresh-status le pregunta al SRI en ese momento si decidió sobre un comprobante submitted. Responde 202 con el comprobante, que cambia de estado por el camino de siempre y avisa por webhook. Uno pending ya se está firmando o enviando, y uno que el SRI ya decidió no tiene nada que preguntar: ambos responden 200 con el comprobante tal cual. Cada comprobante se consulta a lo sumo una vez cada 10 segundos; repetirlo antes responde 429 con Retry-After.

curl -X POST https://api.fiscalbase.io/v1/ec/documents/$DOCUMENT_ID/refresh-status \
  -H "Authorization: Bearer fb_live_…"

Cuando el SRI tardaCopiar enlace a esta sección

El SRI a veces responde "en procesamiento" (código 70). No es un error: el comprobante queda en submitted y seguimos preguntando. Nunca lo reenviamos ni le cambiamos la clave de acceso, porque el SRI lo prohíbe: si lo reenviáramos, podría quedar duplicado.

La ficha técnica del SRI promete una respuesta en 24 horas. Si pasan 24 horas sin decisión, dejamos de preguntar, el comprobante queda en submitted y lo marcamos para que una persona lo revise.

Si el SRI responde que ya tiene ese comprobante (código 43), tampoco es un error: significa que lo recibió en un intento anterior, y pasamos a consultar su autorización.

Cuando el número ya está usadoCopiar enlace a esta sección

Si el SRI responde que otro comprobante ya tiene ese número (código 45), en Sandbox y Pruebas el comprobante toma otro número y una clave de acceso nueva, y se envía de nuevo sin pasar por returned: sigue en pending y su recorrido registra el paso renumbered. En Producción queda returned hasta que lo renumeras. Todo está en Establecimientos y numeración. Por eso el number y la access_key son definitivos recién en authorized.

Los mensajes del SRICopiar enlace a esta sección

Cuando el SRI devuelve o rechaza, sri_messages trae su explicación:

{
  "status": "returned",
  "sri_messages": [
    {
      "code": "35",
      "message": "ARCHIVO NO CUMPLE ESTRUCTURA XML",
      "detail": "No se ha encontrado información en el tag claveAcceso.",
      "type": "error"
    }
  ]
}

code es el código del SRI (ficha técnica, sección 11); úsalo en tu código, porque el texto puede cambiar. type es error, warning o info. Un comprobante autorizado también puede traer mensajes, por ejemplo el aviso 60 de Pruebas: este proceso fue realizado en el ambiente de pruebas.

Cómo enterarteCopiar enlace a esta sección

• Webhooks: te avisamos al llegar a authorized, returned o not_authorized. Es la forma recomendada. Mira Webhooks.
• Consultando: GET /v1/ec/invoices/{id} devuelve el estado actual. Úsalo para reconciliar, no en un bucle cada segundo.