Entorno Sandbox
Probá tu integración sin cargo real usando el entorno de prueba de QAPI con el certificador MOCK.
El sandbox de QAPI te permite emitir facturas de prueba que nunca llegan a la SAT pero siguen exactamente el mismo flujo que producción.
Cero costo, misma lógica
Las facturas emitidas en sandbox no consumen tu cuota de DTEs del plan y no tienen
validez tributaria. Las validaciones y los estados funcionan exactamente igual.
También disparan webhooks: usan tu webhook global (el de la cuenta) o el webhook_url
que envíes en el request, y llegan marcados con data.test: true para distinguirlos de las
emisiones reales. Mirá Webhooks para el detalle.
Endpoints sandbox
Solo la creación tiene su propio endpoint. La consulta y la anulación se hacen
por los endpoints normales (la respuesta de creación ya trae el link en links.self):
| Acción | Endpoint |
|---|---|
| Crear factura de prueba | POST /v1/sandbox/invoices |
| Consultar una factura de prueba | GET /v1/invoices/:id |
| Anular una factura de prueba | POST /v1/invoices/:id/cancel |
| Ver tu uso del sandbox de hoy | GET /v1/sandbox/usage |
| Listar las pruebas creadas hoy | GET /v1/sandbox/history |
Podés autenticarte con tu API key qapi_test_* o qapi_live_*: el sandbox acepta las dos y
siempre certifica con MOCK, sin importar cuál uses.
Tu referencia_interna se guarda con el prefijo [SANDBOX] para distinguir las pruebas
en tus listados.
POST necesita acceso completo
POST /v1/sandbox/invoices requiere el scope invoices:write (una key de solo lectura
recibe 403 FORBIDDEN). GET /v1/sandbox/usage y /history solo piden invoices:read.
Emitir una factura de prueba
# fecha_emision: ahora, en hora de Guatemala (no puede ser futura ni de hace más de 5 días)
FECHA=$(TZ=UTC+6 date +%Y-%m-%dT%H:%M:%S-06:00)
curl -X POST https://api.dtevia.com.gt/v1/sandbox/invoices \
-H "Authorization: Bearer qapi_test_xxxxxxxxxxxx" \
-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 Av 1-36 Z1", "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": "Prueba de integración",
"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('https://api.dtevia.com.gt/v1/sandbox/invoices', {
method: 'POST',
headers: {
Authorization: 'Bearer qapi_test_xxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify(invoicePayload),
});
const invoice = await res.json();
// invoice.sandbox === true
// invoice.status === "PROCESSING" → se certifica casi instantáneamente
// invoice.links.self === "/v1/invoices/inv_..." → consultala ahíres = httpx.post(
"https://api.dtevia.com.gt/v1/sandbox/invoices",
json=invoice_payload,
headers={"Authorization": "Bearer qapi_test_xxxxxxxxxxxx"},
)
invoice = res.json()
# invoice["sandbox"] == True
# invoice["status"] == "PROCESSING"Los ocho tipos, con sus complementos
El body de arriba es FACT, pero el sandbox acepta los mismos tipos que producción —
FPEQ, FCAM, FCAP, FESP, NCRE, NDEB y RECI — con sus mismas reglas: el IVA
en 0/0 del Pequeño Contribuyente, los abonos que cuadran con el total, la
referencia_nota de una nota de crédito. Es el lugar para ensayar un tipo nuevo antes de
emitirlo en live: ver Tipos de DTE y el ejemplo completo en
Emitir una Factura.
Certificador MOCK
Comportamiento del MOCK
En sandbox, QAPI usa el certificador MOCK que:
- Certifica instantáneamente (sin esperar a la SAT real)
- Genera un
uuid_satficticio pero con el formato correcto: un UUID v4 aleatorio, en mayúsculas como los de la SAT (sirve comoreferencia_dte_origende una nota de prueba) - Emite con serie
QAPIy unnumero_dtenumérico secuencial
{
"id": "inv_V1StGXR8_Z5jdHi6",
"status": "CERTIFIED",
"certificador": "MOCK",
"uuid_sat": "A1B2C3D4-E5F6-A7B8-C9D0-E1F2A3B4C5D6",
"serie": "QAPI",
"numero_dte": 1,
"pdf_url": "https://api.dtevia.com.gt/v1/invoices/inv_V1StGXR8_Z5jdHi6/pdf"
}pdf_url funciona igual en sandbox que en producción
A diferencia del uuid_sat (ficticio en MOCK), el pdf_url sí es un link real en
los dos entornos: en producción redirige al PDF del certificador; en sandbox, QAPI
genera el PDF él mismo (marcado como "DOCUMENTO DE PRUEBA") y lo devuelve directo. Es
el mismo GET /v1/invoices/:id/pdf en ambos casos — tu integración no necesita
distinguir el entorno para mostrar o descargar el PDF.
Restricciones y diferencias
Comparación con producción
Propiedad
Tipo
Límite de uso
El sandbox tiene un límite diario por tipo de DTE según tu plan (el día se calcula en hora de Guatemala, UTC-6):
| Plan | Pruebas por tipo de DTE al día |
|---|---|
| Basic | 10 |
| Starter | 30 |
| Business | 50 |
Si lo superás, recibirás 429 SANDBOX_LIMIT_REACHED:
{
"type": "https://docs.dtevia.com.gt/errors/sandbox-limit-reached",
"title": "SANDBOX_LIMIT_REACHED",
"status": 429,
"detail": "Límite diario de 30 pruebas por tipo DTE alcanzado. Reinicia mañana.",
"context": { "limit": 30, "used": 30, "tipo_dte": "FACT" }
}El cupo es uno solo para las dos formas de probar
El mismo contador cubre POST /v1/sandbox/invoices (el Playground) y
POST /v1/invoices con una API key qapi_test_. Ambas certifican con MOCK, así que las
pruebas diarias por tipo de DTE se reparten entre las dos — el cupo no se duplica por
endpoint. Si integrás contra /v1/invoices con tu key de prueba y ya usaste el
Playground hoy, arrancás con ese consumo encima.
Monitorear tu uso
Consultá cuántas pruebas llevás hoy con GET /v1/sandbox/usage:
{ "date": "2026-06-10", "usage": { "FACT": 3 }, "limit_per_type": 30, "total_today": 3 }Y lista las facturas de prueba creadas hoy con GET /v1/sandbox/history:
{
"data": [
{ "id": "inv_...", "status": "CERTIFIED", "tipo_dte": "FACT", "gran_total": 112, "moneda": "GTQ", "created_at": "2026-06-10T15:00:00.000Z" }
]
}No hay 'limpiar sandbox'
Las facturas de prueba no se borran: quedan en tu historial marcadas con
certificador: "MOCK" y referencia_interna con prefijo [SANDBOX]. Para
excluirlas de tus listados de producción usa GET /v1/invoices?exclude_mock=true.