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
| Prefijo | Entorno | Descripción |
|---|---|---|
qapi_test_... | Test | Key del Proyecto Sandbox. Solo certificador MOCK. No consume cuota. No toca la SAT. |
qapi_live_... | Live | Key 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:
| Acceso | Scopes | Permite |
|---|---|---|
| Completo | invoices:write + invoices:read | Emitir, anular y consultar facturas |
| Solo lectura | invoices:read | Solo 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
| Respuesta | Qué pasó |
|---|---|
401 UNAUTHORIZED | Falta el header Authorization o no tiene el formato Bearer <api_key> |
401 INVALID_API_KEY | La key no existe o fue revocada (por ejemplo, al regenerarla o al archivar su proyecto) |
403 FORBIDDEN | La 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()