Introducción
Qué es QAPI, cómo funciona el modelo de Facturación Electrónica en Línea de Guatemala y el glosario esencial.
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 vos. Vos solo necesitás una API key y enviar JSON: nunca contratás ni configurás 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 necesitás:
- 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
Cómo encaja QAPI
Tu integración termina en QAPI. Mandás el JSON, recibís el UUID SAT: no hay un segundo proveedor con el que contratar, ni credenciales de certificador que configurar, ni una API más que aprender. Todo lo que está dentro del recuadro lo gestionamos nosotros.
QAPI se encarga de:
- Validar el objeto factura contra las 21 reglas pre-certificación
- Construir el XML DTE según las normas SAT
- Certificarlo con el certificador autorizado — la relación comercial, las credenciales y los cambios de su API corren por nuestra cuenta, no por la tuya
- 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
Respuesta asíncrona
La respuesta inicial es 202 PROCESSING (no 200). Esto es intencional: la certificación es
asíncrona. Usá GET /v1/invoices/:id para hacer polling del estado final o configurá un
webhook para recibir notificaciones automáticas.