Estados

Los once estados de un documento y cómo seguirlo hasta el veredicto.

Emitir no es instantáneo. El documento se firma, se presenta y Hacienda lo resuelve cuando lo resuelve; Timbre lo sigue mientras tanto.

Si lo que necesitás es mirar un documento —no integrarlo en tu sistema— el panel ya te lo muestra: Facturas lista todos, con filtros por estado, tipo, contribuyente y fecha, y cada uno abre a su línea de tiempo completa. Lo de abajo es para seguirlo por código.

Petición

curl https://api.timbre.cr/internal/v1/invoices/{id} \
  -H "Authorization: Bearer timbre_sk_…"

Los once estados

Estado	Qué significa
`draft`	Creado, sin clave ni consecutivo
`finalized`	Numerado; el proceso arrancó
`queued`	En cola de trabajo
`generated`	XML armado y validado contra los XSD
`signed`	Firmado con XAdES
`submitted`	Presentado a Hacienda
`processing`	Hacienda lo recibió y todavía no resuelve
`accepted`	Aceptado
`rejected`	Rechazado
`retry_pending`	Falló algo transitorio; se reintenta solo
`permanent_error`	Falló de forma definitiva

Los tres en negrita son terminales: de ahí no se mueve.

retry_pending no requiere nada de tu parte —Timbre reintenta con espera creciente. permanent_error sí: algo del documento o del entorno está mal y no va a mejorar reintentando.

No consultes en bucle

Podés consultar el documento, y para una prueba manual está bien. Para producción usá el webhook: Timbre te avisa cuando hay veredicto, en lugar de que preguntes cada pocos segundos por documentos que no cambiaron.

La historia completa

Petición

curl https://api.timbre.cr/internal/v1/invoices/{id}/events \
  -H "Authorization: Bearer timbre_sk_…"

Cada transición queda registrada, en orden y solo se agrega: nada las edita ni las borra. Siempre se puede reconstruir qué pasó y cuándo, que es lo que hace falta cuando algo salió mal hace tres semanas.

Y provenance explica de dónde salió cada decisión de impuesto:

Petición

curl https://api.timbre.cr/internal/v1/invoices/{id}/provenance \
  -H "Authorization: Bearer timbre_sk_…"

Reintentar a mano

Petición

curl -X POST https://api.timbre.cr/internal/v1/invoices/{id}/retry \
  -H "Authorization: Bearer timbre_sk_…"

Esto sirve para un caso concreto y estrecho: el documento quedó en finalized —numerado, pero nunca encolado, porque la cola no estaba disponible— y lo volvés a encaminar. Si ya está en queued, la llamada no hace nada y responde lo mismo.

No revive un permanent_error. Desde cualquier otro estado la respuesta es 409 con invalid_transition. Un documento que falló definitivamente se resuelve emitiendo uno nuevo, no reintentando el que ya se gastó.