El ambiente sandbox de JAAK te permite desarrollar y probar tu integración sin afectar datos reales ni incurrir en costos. Es un ambiente completamente separado de producción.

URLs de los ambientes

Verificación de Identidad (KYC) y consultas oficiales

Ambiente	URL base
Sandbox	`https://api.sandbox.jaak.ai`
Producción	`https://services.api.jaak.ai`

Frontend KYC (white-label)

Ambiente	URL
Sandbox	`https://kyc.sandbox.jaak.ai`
Producción	`https://identity.jaak.ai`

Firma Digital (Signa)

Ambiente	URL base
Sandbox	`https://signa.sandbox.jaak.ai`
Producción	`https://signa.jaak.ai`

Plataforma JAAK (dashboard)

Ambiente	URL
Sandbox	`https://platform.sandbox.jaak.ai`
Producción	`https://platform.jaak.ai`

Credenciales

Las credenciales de sandbox y producción son independientes: una API Key generada en sandbox no funciona en producción, y viceversa.

Inicia sesión en la Plataforma JAAK del ambiente que vayas a usar.
Ve a Ajustes → API keys.
Pulsa Generar nueva API key, ponle un nombre descriptivo y elige una vigencia.
Copia y guarda la API Key inmediatamente — no podrás recuperarla después.

La API Key se envía como header Authorization: Bearer <api-key-jwt> en las llamadas iniciales del flujo (creación de sesión KYC, consultas oficiales, etc.).

No mezcles ambientes

Si usas una API Key de producción contra api.sandbox.jaak.ai (o al revés), recibirás 401 Unauthorized. Asegúrate de que la URL base y la API Key correspondan al mismo ambiente.

Probar el flujo KYC en sandbox

El flujo completo (crear sesión → short key → captura → finalización) funciona igual que en producción. Consulta los pasos detallados en JAAK KYC vía API, reemplazando la URL base por https://api.sandbox.jaak.ai.

curl -X POST https://api.sandbox.jaak.ai/api/v1/kyc/flow \
  -H "Authorization: Bearer $JAAK_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Pérez",
    "flow": "Sandbox-Test",
    "redirectUrl": "",
    "countryDocument": "MEX",
    "flowType": "KYC",
    "verificationType": "",
    "verification": { "EMAIL": "", "SMS": "", "WHATSAPP": "" }
  }'

La respuesta incluye un sessionUrl que puedes abrir en el navegador para completar el flujo manualmente, o continuar consumiendo los endpoints API (paso 2 en adelante).

Reproducir escenarios concretos (approved/rejected/pending/errores)

En sandbox puedes forzar cualquier escenario del flujo enviando un requestId con un prefijo convencional. Esto es útil para construir tests automatizados que cubran no solo el happy path sino también rechazos y errores.

Consulta el Catálogo de Sandbox Request IDs para la lista completa de prefijos disponibles.

Webhooks en sandbox

El sandbox envía webhooks reales a la URL que configures en la Plataforma JAAK → Compañía → Webhooks. Para desarrollo local puedes usar:

webhook.site — inspecciona webhooks en tiempo real sin código.
ngrok — expone tu localhost a internet con HTTPS.

Detalles del payload, headers de autenticación y comportamiento ante fallos: Webhooks.

Diferencias con producción

Característica	Sandbox	Producción
Datos	De prueba	Reales
Costos	Sin costo	Según tu plan
Validación contra padrón INE / RENAPO / SAT	Real (consulta servicios oficiales)	Real
Liveness y verificación de documento	Modelos completos	Modelos completos
Catálogo de request IDs	Disponible (forzar escenarios)	No aplica
SLA	Best effort	Garantizado
Soporte	Email	Prioritario

El sandbox usa los mismos modelos de IA

A diferencia de otros sandboxes "simulados", el de JAAK ejecuta los mismos modelos de visión y los mismos servicios oficiales que producción. Los rechazos por liveness o por documento alterado se calculan de la misma forma. Lo único distinto es que los datos no se persisten para auditoría comercial y el catálogo de request IDs te permite forzar respuestas concretas.

Migrar a producción

Cuando estés listo para ir a producción:

Genera credenciales de producción desde Plataforma JAAK producción → Ajustes → API keys. Las credenciales son independientes.
Cambia las URLs base en tu integración:
- api.sandbox.jaak.ai → services.api.jaak.ai
- kyc.sandbox.jaak.ai → identity.jaak.ai
- signa.sandbox.jaak.ai → signa.jaak.ai
- platform.sandbox.jaak.ai → platform.jaak.ai
Actualiza la URL del webhook en la plataforma de producción (debe ser HTTPS y públicamente accesible).
Prueba el flujo end-to-end con tu propio documento real antes del lanzamiento.

Usa variables de entorno

Mantén JAAK_API_BASE_URL y JAAK_API_KEY en variables de entorno y cambia el valor por ambiente, en lugar de hardcodear las URLs. Te ahorra errores al promocionar a producción.

Buenas prácticas

Ambientes separados en tu propio sistema (development/staging/production) apuntando a sandbox/sandbox/producción de JAAK respectivamente.
Tests automatizados en CI usando los prefijos del catálogo de request IDs para cubrir caminos no felices.
No reuses datos personales reales en sandbox, ni siquiera para pruebas internas — los datos son de prueba por definición.

Solución de problemas

"401 Unauthorized" en sandbox

Verifica que la API Key corresponde al ambiente (sandbox vs producción).
Confirma que el header es Authorization: Bearer <api-key> (no X-API-Key).
Asegúrate de que la API Key no haya expirado en la plataforma.

Los webhooks no llegan

La URL configurada debe ser HTTPS y accesible públicamente (no localhost).
Tu servidor debe responder con 2xx en menos de 10 segundos.
Revisa el historial de envíos en la Plataforma JAAK → Compañía → Webhooks.

Quiero forzar un rechazo por liveness para mi test

Usa el prefijo correspondiente del Catálogo de Sandbox Request IDs.