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

Primer DTE en 5 minutos

De tu API key de prueba a tu primera factura certificada, paso a paso con código real.

Esta guía te lleva desde cero hasta emitir tu primera factura de prueba certificada. Usaremos el entorno test (certificador MOCK) para que no haya riesgo de emitir facturas reales.

En entorno test (qapi_test_...) el certificador es siempre MOCK. No se conecta a la SAT, no consume cuota y la respuesta es instantánea. Ideal para desarrollo e integración.


Crear tu cuenta y copiar la API key

Registrate en dtevia.com.gt/register. Al crear la cuenta se genera tu Proyecto Sandbox con su API key de prueba (qapi_test_...).

En el dashboard, entrá a Proyectos → Proyecto Sandbox y copiá la key. Guardala como una variable de entorno de tu servidor:

QAPI_API_KEY=qapi_test_abc123xyz...

La key no se muestra, se copia

El dashboard nunca vuelve a mostrar la key en pantalla, pero podés volver a copiarla al portapapeles cuando quieras desde el proyecto. Ver Autenticación para los niveles de acceso de cada key.

Confirmar tu correo

Antes de emitir, confirmá la dirección con la que te registraste. Te llega un correo con un enlace: abrilo y hacé clic en "Confirmar mi correo".

Sin este paso, los ejemplos de abajo devuelven 403

Hasta confirmar el correo, Facturas y Sandbox están bloqueados y la API responde EMAIL_NOT_VERIFIED. El bloqueo es de la cuenta, así que alcanza igual a tu API key y al botón de probar de esta documentación — generar otra key no lo evita.

Es un paso de una sola vez. Si el correo no llegó o el enlace venció (duran 24 horas), pedí uno nuevo desde el aviso que aparece en el panel; cada enlace nuevo invalida el anterior.

Emitir la factura

Con tu API key, emití una factura de tipo FACT (Régimen General) — el caso más simple para este ejemplo. QAPI emite ocho tipos en total (facturas, notas de crédito y débito, cambiarias, factura especial y recibos): ver Tipos de DTE. El campo precio_unitario va sin IVA — QAPI calcula y valida el IVA automáticamente. La fecha_emision es la fecha y hora actual de Guatemala (-06:00): no puede ser futura ni de hace más de 5 días, así que los ejemplos la calculan al momento.

# Ahora, en hora de Guatemala (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)

curl -X POST https://api.dtevia.com.gt/v1/invoices \
  -H "Authorization: Bearer qapi_test_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_dte": "FACT",
    "moneda": "GTQ",
    "fecha_emision": "'"$FECHA"'",
    "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
          }
        ]
      }
    ]
  }'
const API_KEY = process.env.QAPI_TEST_KEY!;
const BASE = 'https://api.dtevia.com.gt/v1';

// Ahora, en hora de Guatemala (UTC-6)
const fechaGT = new Date(Date.now() - 6 * 3600_000).toISOString().slice(0, 19) + '-06:00';

const invoice = {
  tipo_dte: 'FACT',
  moneda: 'GTQ',
  fecha_emision: fechaGT,
  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,
    }],
  }],
};

const res = await fetch(`${BASE}/invoices`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(invoice),
});

const { id, status } = await res.json();
// status === "PROCESSING" — ahora hay que hacer polling
import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.dtevia.com.gt/v1',
  headers: { Authorization: `Bearer ${process.env.QAPI_TEST_KEY}` },
});

const { data } = await client.post('/invoices', {
  tipo_dte: 'FACT',
  moneda: 'GTQ',
  // Ahora, en hora de Guatemala (UTC-6)
  fecha_emision: new Date(Date.now() - 6 * 3600_000).toISOString().slice(0, 19) + '-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,
    }],
  }],
});

const { id, status } = data; // status === "PROCESSING"
import requests
from datetime import datetime, timezone, timedelta

API_KEY = 'qapi_test_TU_API_KEY'
BASE = 'https://api.dtevia.com.gt/v1'
headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json',
}

