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

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.json

Necesitá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 }]
  }
]

En esta página