Prueba tu integración sin cargo real usando el entorno de prueba de QAPI con el certificador MOCK.

Entorno Sandbox

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. Mira 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`

Puedes autenticarte con tu API key (qapi_test_* o qapi_live_*) o con tu JWT del dashboard — el sandbox acepta ambas. Tu referencia_interna se guarda con el prefijo [SANDBOX] para distinguir las pruebas en tus listados.

Emitir una factura de prueba

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": "2026-06-08T10:00:00-06:00",
    "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_..." → consúltala 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"

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 (derivado del contenido del DTE)
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://report.feel.com.gt/ingfacereport/ingfacereport_documento?uuid=A1B2C3D4-..."
}

El pdf_url de MOCK no resuelve — usa el visualizador del dashboard

pdf_url apunta al visor del certificador. Como el uuid_sat de MOCK no existe ante la SAT, ese enlace no mostrará un documento — es normal en sandbox. La factura de prueba sí se puede ver: en el detalle de la factura del dashboard, el botón "Ver factura" la renderiza en el visualizador integrado (con la marca "PRUEBA · sin validez SAT") y permite descargar el PDF generado. En producción el botón "PDF" descarga la representación gráfica oficial del certificador — el mismo enlace de pdf_url.

Restricciones y diferencias

Comparación con producción

Prop

Type

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
Starter	20
Business	20
Enterprise	50

Si lo superas, 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 20 pruebas por tipo DTE alcanzado. Reinicia mañana.",
  "invalid_params": [{ "limit": 20, "used": 20, "tipo_dte": "FACT" }]
}

Monitorear tu uso

Consulta cuántas pruebas llevas hoy con GET /v1/sandbox/usage:

{ "date": "2026-06-10", "usage": { "FACT": 3 }, "limit_per_type": 20, "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.

Entorno Sandbox

On this page