Tipos de DTE
Los 12 tipos de Documento Tributario Electrónico de la SAT, los 8 que QAPI emite hoy y el complemento que exige cada uno.
QAPI soporta los 12 tipos de Documento Tributario Electrónico definidos por la SAT Guatemala.
Hoy emite 8: FACT, FPEQ, FCAM, FCAP, FESP, NCRE, NDEB y RECI. Los otros
cuatro devuelven 501 NOT_IMPLEMENTED.
Los ocho certificados contra el certificador real
Los ocho tipos ya se emitieron y certificaron de punta a punta contra el certificador, con emisores de los dos regímenes, incluida la cadena factura → nota de crédito y la anulación.
La única combinación que quedó fuera es un recibo emitido por un Pequeño Contribuyente: el certificador lo rechazó. Ver la nota en RECI.
El emisor define qué puede emitir (modo live)
La afiliación IVA configurada en tu emisor (cuenta o proyecto) determina el catálogo disponible en live. Se configura en el dashboard al crear el proyecto (o en Configuración → Empresa para el emisor de la cuenta).
| Afiliación | Puede emitir |
|---|---|
GEN — Régimen General | FACT, FCAM, FESP, NCRE, NDEB, RECI |
PEQ — Pequeño Contribuyente | FPEQ, FCAP, FESP, RECI |
El Pequeño Contribuyente no ajusta con notas de crédito ni de débito. Sí emite factura especial (la extiende el comprador por cuenta del vendedor) y sí emite recibos.
Para RECI y FESP la afiliación IVA es opcional: lo que habilita esos documentos es la
personería del emisor (emisor.tipo_personeria), no su régimen. Por eso una asociación
afiliada como Pequeño Contribuyente puede extender recibos, que es justamente su caso de uso.
Emitir fuera de esa lista devuelve 422 VALIDATION_ERROR con invalid_params en tipo_dte.
En sandbox no se aplica: podés probar cualquiera de los 8.
Tabla de tipos
| Tipo | Documento | Estado |
|---|---|---|
FACT | Factura — documento estándar de venta de bienes o servicios | Certificado en vivo |
FPEQ | Factura Pequeño Contribuyente — emisores con afiliación PEQ. No traslada IVA | Certificado en vivo |
FCAM | Factura Cambiaria — venta al crédito, con plan de abonos y vencimientos | Certificado en vivo |
FCAP | Factura Cambiaria de Pequeño Contribuyente — la cambiaria del régimen PEQ | Certificado en vivo |
FESP | Factura Especial — la emite el comprador por cuenta de un proveedor no inscrito, reteniéndole ISR e IVA | Certificado en vivo |
NCRE | Nota de Crédito — ajuste negativo o devolución sobre un documento anterior | Certificado en vivo |
NDEB | Nota de Débito — ajuste positivo sobre un documento anterior | Certificado en vivo |
RECI | Recibo — comprobante de un cobro | Certificado en vivo |
RDON | Recibo por Donación | Próximamente |
NABN | Nota de Abono | Próximamente |
FACA | Factura de Contribuyente Agropecuario | Próximamente |
FCCA | Factura Cambiaria de Contribuyente Agropecuario | Próximamente |
La exportación no es un tipo aparte: cualquier DTE se emite como exportación con
exportacion: true y su complemento exportacion_info. Lo mismo con la moneda —
moneda: "USD" funciona en cualquier tipo y no requiere FCAM.
Cuál emitir en cada caso
La tabla de arriba dice qué es cada documento; ésta, cuándo se usa. Lo primero que acota la lista es tu régimen: un emisor de Régimen General y un Pequeño Contribuyente facturan con documentos distintos y no son intercambiables.
| Situación | Régimen General | Pequeño Contribuyente |
|---|---|---|
| Venta al contado, bienes o servicios | FACT | FPEQ |
| Venta al crédito, en cuotas con vencimiento | FCAM | FCAP |
| Le comprás a un proveedor que no te factura | FESP | FESP |
| Corregir hacia abajo una factura ya emitida | NCRE | — |
| Cobrar algo adicional sobre una factura ya emitida | NDEB | — |
| Cobro de un servicio exento (entidad con personería) | RECI | RECI |
| Venta al exterior | FACT o FCAM con exportacion: true | FPEQ con exportacion: true |
Complementos por tipo
Cinco tipos exigen un bloque extra en el payload. QAPI lo aplica de forma estricta en las dos
direcciones: si falta, responde 422; si mandás el de otro tipo, también.
| Tipo | Campo obligatorio | Qué lleva |
|---|---|---|
NCRE, NDEB | referencia_nota + referencia_dte_origen | Identificación del documento que se ajusta |
FCAM, FCAP | abonos[] | Plan de pagos: cuota, vencimiento y monto |
FESP | retenciones | ISR e IVA retenidos al proveedor |
Cualquiera con exportacion: true | exportacion_info (salvo notas) | Consignatario, comprador e INCOTERM |
El detalle campo por campo está en Objeto Factura.
Reglas especiales por tipo
Pequeño Contribuyente — FPEQ, FCAP y sus demás documentos
- El emisor debe tener
afiliacion_iva: "PEQ"(en live, además, debe coincidir con la afiliación configurada del emisor — un emisor GEN no puede emitir FPEQ ni viceversa) - Los items no trasladan IVA — enviá el impuesto con
monto_gravable: 0ymonto_impuesto: 0 - La regla es del régimen, no del tipo: si el emisor es
PEQ, sus documentos no trasladan IVA y la validación 13 rechaza cualquiermonto_impuesto > 0. La excepción es la factura especial (FESP), que sí lleva el IVA de la operación porque lo retiene el comprador - El total del item es
precio_unitario × cantidad − descuento(sin gross-up de IVA) - La frase estándar es tipo 3, escenario 1 ("No genera derecho a crédito fiscal")
FCAPes además una cambiaria: llevaabonos[]
NCRE y NDEB — Notas de Crédito y Débito
Necesitan dos cosas: a qué documento ajustan y desde cuándo.
Llevan además una frase del tipo 1 (retención del ISR), la misma que declara la factura
del emisor — normalmente 1/1. Los ejemplos oficiales de la SAT muestran las notas sin
frases, pero el certificador la exige, así que QAPI la pide también: sin ella el request
responde 422.
El receptor de una nota no puede ser CF: el ajuste es sobre el documento de alguien
identificado. Y como la SAT exige además que ese receptor coincida con el del documento
origen, una factura emitida a consumidor final no puede ajustarse con una nota. El resto de
las condiciones del origen —debe estar vigente, ser FACT o FCAM, y del mismo emisor— están
en Cuál emitir en cada caso y en
Reglas SAT.
Si la nota no es de exportación y lleva una frase del tipo 4 (exento o no afecto al IVA),
el único escenario válido es el 22 — "Factura origen no incluye IVA".
Toda nota identifica al documento origen por UUID y por serie y número: serie_origen y
numero_origen son obligatorios. Los dos salen de la factura original — son los campos
serie y numero_dte que devuelve GET /v1/invoices/:id una vez certificada.
{
"tipo_dte": "NCRE",
"referencia_dte_origen": "550e8400-e29b-41d4-a716-446655440000",
"referencia_nota": {
"fecha_emision_origen": "2026-06-01",
"serie_origen": "A5F2C1B8",
"numero_origen": "1837",
"motivo_ajuste": "Devolución de mercadería"
}
}Si el documento original no es FEL (régimen de papel o FACE1) no hay UUID que referenciar:
marcá regimen_antiguo: true y mandá el número de resolución en lugar del UUID. La serie y el
número siguen siendo obligatorios.
{
"referencia_nota": {
"fecha_emision_origen": "2021-03-15",
"regimen_antiguo": true,
"numero_autorizacion_origen": "2021-1-1-1",
"serie_origen": "A",
"numero_origen": "123"
}
}FCAM y FCAP — Facturas Cambiarias
Lo que las distingue de una factura normal es el plan de abonos: por lo demás llevan las mismas
frases y el mismo IVA que la factura de su régimen (FCAM como FACT, FCAP como FPEQ).
La suma de los abonos debe ser igual al total del documento (tolerancia ±0.01) o el request
falla con 422.
{
"tipo_dte": "FCAM",
"abonos": [
{ "numero_abono": 1, "fecha_vencimiento": "2026-07-08", "monto_abono": 56.00 },
{ "numero_abono": 2, "fecha_vencimiento": "2026-08-08", "monto_abono": 56.00 }
]
}Como el total lo recalcula QAPI a partir de los items, cuadrá los abonos contra
precio_unitario × cantidad − descuento + impuestos, no contra el precio base.
FESP — Factura Especial
La emite el comprador por una compra a alguien que no puede facturar, y le retiene los impuestos. Va sin frases.
{
"tipo_dte": "FESP",
"retenciones": {
"retencion_isr": 5.00,
"retencion_iva": 12.00
}
}retencion_iva es opcional. Lo retenido no puede superar el total del documento. El campo
total_menos_retenciones no se envía: lo calcula QAPI (gran_total menos las retenciones),
igual que el gran_total.
El único impuesto que admite es el IVA. Dos restricciones más: el receptor no puede ser CF —la factura especial identifica al
proveedor— y, si el emisor declara tipo_personeria, esa personería tiene que habilitar
FESP: una cooperativa (710) o un centro educativo público (738) emiten recibos pero no
facturas especiales.
RECI — Recibo
Comprobante de los servicios exentos que prestan asociaciones, fundaciones, instituciones educativas, de asistencia o de servicio social y entidades religiosas (art. 7 num. 13 y art. 8 num. 1 y 2 de la Ley del IVA). Lleva al menos una frase.
Un recibo no admite ningún impuesto, lo emita quien lo emita: el bloque impuestos va con
el patrón en cero (monto_gravable: 0 y monto_impuesto: 0), que es la forma de declarar que
no hay traslado.
Recibo de un emisor Pequeño Contribuyente
QAPI acepta el request, pero el certificador rechazó un recibo emitido por un emisor PEQ común, sin personería registrada. Si tu entidad tiene personería (una asociación afiliada como Pequeño Contribuyente, por ejemplo), ese caso todavía no está verificado: escribinos a soporte antes de emitirlo en live y lo consultamos con el certificador — esa gestión es nuestra, no tuya.
emisor.tipo_personeria es obligatorio en el recibo — la SAT exige la casilla de
personería en este documento:
{
"tipo_dte": "RECI",
"emisor": {
"nit": "12345678",
"tipo_personeria": 725,
"...": "resto del emisor"
}
}El código sale del RTU del emisor. Los más frecuentes: 719 asociación civil, 725
asociación educativa, cultural o deportiva, 733 ONG, 735 iglesia católica, 736 otra
entidad religiosa, 2635 fundación, 2744 universidad privada. Un código que no exista en el
catálogo, o que no habilite el documento, devuelve 422.
No hay una "frase del recibo": la frase depende de por qué ese cobro está exento, no del
tipo de documento. El ejemplo del kit del certificador usa tipo_frase: 4, codigo_escenario: 8,
que declara cuotas de centros educativos exentas de IVA — si tu recibo no documenta una
matrícula, esa no es tu frase. Elegila con tu contador del catálogo de frases de la
SAT (Catalogos/CatalogoFrases-0.6.0.json) — QAPI valida que el par exista.
Exportaciones
La marca y el complemento son dos cosas distintas. exportacion: true pone el atributo
Exp="SI" en el DTE; exportacion_info agrega el bloque con el consignatario:
{
"exportacion": true,
"exportacion_info": {
"nombre_consignatario": "IMPORTADORA DEL SUR S.A.",
"direccion_consignatario": "Av. Central 100, San José",
"pais_consignatario": "COSTA RICA",
"incoterm": "FOB"
}
}Los tres campos obligatorios del complemento son nombre_consignatario,
direccion_consignatario y pais_consignatario. El incoterm es condicional: hace falta
cuando la exportación incluye bienes (alguna línea con tipo: "B") y no corresponde en una
exportación de solo servicios.
Reglas de la exportación:
- Con la marca va el complemento. Si mandás
exportacion: truetenés que mandarexportacion_info; la única excepción son las notas. - La frase es obligatoria y es una sola:
tipo_frase: 4, codigo_escenario: 1("Exportaciones. Exenta del IVA, art. 7 núm. 2") enFACT,FCAM,NCREyNDEB. Cualquier otro escenario del tipo 4 cita el artículo equivocado. - El receptor debe ser
CFo un extranjero (receptor.tipo_id: "EXT"). - Un receptor con
tipo_id: "CUI"es incompatible con la exportación. RECIyFESPno admiten la marcaexportacion: true.- El complemento
exportacion_infono corresponde enNCRE,NDEB,RECIniFESP: una nota de crédito sí puede llevar la marca de exportación —hereda la del documento que ajusta— pero nunca el bloque del consignatario. exportacion_infosinexportacion: truedevuelve422.
Una nota de exportación va a receptor extranjero
Sale de cruzar dos reglas: una exportación exige receptor CF o extranjero, y una nota no
admite CF. Queda una sola combinación válida: receptor.tipo_id: "EXT". Ni consumidor
final ni un NIT nacional.
La contingencia no es un tipo de DTE
Emitir en contingencia (cuando la SAT no está disponible) no se pide con un tipo_dte: es un
flujo aparte del certificador. QAPI todavía no lo expone.
El campo tipo_dte en el request
{
"tipo_dte": "FACT",
...
}El valor debe ser exactamente uno de los 12 códigos en mayúsculas. Cualquier otro valor
devuelve 422 VALIDATION_ERROR con invalid_params indicando el campo tipo_dte; uno de los
cuatro pendientes devuelve 501 NOT_IMPLEMENTED.