Ciclo de vida del comprobante

Un comprobante tiene un estado tributario (status), que depende del SRI, y dos estados de entrega, ride.status y email.status. Un RIDE o un correo que falla nunca cambia si el SRI autorizó el comprobante.

Estado tributario

processing ──► pending_sri ──► authorized
     │              │      └──► rejected
     └──────────────┴─────────► failed

Estado	Final	Significado
processing	No	Flashpi aceptó la solicitud: el comprobante está numerado, y su XML armado y validado contra el esquema del SRI. Se está firmando y enviando.
pending_sri	No	El SRI tiene el comprobante, o hay que volver a enviárselo, y Flashpi espera su decisión. Mientras el SRI está lento o no responde, Flashpi sigue reintentando por su cuenta.
authorized	Sí	El SRI lo autorizó. authorization.number (la clave de acceso) y authorization.authorizedAt tienen valor. Tiene validez tributaria (en el ambiente de producción).
rejected	Sí	El SRI lo rechazó. sriMessages indica por qué.
failed	Sí	Flashpi no pudo obtener una respuesta del SRI para él. failure.code indica por qué.
voided	Sí	Reservado para comprobantes anulados. La anulación está planificada; hoy ningún comprobante llega a este estado.

Precaución

Nunca vuelvas a enviar un comprobante porque sigue en processing o pending_sri: ya tiene su número y su clave de acceso, y el SRI puede tenerlo. Flashpi reintenta por ti, y una solicitud duplicada emitiría un segundo comprobante. Usa una Idempotency-Key para que reintentar la solicitud HTTP en sí no tenga riesgo.

Rechazado

Un rechazo es definitivo para ese comprobante: su secuencial queda usado. Corrige la causa y emite un comprobante nuevo (una solicitud nueva, que recibe un secuencial nuevo). Cada elemento de sriMessages tiene un code de Flashpi, un message (en inglés, o en español con Accept-Language: es) y una severity (error o warning):

"sriMessages": [
  {
    "code": "issuer_not_authorized",
    "message": "El RUC del emisor no tiene una solicitud aprobada para emitir comprobantes electrónicos en este ambiente del SRI.",
    "severity": "error"
  }
]

Flashpi nunca reenvía la respuesta del SRI tal cual: traduce cada mensaje del SRI a un código estable, como calculation_mismatch, issuer_not_authorized, issuer_ruc_inactive, establishment_closed, sequential_already_registered o late_submission. Un comprobante autorizado también puede traer advertencias del SRI en sriMessages, con severidad warning: en el ambiente de pruebas, todo comprobante autorizado trae test_environment.

Fallido

failure.code	Significado
certificate_required	El emisor no tiene un certificado de firma aceptado para el ambiente del comprobante.
certificate_expired, certificate_not_yet_valid	El certificado está fuera de sus fechas de validez.
certificate_blocked	No se pudo verificar a tiempo su estado de revocación, o su cadena ya no es confiable. Consulta Certificados.
certificate_revoked	Su entidad de certificación lo revocó.
certificate_unusable, signing_failed, document_invalid	No se pudo producir la firma. Flashpi recibe una alerta.
document_too_large	El comprobante firmado supera el límite de 320 KB del SRI.
sri_unavailable	No se pudo contactar al SRI durante toda la ventana de envío.
sri_authorization_timeout	El SRI no autorizó ni rechazó el comprobante dentro de la ventana de espera.
sri_request_refused, sri_environment_mismatch	El SRI rechazó la solicitud de Flashpi, o respondió desde el otro ambiente. Flashpi recibe una alerta.

Hoy la ventana de envío y la ventana de espera son de 72 horas cada una, contadas desde la creación del comprobante y desde su envío. El secuencial de un comprobante fallido también queda usado: emite un comprobante nuevo cuando la causa esté resuelta. Un comprobante failed todavía no genera un evento de webhook, así que búscalos también con GET /v1/documents?status=failed.

Cómo seguir un comprobante

• Webhooks (recomendado): invoice.authorized, invoice.rejected, y lo mismo para cada tipo. Consulta Webhooks.
• El modo síncrono: espera la respuesta en la propia solicitud de emisión. Consulta Modo síncrono y asíncrono.
• Consultándolo: GET /v1/documents/{id}, o una lista filtrada por status. Si consultas periódicamente, espera unos segundos entre lecturas, y más mientras esté en pending_sri.
• Eventos: GET /v1/events?documentId=... lista lo que le pasó a un comprobante.

Estado del RIDE

Cuando un comprobante está authorized, Flashpi genera su RIDE (el PDF imprimible). Consulta RIDE y correo.

ride.status	Significado
pending	Todavía no se genera. Todo comprobante empieza aquí; solo los comprobantes autorizados reciben un RIDE.
generated	Listo: GET /v1/documents/{id}/pdf lo devuelve. ride.template y ride.generatedAt tienen valor. Evento document.ride.generated.
failed	No se pudo generar tras algunos intentos. Evento document.ride.failed. Reenviar el comprobante por correo lo vuelve a generar.

Estado del correo

email.requested indica si se pidió el correo (options.sendEmail, o el valor por defecto del emisor). email.status es el estado de la entrega más reciente, y email.deliveries[] tiene un elemento por cada correo enviado, con su recipient, status, sentAt, lastEventAt y error. email.warnings[] lista lo que parece estar mal en la dirección, como un recipient_domain_typo (mira revisión de la dirección).

email.status	Significado
not_requested	La solicitud o el emisor lo desactivaron.
skipped	No hay a qué dirección enviarlo (la solicitud no tenía correo).
queued	Sale cuando el comprobante esté autorizado y su RIDE listo. Un comprobante rechazado o fallido se queda en queued, porque nunca se envía.
sent	El proveedor de correo lo aceptó. Evento document.email.sent.
delivered	El servidor de correo del destinatario lo aceptó. Evento document.email.delivered.
bounced	Rebotó (error dice bounce_permanent, bounce_transient, bounce_undetermined o bounce_suppressed, una dirección a la que el proveedor de correo ya no envía por un rebote o una queja anterior). Evento document.email.bounced.
complained	El destinatario lo marcó como spam. Evento document.email.complained.
failed	No se pudo enviar, por ejemplo cuando el dominio del destinatario no recibe correo (invalid_domain), se alcanzó el límite diario de correos de la cuenta o de la plataforma (account_email_limit_reached, platform_email_limit_reached), los correos de la cuenta están pausados (email_sending_paused) o un comprobante de prueba va a alguien que no es miembro verificado del equipo (test_recipient_not_allowed). Evento document.email.failed.