Estados de un comprobante

Cada factura pasa por cuatro estados bien definidos. Conocerlos te ayuda a decidir cuándo mostrar "pendiente" en tu UI, cuándo enviar el email al cliente, y cuándo reintentar tras un rechazo.

Diagrama de transición

           POST /api/v1/facturas
                    │
                    ▼
        ┌──────────────────────┐
        │     PENDIENTE        │
        │  (en cola, sin       │
        │   firma todavía)     │
        └──────────┬───────────┘
                   │ worker toma
                   ▼
        ┌──────────────────────┐
        │    PROCESANDO        │
        │  (firma XAdES-BES,   │
        │   envío SOAP)        │
        └──────────┬───────────┘
                   │
        ┌──────────┴───────────┐
        ▼                      ▼
┌────────────────┐    ┌────────────────┐
│   AUTORIZADO   │    │   RECHAZADO    │
│  número + RIDE │    │ body con motivo│
└────────────────┘    └────────┬───────┘
                              │ POST /reenviar
                              ▼
                       (vuelve a PROCESANDO)

PENDIENTE

Estado inicial. La API recibió la factura, validó el body y la dejó en la cola. La respuesta del POST llega casi inmediata en este estado. Típicamente < 50 ms.

Qué hacer: mostrar "Estamos procesando tu comprobante…" en tu UI. No enviar email todavía.

PROCESANDO

El worker tomó la factura, está generando el XML, firmándolo con XAdES-BES y enviándolo al ente tributario vía SOAP. Dura entre 1 y 30 segundos según la carga del ente tributario.

Qué hacer: seguir mostrando "procesando". Si te suscribiste a webhooks, espera factura.autorizada o factura.rechazada.

AUTORIZADO

El ente tributario devolvió el número de autorización. La factura ya es legalmente válida. En este momento también queda disponible el PDF del RIDE en /api/v1/facturas/{id}/ride.

Qué hacer: enviar el email al cliente con el RIDE adjunto (puedes hacerlo desde tu código o disparando el endpoint POST /facturas/{id}/email).

RECHAZADO

El ente tributario rechazó el comprobante. El body trae un campo motivo con la razón: datos del cliente, totales, formato XML, firma inválida, etc.

Qué hacer: corregir la factura (o los datos del cliente) y hacer POST /api/v1/facturas/{id}/reenviar. No crees un comprobante nuevo desde cero: el sistema reusa la misma clave_acceso para evitar duplicados.