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

Las 21 Validaciones

Reglas de validación que QAPI aplica a cada factura antes de enviarla al certificador.

Antes de construir el XML y enviarlo al certificador, QAPI aplica 21 reglas de validación. Si alguna falla, la factura nunca llega al certificador — recibís un 422 VALIDATION_ERROR inmediatamente con el detalle exacto de qué campo falló.

Las validaciones se ejecutan síncronamente antes del 202 PROCESSING. Si recibís 202, tu factura pasó las 21 reglas y ya está en el pipeline de certificación.

Todas las validaciones

Identidad y formato (1–5)

Cálculos y montos (6–10)

Restricciones fiscales especiales (11–21)

Reglas de los complementos

Además de las 21, cinco tipos de DTE llevan un bloque propio en el payload. La regla es la misma para todos y corre en las dos direcciones: el complemento de un tipo es obligatorio en ese tipo y prohibido en los demás. Mandar abonos en una FACT, o emitir una FCAM sin ellos, devuelve 422 VALIDATION_ERROR.

Lo que valida el certificador

Las 21 validaciones corren en QAPI y responden 422 en el acto. Después, el certificador aplica las suyas: si alguna falla, el request ya recibió su 202 PROCESSING y el error llega como estado FAILED con error_code y error_message, o por webhook.

Dos reglas del certificador que conviene tener en cuenta al armar el payload, porque no son evidentes:

Respuesta de error

Estructura RFC 9457

Cuando una o más validaciones fallan, QAPI responde con 422 VALIDATION_ERROR en formato RFC 9457 (Problem Details):

{
  "type": "https://docs.dtevia.com.gt/errors/validation-error",
  "title": "VALIDATION_ERROR",
  "status": 422,
  "detail": "Error de validación",
  "instance": "/v1/invoices",
  "invalid_params": [
    {
      "field": "items.0.impuestos.0.monto_impuesto",
      "message": "MontoImpuesto IVA inválido. Esperado ~12.00, recibido 10.00"
    }
  ]
}

Campo invalid_params

Cada entrada incluye el path exacto del campo (field) y la razón del fallo (message). Usa notación de puntos, incluidos los índices de array: items.0.impuestos.0.monto_impuesto.

En esta página