QAPI está en beta — la API puede cambiar sin previo aviso. Usá sandbox para pruebas.
QAPIQAPIDocs · by DTEVIA
Referencia

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

DesdeHaciaCómo
PENDINGSIGNINGAutomático — pipeline interno inicia
SIGNINGCERTIFYINGAutomático — XML firmado correctamente
SIGNINGFAILEDAutomático — la firma falla (error_code: SIGN_FAILED)
CERTIFYINGCERTIFIEDAutomático — certificador responde OK
CERTIFYINGFAILEDAutomático — certificador falla o timeout (error_code: CERT_FAILED)
CERTIFIEDCANCELLEDManual — 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 finalEvento webhook disparado
CERTIFIEDinvoice.certified
FAILEDinvoice.failed
CANCELLEDinvoice.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.

En esta página