payload = {
    'tipo_dte': 'FACT',
    'moneda': 'GTQ',
    # Ahora, en hora de Guatemala
    'fecha_emision': datetime.now(timezone(timedelta(hours=-6))).isoformat(timespec='seconds'),
    '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,
        }],
    }],
}

res = requests.post(f'{BASE}/invoices', json=payload, headers=headers)
data = res.json()
invoice_id = data['id']  # status === "PROCESSING"

Respuesta (202)

{
  "id": "inv_01jx...",
  "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_01jx..." }
}

¿Por qué 202 y no 200?

La certificación es asíncrona. QAPI acepta la factura, la encola y responde inmediatamente con PROCESSING. El estado final (CERTIFIED o FAILED) llega en segundos vía polling o webhook.

Consultar el estado (polling)

Usá el id de la respuesta anterior para consultar el estado hasta que sea CERTIFIED.

curl https://api.dtevia.com.gt/v1/invoices/inv_01jx... \
  -H "Authorization: Bearer qapi_test_TU_API_KEY"
async function waitForCertification(invoiceId: string, apiKey: string) {
  const BASE = 'https://api.dtevia.com.gt/v1';
  const headers = { Authorization: `Bearer ${apiKey}` };

  for (let i = 0; i < 10; i++) {
    const res = await fetch(`${BASE}/invoices/${invoiceId}`, { headers });
    const invoice = await res.json();

    if (invoice.status === 'CERTIFIED') return invoice;
    if (invoice.status === 'FAILED') throw new Error(invoice.error_message);

    await new Promise(r => setTimeout(r, 1000)); // espera 1 segundo
  }
  throw new Error('Timeout esperando certificación');
}

const certified = await waitForCertification(id, API_KEY);
console.log('UUID SAT:', certified.uuid_sat);
console.log('Número DTE:', certified.numero_dte);
console.log('PDF:', certified.pdf_url);
import time

def wait_for_certification(invoice_id, api_key, max_attempts=10):
    url = f'{BASE}/invoices/{invoice_id}'
    headers = {'Authorization': f'Bearer {api_key}'}

    for _ in range(max_attempts):
        res = requests.get(url, headers=headers)
        invoice = res.json()

        if invoice['status'] == 'CERTIFIED':
            return invoice
        if invoice['status'] == 'FAILED':
            raise Exception(invoice['error_message'])

        time.sleep(1)

    raise TimeoutError('Tiempo de espera agotado')

certified = wait_for_certification(invoice_id, API_KEY)
print('UUID SAT:', certified['uuid_sat'])
print('Número DTE:', certified['numero_dte'])
print('PDF:', certified['pdf_url'])

Respuesta certificada

{
  "id": "inv_01jx...",
  "status": "CERTIFIED",
  "tipo_dte": "FACT",
  "gran_total": 112.00,
  "moneda": "GTQ",
  "numero_acceso": 543219876,
  "certificador": "MOCK",
  "uuid_sat": "A1B2C3D4-E5F6-A7B8-C9D0-E1F2A3B4C5D6",
  "serie": "QAPI",
  "numero_dte": 1,
  "pdf_url": "https://api.dtevia.com.gt/v1/invoices/inv_01jx.../pdf",
  "certified_at": "2026-06-08T16:00:02.000Z"
}

¡Listo!

Tu primera factura está certificada. En entorno test el certificador es MOCK, así que:

  • uuid_sat es un UUID generado localmente (no es un UUID real de la SAT)
  • certificador aparece como "MOCK"
  • El pdf_url sí abre un PDF — QAPI lo genera al vuelo con la marca de agua "DOCUMENTO DE PRUEBA", para que puedas probar tu integración de punta a punta sin tocar producción. Es el mismo endpoint que usarías en live (GET /v1/invoices/:id/pdf); no hace falta ninguna lógica especial para sandbox.

Para emitir facturas reales, necesitás cambiar a entorno live — consultá la guía de Entornos.


¿Qué sigue?

  • Entornos — diferencias entre test y live, y cómo activar el certificador real
  • Emitir Factura — guía completa con todos los campos y casos de uso
  • Webhooks — recibe notificaciones en vez de hacer polling
  • Manejo de Errores — qué hacer cuando algo falla

En esta página