Emitir factura de prueba
Crea una factura de prueba usando siempre el certificador MOCK, sin importar el certificador del tenant. No tiene costo ni validez tributaria, y aplica las mismas 21 validaciones que producción.
La respuesta incluye links.self apuntando a GET /v1/invoices/{id}: las facturas de sandbox se consultan y anulan por los endpoints normales de Facturas — no existe un GET/cancel bajo /v1/sandbox.
Diferencias respecto de producción
- Sí dispara webhooks: usa el webhook de la cuenta o el
webhook_urldel request, y los eventos llevandata.test: truepara distinguirlos de emisiones reales. - No consume cuota del plan.
- Acepta los mismos tipos de DTE y los mismos complementos que producción: es el lugar para probar una nota de crédito o una factura cambiaria antes de emitirla en live.
referencia_internase prefija con[SANDBOX].- Límite diario de pruebas por tipo de DTE según el plan: basic 10, starter 30, business 50.
Autorización
ApiKeyAuth API key con prefijo qapi_test_ (Sandbox) o qapi_live_ (producción), enviada en el header Authorization: Bearer <api_key>. Se genera en el dashboard, dentro de cada proyecto.
Va en: header
Parámetros de cabecera
Mismo comportamiento que en POST /v1/invoices: evita duplicados en reintentos, ventana de 24 horas.
Cuerpo del request
application/json
Definiciones de TypeScript
Usá el tipo request body en TypeScript.
Cuerpo de la respuesta
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/sandbox/invoices" \ -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 Avenida 1-36 Zona 1", "municipio": "Guatemala", "departamento": "Guatemala", "codigo_postal": "01001", "pais": "GT" }, "correo": "facturacion@miempresa.com" }, "receptor": { "id": "CF", "nombre": "Consumidor Final" }, "items": [ { "tipo": "S", "cantidad": 1, "unidad_medida": "UND", "descripcion": "Servicio de consultoría", "precio_unitario": 100, "impuestos": [ { "nombre": "IVA", "codigo_unidad_gravable": 1, "monto_impuesto": 12 } ] } ] }'{
"id": "inv_V1StGXR8_Z5jdHi6",
"status": "PROCESSING",
"sandbox": false,
"tipo_dte": "FACT",
"gran_total": 112,
"moneda": "GTQ",
"numero_acceso": 543219876,
"created_at": "2019-08-24T14:15:22Z",
"links": {
"self": "/v1/invoices/inv_V1StGXR8_Z5jdHi6"
}
}{
"type": "https://docs.dtevia.com.gt/errors/ssrf-blocked",
"title": "SSRF_BLOCKED",
"status": 400,
"detail": "La URL del webhook apunta a una dirección privada o interna",
"instance": "/v1/sandbox/invoices"
}{
"type": "https://docs.dtevia.com.gt/errors/invalid-api-key",
"title": "INVALID_API_KEY",
"status": 401,
"detail": "API key inválida o revocada",
"instance": "/v1/sandbox/invoices"
}{
"type": "https://docs.dtevia.com.gt/errors/email-not-verified",
"title": "EMAIL_NOT_VERIFIED",
"status": 403,
"detail": "Confirmá el correo de tu cuenta para usar Facturas y Sandbox.",
"instance": "/v1/sandbox/invoices"
}{
"type": "https://docs.dtevia.com.gt/errors/idempotency-conflict",
"title": "IDEMPOTENCY_CONFLICT",
"status": 409,
"detail": "La Idempotency-Key ya se usó con un cuerpo distinto",
"instance": "/v1/sandbox/invoices"
}{
"type": "https://docs.dtevia.com.gt/errors/payload-too-large",
"title": "PAYLOAD_TOO_LARGE",
"status": 413,
"detail": "El cuerpo del request excede el límite de 1024KB",
"instance": "/v1/invoices",
"context": {
"max_bytes": 1048576
}
}{
"type": "https://docs.dtevia.com.gt/errors/validation-error",
"title": "VALIDATION_ERROR",
"status": 422,
"detail": "Error de validación",
"instance": "/v1/sandbox/invoices",
"invalid_params": [
{
"field": "items.0.impuestos.0.monto_impuesto",
"message": "MontoImpuesto IVA inválido. Esperado ~12 (MontoGravable 100 × 0.12), recibido 10"
}
]
}{
"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.",
"instance": "/v1/sandbox/invoices",
"context": {
"limit": 30,
"used": 30,
"tipo_dte": "FACT"
}
}{
"type": "https://docs.dtevia.com.gt/errors/internal-error",
"title": "INTERNAL_ERROR",
"status": 500,
"detail": "Error interno del servidor",
"instance": "/v1/invoices"
}{
"type": "https://docs.dtevia.com.gt/errors/not-implemented",
"title": "NOT_IMPLEMENTED",
"status": 501,
"detail": "Tipo DTE 'RDON' no implementado aún. Disponibles: FACT, FPEQ, FCAM, FCAP, FESP, NCRE, NDEB, RECI.",
"instance": "/v1/sandbox/invoices"
}PDF de la factura
Devuelve el PDF de la factura. Un solo endpoint para los dos casos — quien integra no necesita saber ni importarle si la factura es de prueba o real, QAPI decide del lado del servidor:
Uso del sandbox hoy
Devuelve el consumo de pruebas del día (hora de Guatemala, UTC-6) desglosado por tipo de DTE, junto con el límite diario del plan.