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

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_url del request, y los eventos llevan data.test: true para 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_interna se prefija con [SANDBOX].
  • Límite diario de pruebas por tipo de DTE según el plan: basic 10, starter 30, business 50.
POST
/v1/sandbox/invoices

Autorización

ApiKeyAuth
AutorizaciónBearer <token>

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

Idempotency-Key?string

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"
}