Estados de Factura
Ciclo de vida completo de una factura QAPI — de PENDING a CERTIFIED, FAILED o CANCELLED.
Cada factura en QAPI pasa por un ciclo de vida bien definido. El campo status en
GET /v1/invoices/:id siempre refleja el estado actual.
Diagrama de estados
La anulación se pide con POST /v1/invoices/:id/cancel y solo procede desde CERTIFIED.
PROCESSING solo aparece en la respuesta 202
El body del 202 Accepted devuelve status: "PROCESSING" como resumen de "tu factura
está en el pipeline". Al consultar con GET /v1/invoices/:id verás el estado persistido
real: PENDING, SIGNING, CERTIFYING, o uno de los finales. Tratá los tres
transitorios como equivalentes: "todavía no hay resultado, seguí esperando".
Detalle de cada estado
Propiedad
Tipo
Campos disponibles por estado
Campos base — siempre presentes, sin importar el estado
id, status, tipo_dte, moneda, gran_total, numero_acceso, certificador,
origen ("api" o "playground"), referencia_interna, integrity_checksum,
created_at y updated_at vienen en toda respuesta de GET /v1/invoices/:id,
cualquiera sea el estado. Los ejemplos de abajo los incluyen completos; lo que cambia
por estado es lo que se agrega encima.
CERTIFIED
Agrega el grupo de certificación (uuid_sat, serie, numero_dte, pdf_url, certified_at):
{
"id": "inv_01jx...",
"status": "CERTIFIED",
"tipo_dte": "FACT",
"moneda": "GTQ",
"gran_total": 112.00,
"numero_acceso": 543219876,
"certificador": "TOTALDOC",
"origen": "api",
"referencia_interna": "ORD-2026-001",
"integrity_checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"created_at": "2026-06-08T16:00:00.000Z",
"updated_at": "2026-06-08T16:00:02.000Z",
"uuid_sat": "550E8400-E29B-41D4-A716-446655440000",
"serie": "A",
"numero_dte": 42,
"pdf_url": "https://print.totaldoc.io/pdf?uuid=550E8400-...",
"certified_at": "2026-06-08T16:00:02.000Z"
}FAILED
Solo los campos base, más error_code y error_message — nunca llegó a firmarse o
certificarse, así que no hay grupo de certificación:
{
"id": "inv_01jx...",
"status": "FAILED",
"tipo_dte": "FACT",
"moneda": "GTQ",
"gran_total": 112.00,
"numero_acceso": 543219876,
"certificador": "TOTALDOC",
"origen": "api",
"referencia_interna": "ORD-2026-001",
"integrity_checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"created_at": "2026-06-08T16:00:00.000Z",
"updated_at": "2026-06-08T16:00:05.000Z",
"error_code": "CERT_FAILED",
"error_message": "Regla SAT 2.2.4.4: El NIT del Receptor es inválido"
}Cuando el rechazo viene de la certificación (CERT_FAILED), error_message arranca con
Regla SAT <código>. Ese código es el de la regla de las Reglas y Validaciones de FEL
de la SAT que no se cumplió, y el texto que sigue es su descripción: con los dos ubicás la
regla exacta y sabés qué corregir en el documento. Los códigos que aparecen en la práctica están
explicados uno por uno en Reglas SAT.
CANCELLED
Conserva el grupo de certificación completo (la autorización SAT sigue existiendo) y
agrega cancelled_at:
{
"id": "inv_01jx...",
"status": "CANCELLED",
"tipo_dte": "FACT",
"moneda": "GTQ",
"gran_total": 112.00,
"numero_acceso": 543219876,
"certificador": "TOTALDOC",
"origen": "api",
"referencia_interna": "ORD-2026-001",
"integrity_checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"created_at": "2026-06-08T16:00:00.000Z",
"updated_at": "2026-06-09T10:30:00.000Z",
"uuid_sat": "550E8400-E29B-41D4-A716-446655440000",
"serie": "A",
"numero_dte": 42,
"pdf_url": "https://print.totaldoc.io/pdf?uuid=550E8400-...",
"certified_at": "2026-06-08T16:00:02.000Z",
"cancelled_at": "2026-06-09T10:30:00.000Z"
}Transiciones permitidas
| Desde | Hacia | Cómo |
|---|---|---|
PENDING | SIGNING | Automático — pipeline interno inicia |
SIGNING | CERTIFYING | Automático — XML firmado correctamente |
SIGNING | FAILED | Automático — la firma falla (error_code: SIGN_FAILED) |
CERTIFYING | CERTIFIED | Automático — certificador responde OK |
CERTIFYING | FAILED | Automático — certificador falla o timeout (error_code: CERT_FAILED) |
CERTIFIED | CANCELLED | Manual — POST /v1/invoices/:id/cancel |
Solo CERTIFIED se puede cancelar
Si intentás cancelar una factura que no está en estado CERTIFIED (por ejemplo SIGNING,
CERTIFYING o FAILED), recibirás 409 INVALID_STATUS.
FAILED no es cancelable
Una factura FAILED no tiene validez tributaria — no llegó a la SAT. No es necesario cancelarla.
Simplemente creá una nueva factura con los datos corregidos.
Polling recomendado
En entorno live, la certificación tarda entre 1 y 10 segundos dependiendo del certificador. En entorno test (MOCK), es casi instantáneo.
Estrategia de polling con backoff:
async function waitForCertification(id: string, apiKey: string) {
const delays = [1000, 2000, 2000, 3000, 3000, 5000, 5000, 10000];
for (const delay of delays) {
await new Promise(r => setTimeout(r, delay));
const res = await fetch(`https://api.dtevia.com.gt/v1/invoices/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const invoice = await res.json();
if (invoice.status === 'CERTIFIED') return invoice;
if (invoice.status === 'FAILED') throw new Error(invoice.error_message);
}
throw new Error('Timeout: la certificación tardó más de lo esperado');
}Como alternativa al polling, configurá un webhook para recibir
invoice.certified e invoice.failed automáticamente.
Webhook events por estado
| Estado final | Evento webhook disparado |
|---|---|
CERTIFIED | invoice.certified |
FAILED | invoice.failed |
CANCELLED | invoice.cancelled |
Los estados transitorios (PENDING, SIGNING, CERTIFYING) no disparan webhooks —
solo los finales. El evento invoice.test se dispara manualmente desde el dashboard.
El error_code de una factura FAILED es SIGN_FAILED (falló la firma) o CERT_FAILED
(falló la certificación) — es un namespace distinto al de los errores HTTP del
catálogo de errores.