Emitir una Factura
Guía paso a paso para emitir tu primera factura electrónica FACT con QAPI.
Esta guía cubre el flujo completo: construir el request, manejar el 202 PROCESSING,
hacer polling hasta CERTIFIED y obtener el PDF final.
QAPI usa un flujo asíncrono. El POST /v1/invoices responde 202 inmediatamente
— la certificación ocurre en segundo plano. El 202 no confirma la emisión: esperá a que la
factura quede CERTIFIED.
Flujo completo
Construir el request
Esta guía usa las dos facturas base: FACT (Régimen General) y FPEQ (Pequeño
Contribuyente). Cuál podés emitir en live lo define la afiliacion_iva de tu emisor:
GEN factura con FACT, PEQ con FPEQ.
QAPI emite además FCAM, FCAP, FESP, NCRE, NDEB y RECI — cada uno con su
complemento obligatorio en el payload. Los cuatro restantes del catálogo devuelven
501 NOT_IMPLEMENTED. Todo el detalle en Tipos de DTE.
Cambiá la fecha_emision antes de enviar
La fecha_emision de los ejemplos es ilustrativa. Tiene que ser la fecha y hora actual
de Guatemala: el API rechaza con 422 una fecha futura o de hace más de 5 días. Ver
Zona horaria.
{
"tipo_dte": "FACT",
"moneda": "GTQ",
"fecha_emision": "2026-06-08T10:00:00-06:00",
"emisor": {
"nit": "12345678",
"nombre": "Mi Empresa S.A.",
"nombre_comercial": "Mi Empresa",
"codigo_establecimiento": 1,
"afiliacion_iva": "GEN",
"direccion": {
"calle": "6a Avenida 1-36 Zona 1",
"municipio": "Guatemala",
"departamento": "Guatemala",
"codigo_postal": "01001",
"pais": "GT"
},
"correo": "facturacion@miempresa.com"
},
"receptor": {
"id": "CF",
"tipo_id": "NIT",
"nombre": "Consumidor Final"
},
"frases": [
{ "tipo_frase": 1, "codigo_escenario": 1 }
],
"items": [
{
"tipo": "S",
"cantidad": 1,
"unidad_medida": "UND",
"descripcion": "Servicio de consultoría",
"precio_unitario": 100.00,
"descuento": 0,
"impuestos": [
{
"nombre": "IVA",
"codigo_unidad_gravable": 1,
"monto_gravable": 100.00,
"monto_impuesto": 12.00
}
]
}
],
"metadata": {
"referencia_interna": "ORD-2026-001"
}
}precio_unitario siempre SIN IVA
El precio_unitario es el precio antes de IVA, y QAPI valida que
monto_impuesto = monto_gravable × 0.12 y que monto_gravable cuadre con
precio_unitario × cantidad − descuento. Si mandás el precio con IVA incluido, el
monto_gravable no cuadra y recibís 422 VALIDATION_ERROR; si forzás que cuadre, el IVA se
cobra dos veces.
{
"tipo_dte": "FPEQ",
"moneda": "GTQ",
"fecha_emision": "2026-06-08T10:00:00-06:00",
"emisor": {
"nit": "12345678",
"nombre": "Mi Empresa S.A.",
"nombre_comercial": "Mi Empresa",
"codigo_establecimiento": 1,
"afiliacion_iva": "PEQ",
"direccion": {
"calle": "6a Avenida 1-36 Zona 1",
"municipio": "Guatemala",
"departamento": "Guatemala",
"codigo_postal": "01001",
"pais": "GT"
},
"correo": "facturacion@miempresa.com"
},
"receptor": {
"id": "CF",
"tipo_id": "NIT",
"nombre": "Consumidor Final"
},
"frases": [
{ "tipo_frase": 3, "codigo_escenario": 1 }
],
"items": [
{
"tipo": "S",
"cantidad": 1,
"unidad_medida": "UND",
"descripcion": "Servicio de consultoría",
"precio_unitario": 100.00,
"descuento": 0,
"impuestos": [
{
"nombre": "IVA",
"codigo_unidad_gravable": 1,
"monto_gravable": 0,
"monto_impuesto": 0
}
]
}
],
"metadata": {
"referencia_interna": "ORD-2026-001"
}
}El Pequeño Contribuyente no lleva IVA — ni siquiera en 0 aparte
Un emisor PEQ no traslada IVA en sus documentos —salvo en la factura especial, donde el IVA
es de la operación y lo retiene el comprador—. El bloque impuestos igual va, pero con
monto_gravable: 0 y monto_impuesto: 0 (Validación 13) — no con el 12% como en FACT.
El total del item es precio_unitario × cantidad − descuento, sin gross-up. La frase
estándar de FPEQ es tipo_frase: 3, codigo_escenario: 1 ("No genera derecho a crédito
fiscal"), no la frase 1 de FACT.
Enviar el request
curl -X POST https://api.dtevia.com.gt/v1/invoices \
-H "Authorization: Bearer qapi_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d @factura.jsonNecesitás una key de acceso completo
POST /v1/invoices requiere el scope invoices:write. Una key de solo lectura
recibe 403 FORBIDDEN. Ver Autenticación.
const res = await fetch('https://api.dtevia.com.gt/v1/invoices', {
method: 'POST',
headers: {
Authorization: 'Bearer qapi_live_xxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify(invoicePayload),
});
const { id, status } = await res.json();
// status === "PROCESSING"import axios from 'axios';
const { data } = await axios.post(
'https://api.dtevia.com.gt/v1/invoices',
invoicePayload,
{ headers: { Authorization: 'Bearer qapi_live_xxxxxxxxxxxx' } }
);
// data.status === "PROCESSING"import httpx
res = httpx.post(
"https://api.dtevia.com.gt/v1/invoices",
json=invoice_payload,
headers={"Authorization": "Bearer qapi_live_xxxxxxxxxxxx"},
)
data = res.json()
# data["status"] == "PROCESSING"La respuesta 202 incluye el id de la factura y el estado PROCESSING:
{
"id": "inv_V1StGXR8_Z5jdHi6",
"status": "PROCESSING",
"tipo_dte": "FACT",
"gran_total": 112.00,
"moneda": "GTQ",
"numero_acceso": 543219876,
"created_at": "2026-06-08T16:00:00.000Z",
"links": { "self": "/v1/invoices/inv_V1StGXR8_Z5jdHi6" }
}Esperar la certificación
Podés usar polling con backoff o configurar un webhook para
recibir invoice.certified automáticamente.
async function waitForCertification(id: string, apiKey: string) {
const delays = [1000, 2000, 2000, 3000, 5000, 5000, 10000];
for (const delay of delays) {
await new Promise(r => setTimeout(r, delay));
const res = await fetch(`https://api.dtevia.com.gt/v1/invoices/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const invoice = await res.json();
if (invoice.status === 'CERTIFIED') return invoice;
if (invoice.status === 'FAILED') throw new Error(invoice.error_message);
}
throw new Error('Timeout esperando certificación');
}async function waitForCertification(id: string, apiKey: string) {
const delays = [1000, 2000, 2000, 3000, 5000, 5000, 10000];
for (const delay of delays) {
await new Promise(r => setTimeout(r, delay));
const { data } = await axios.get(
`https://api.dtevia.com.gt/v1/invoices/${id}`,
{ headers: { Authorization: `Bearer ${apiKey}` } }
);
if (data.status === 'CERTIFIED') return data;
if (data.status === 'FAILED') throw new Error(data.error_message);
}
throw new Error('Timeout esperando certificación');
}import time
def wait_for_certification(invoice_id: str, api_key: str) -> dict:
delays = [1, 2, 2, 3, 5, 5, 10]
for delay in delays:
time.sleep(delay)
res = httpx.get(
f"https://api.dtevia.com.gt/v1/invoices/{invoice_id}",
headers={"Authorization": f"Bearer {api_key}"},
)
invoice = res.json()
if invoice["status"] == "CERTIFIED":
return invoice
if invoice["status"] == "FAILED":
raise Exception(invoice["error_message"])
raise TimeoutError("Timeout esperando certificación")Acceder al PDF certificado
Cuando el estado es CERTIFIED, el campo pdf_url contiene el enlace al PDF con sello SAT:
{
"id": "inv_V1StGXR8_Z5jdHi6",
"status": "CERTIFIED",
"uuid_sat": "550E8400-E29B-41D4-A716-446655440000",
"serie": "A",
"numero_dte": 42,
"pdf_url": "https://print.totaldoc.io/pdf?uuid=550E8400-...",
"certified_at": "2026-06-08T16:00:02.000Z"
}El pdf_url es la URL de la representación gráfica provista por el certificador.
Es un enlace estable — no expira. También podés usar GET /v1/invoices/:id/pdf,
que redirige (302) al mismo enlace en vez de tener que leer el campo del JSON.
El mismo endpoint sirve para sandbox
Si emitiste con una key qapi_test_ (certificador MOCK), GET /v1/invoices/:id/pdf
no redirige — devuelve directo los bytes del PDF (200, generado por QAPI, marcado
como "DOCUMENTO DE PRUEBA"). Es el mismo endpoint y el mismo pdf_url; no hace falta
ninguna lógica distinta según el entorno. Ver Entorno Sandbox.
Errores posibles de GET /:id/pdf
409 PDF_NOT_AVAILABLE si la factura todavía no está
certificada (no hay pdf_url aún). 502 PDF_URL_UNTRUSTED
si la URL guardada no corresponde a un dominio de certificador conocido — una red de
seguridad interna que en uso normal nunca deberías ver.
Consideraciones importantes
Zona horaria
Guatemala usa UTC-6. La fecha_emision es la fecha y hora actual de Guatemala, con el
offset -06:00: no puede ser futura (hay 5 minutos de tolerancia) ni de hace más de 5 días.
"fecha_emision": "2026-06-08T10:00:00-06:00"Para calcularla en tu código:
const fechaGT = new Date(Date.now() - 6 * 3600_000).toISOString().slice(0, 19) + '-06:00';from datetime import datetime, timedelta, timezone
fecha_gt = datetime.now(timezone(timedelta(hours=-6))).isoformat(timespec="seconds")# UTC+6 en notación POSIX = 6 horas detrás de UTC
FECHA=$(TZ=UTC+6 date +%Y-%m-%dT%H:%M:%S-06:00)No pegues -06:00 a la hora UTC
new Date().toISOString() devuelve la hora UTC. Cambiarle la Z por -06:00 deja la
fecha 6 horas en el futuro y el API la rechaza. Restale las 6 horas antes, como en el ejemplo.
Consumidor Final (CF)
Para ventas sin NIT específico, usa id: "CF" con tipo_id: "NIT":
"receptor": { "id": "CF", "tipo_id": "NIT", "nombre": "Consumidor Final" }Múltiples items
Podés incluir varios items en un mismo DTE. Cada uno con sus propios impuestos:
"items": [
{
"tipo": "S",
"cantidad": 2,
"unidad_medida": "HRS",
"descripcion": "Horas de desarrollo",
"precio_unitario": 150.00,
"descuento": 0,
"impuestos": [{ "nombre": "IVA", "codigo_unidad_gravable": 1, "monto_gravable": 300.00, "monto_impuesto": 36.00 }]
},
{
"tipo": "B",
"cantidad": 1,
"unidad_medida": "UND",
"descripcion": "Licencia anual",
"precio_unitario": 500.00,
"descuento": 50.00,
"impuestos": [{ "nombre": "IVA", "codigo_unidad_gravable": 1, "monto_gravable": 450.00, "monto_impuesto": 54.00 }]
}
]