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

Autenticación

Cómo autenticar tu integración con una API key (qapi_test_ / qapi_live_) y qué permite cada nivel de acceso.

Tu integración se autentica con una API key: un solo header en cada request, sin expiración ni renovación.

API Keys

Cada key pertenece a un proyecto y su entorno lo define el proyecto. Tu Proyecto Sandbox y su key de prueba se crean automáticamente al registrar tu cuenta; las keys de tus proyectos live las generás en el dashboard, dentro de cada proyecto.

Formato

PrefijoEntornoDescripción
qapi_test_...TestKey del Proyecto Sandbox. Solo certificador MOCK. No consume cuota. No toca la SAT.
qapi_live_...LiveKey de un proyecto live. Usa el certificador real. Consume la cuota del proyecto. Factura real ante la SAT.

La API key es recuperable

No la perdés si no la copiaste al crearla: el dashboard nunca vuelve a mostrarla en pantalla, pero podés volver a copiarla al portapapeles cuando la necesites, dentro del proyecto. Cada proyecto puede tener hasta dos keys activas a la vez — una de acceso completo y una de solo lectura (ver tabla abajo) — y cada una se rota por separado: para renovar una, regenerala (eso revoca solo la anterior de ese mismo tipo). Cada vez que se copia, queda registrado en el log de auditoría de tu cuenta.

Uso en requests

Enviá la API key en el header Authorization con el prefijo Bearer:

Authorization: Bearer qapi_test_abc123xyz...

Usala solo desde tu servidor

La API key emite facturas a nombre de tu NIT: guardala como un secreto (variable de entorno o gestor de secretos) y hacé las llamadas desde tu backend. No la incluyas en el código de una página web ni de una app móvil.

Acceso de la key (scopes)

Al crear una key elegís su nivel de acceso, y el API lo hace cumplir:

AccesoScopesPermite
Completoinvoices:write + invoices:readEmitir, anular y consultar facturas
Solo lecturainvoices:readSolo consultar (GET) — no puede emitir ni anular

Una key solo lectura que intente emitir (POST /v1/invoices) o anular (POST /v1/invoices/:id/cancel) recibe 403 FORBIDDEN indicando el scope que le falta. Útil, por ejemplo, para una key de un panel de monitoreo que solo lee y nunca debe facturar.

Cómo elegirlo

Lo elegís al generar la key en el dashboard (dentro de cada proyecto). La key del Sandbox y la inicial se crean con acceso completo. Al regenerar una key se conserva su mismo acceso.

Si la key no autentica

RespuestaQué pasó
401 UNAUTHORIZEDFalta el header Authorization o no tiene el formato Bearer <api_key>
401 INVALID_API_KEYLa key no existe o fue revocada (por ejemplo, al regenerarla o al archivar su proyecto)
403 FORBIDDENLa key es válida pero no tiene permiso para esa acción

Ejemplos de autenticación

curl -X GET https://api.dtevia.com.gt/v1/invoices \
  -H "Authorization: Bearer qapi_test_TU_API_KEY"
const BASE = 'https://api.dtevia.com.gt/v1';
const API_KEY = process.env.QAPI_API_KEY; // qapi_test_... o qapi_live_...

const res = await fetch(`${BASE}/invoices`, {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
});

const data = await res.json();
import os
import requests

BASE = 'https://api.dtevia.com.gt/v1'
API_KEY = os.environ['QAPI_API_KEY']  # qapi_test_... o qapi_live_...

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json',
}

response = requests.get(f'{BASE}/invoices', headers=headers)
data = response.json()

En esta página