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

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ónEndpoint
Crear factura de pruebaPOST /v1/sandbox/invoices
Consultar una factura de pruebaGET /v1/invoices/:id
Anular una factura de pruebaPOST /v1/invoices/:id/cancel
Ver tu uso del sandbox de hoyGET /v1/sandbox/usage
Listar las pruebas creadas hoyGET /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_sat ficticio pero con el formato correcto: un UUID v4 aleatorio, en mayúsculas como los de la SAT (sirve como referencia_dte_origen de una nota de prueba)
  • Emite con serie QAPI y un numero_dte numé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):

PlanPruebas por tipo de DTE al día
Basic10
Starter30
Business50

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.

En esta página