Introducción
Qué es QAPI, cómo funciona el modelo de Facturación Electrónica en Línea de Guatemala y el glosario esencial.
Introducción
QAPI no es un certificador SAT
QAPI es un middleware. No emite DTE directamente — conecta tu software con un certificador autorizado por la SAT, y gestiona esa relación por ti. Tú solo necesitas una API key y enviar JSON: nunca contratas ni configuras un certificador.
¿Qué es QAPI?
QAPI es un middleware SaaS de Facturación Electrónica en Línea (FEL) para Guatemala. Actúa como capa de abstracción entre tu software y los certificadores autorizados por la SAT.
Antes de QAPI
necesitabas:
- Contrato directo con un certificador (Totaldoc, Infile, Digifact, etc.)
- Integrar su SDK o API específica
- Manejar certificados digitales y XML DTE
- Gestionar actualizaciones cuando el certificador cambia su API
Con QAPI
solo necesitas:
- Una API key (
qapi_test_...oqapi_live_...) - Enviar un objeto JSON con los datos de la factura
- Recibir el UUID SAT, el número DTE y el PDF
Modelo de negocio
Tu software → QAPI API → [Certificador autorizado SAT] → SAT GuatemalaQAPI se encarga de:
- Validar el objeto factura contra las 14 reglas pre-certificación
- Construir el XML DTE según las normas SAT
- Enviar al certificador que QAPI tiene configurado en tu cuenta
- Devolver el UUID SAT, serie, número DTE y URL del PDF
- Notificarte vía webhook cuando el estado cambia
Glosario FEL
| Término | Definición |
|---|---|
| FEL | Facturación Electrónica en Línea — régimen de emisión de documentos tributarios electrónicos en Guatemala desde 2019 |
| DTE | Documento Tributario Electrónico — el documento emitido bajo el régimen FEL (factura, nota de crédito, etc.) |
| SAT | Superintendencia de Administración Tributaria — ente regulador fiscal de Guatemala |
| Certificador | Empresa autorizada por la SAT para validar y certificar DTEs. QAPI certifica sobre Totaldoc (Grupo CDS) |
| UUID SAT | Identificador único asignado por la SAT al DTE certificado — es el número que prueba que la factura es válida |
| Número de acceso | Número aleatorio de 9 dígitos generado por QAPI como identificador previo a la certificación |
| Tipo DTE | Categoría del documento (FACT = Factura, NCRE = Nota de Crédito, etc.) — ver Tipos de DTE |
| NIT | Número de Identificación Tributaria del emisor o receptor |
| CUI | Código Único de Identificación — DPI del receptor cuando no tiene NIT |
| CF | Consumidor Final — receptor cuando no se conoce o no aplica NIT |
| Gran Total | Total final de la factura calculado por QAPI (no confiar en el valor enviado por el cliente) |
| Frase SAT | Descriptor legal requerido en el DTE (tipo_frase + codigo_escenario) |
| Afiliación IVA | Categoría tributaria del emisor: GEN (general), PEQ (pequeño contribuyente), EXE (exento) |
Flujo completo de una factura
Pipeline de certificación
1. POST /v1/invoices
└─ QAPI valida (14 reglas)
└─ Genera numero_acceso
└─ Calcula gran_total
└─ Persiste con status PENDING
└─ Responde 202 { id, status: "PROCESSING" }
2. Pipeline async
└─ Construye XML DTE
└─ Envía al certificador (gestionado por QAPI)
└─ Recibe UUID SAT + número DTE
3. GET /v1/invoices/:id ← polling
└─ status: CERTIFIED → uuid_sat, numero_dte, pdf_url
└─ status: FAILED → error_code, error_messageRespuesta asíncrona
La respuesta inicial es 202 PROCESSING (no 200). Esto es intencional: la certificación es
asíncrona. Usa GET /v1/invoices/:id para hacer polling del estado final o configura un
webhook para recibir notificaciones automáticas.