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

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ónPuede emitir
GEN — Régimen GeneralFACT, FCAM, FESP, NCRE, NDEB, RECI
PEQ — Pequeño ContribuyenteFPEQ, 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

TipoDocumentoEstado
FACTFactura — documento estándar de venta de bienes o servicios Certificado en vivo
FPEQFactura Pequeño Contribuyente — emisores con afiliación PEQ. No traslada IVA Certificado en vivo
FCAMFactura Cambiaria — venta al crédito, con plan de abonos y vencimientos Certificado en vivo
FCAPFactura Cambiaria de Pequeño Contribuyente — la cambiaria del régimen PEQ Certificado en vivo
FESPFactura Especial — la emite el comprador por cuenta de un proveedor no inscrito, reteniéndole ISR e IVA Certificado en vivo
NCRENota de Crédito — ajuste negativo o devolución sobre un documento anterior Certificado en vivo
NDEBNota de Débito — ajuste positivo sobre un documento anterior Certificado en vivo
RECIRecibo — comprobante de un cobro Certificado en vivo
RDONRecibo por Donación Próximamente
NABNNota de Abono Próximamente
FACAFactura de Contribuyente Agropecuario Próximamente
FCCAFactura 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ónRégimen GeneralPequeño Contribuyente
Venta al contado, bienes o serviciosFACTFPEQ
Venta al crédito, en cuotas con vencimientoFCAMFCAP
Le comprás a un proveedor que no te facturaFESPFESP
Corregir hacia abajo una factura ya emitidaNCRE—
Cobrar algo adicional sobre una factura ya emitidaNDEB—
Cobro de un servicio exento (entidad con personería)RECIRECI
Venta al exteriorFACT o FCAM con exportacion: trueFPEQ 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.

TipoCampo obligatorioQué lleva
NCRE, NDEBreferencia_nota + referencia_dte_origenIdentificación del documento que se ajusta
FCAM, FCAPabonos[]Plan de pagos: cuota, vencimiento y monto
FESPretencionesISR e IVA retenidos al proveedor
Cualquiera con exportacion: trueexportacion_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: 0 y monto_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 cualquier monto_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")
  • FCAP es además una cambiaria: lleva abonos[]

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: true tenés que mandar exportacion_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") en FACT, FCAM, NCRE y NDEB. Cualquier otro escenario del tipo 4 cita el artículo equivocado.
  • El receptor debe ser CF o un extranjero (receptor.tipo_id: "EXT").
  • Un receptor con tipo_id: "CUI" es incompatible con la exportación.
  • RECI y FESP no admiten la marca exportacion: true.
  • El complemento exportacion_info no corresponde en NCRE, NDEB, RECI ni FESP: 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_info sin exportacion: true devuelve 422.

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.

En esta página