Conceptos

Sandbox

Un entorno completo, idéntico al de producción, contra el endpoint de homologación SUNAT. Gratis, ilimitado, sin tarjeta.

¿Qué es sandbox?

Cuando emites con una key fwk_test_*:

  • El XML UBL se firma con un certificado demo (no el tuyo).
  • Se envía al endpoint de homologación de SUNAT (e-beta.sunat.gob.pe).
  • Recibes un CDR real (firmado por SUNAT) en sus respuestas.
  • El documento NO tiene valor fiscal — es una práctica.
  • No consume tu cuota mensual. Tampoco afecta tu factura ni dispara webhooks de billing.

Mismo contrato API que producción

Cualquier código que pase contra fwk_test_* debe pasar tal cual contra fwk_live_*. Los códigos de error, shapes de respuesta y headers son idénticos. Solo cambia el destino del XML.

Cómo activarlo

Al registrarte te entregamos la primera key sandbox automáticamente. Para crear más, ve a /app/keys y marca "test mode".

Sandbox vía curl
# Las keys 'fwk_test_*' apuntan a homologación SUNAT.
# Tu cuota Free no se consume.
curl -H "Authorization: Bearer fwk_test_..." \
     https://api.fiscal-web.pe/v1/documents

El header opcional X-Mode: test es redundante si la key ya es fwk_test_* — la inferimos del prefijo.

Diferencias vs producción

  • Certificado: demo (sandbox) vs el tuyo (producción).
  • Endpoint SUNAT: e-beta.sunat.gob.pe vs e-factura.sunat.gob.pe.
  • Tiempo de respuesta CDR: 1-3s (sandbox) vs 3-15s (producción).
  • Rate limit: 60 req/min (sandbox) vs 600 req/min (producción).
  • Datos del receptor: en sandbox cualquier RUC válido sintácticamente funciona; en producción debe existir realmente en SUNAT.

Usarlo en CI/CD

Guarda una fwk_test_* como secret de CI (GitHub Actions, GitLab, etc.) y úsala en tu pipeline. Sin riesgo fiscal y sin tope de uso.

Para integration tests que verifican el flow completo (emisión → webhook → estado accepted), usa sandbox con timeouts holgados — el camino completo toma 2-4s.