La API no expone un host separado para sandbox. Las pruebas y la integración real corren contra los mismos endpoints, en el mismo dominio (api.example.com). Para que una validación de prueba no impacte tu cuota, tu facturación ni tus webhooks, usas el flag playground en el body de la request.

Cómo funciona playground

Tanto POST /v1/validate como POST /v1/validate-ocr aceptan el campo opcional playground en el body:

curl -X POST 'https://api.veriko.mx/v1/validate' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2025-03-15",
    "monto": 15000.50,
    "clave_rastreo": "MXBA20250315001234",
    "cuenta_beneficiaria": "012180004412345678",
    "playground": true
  }'

Cuando playground=true:

• La request se procesa con la misma validación de inputs y el mismo pipeline contra Banxico que una validación normal — los resultados (valid, not_found, cep_unavailable, error) son reales.
• La fila queda marcada con is_playground=1 en la base. Aparece en tu listado con el badge correspondiente y queda fuera de los conteos de uso (/v1/usage) y de las facturas.
• Los eventos de webhook (validation.completed, validation.failed, validation.error) no se disparan.
• Las notificaciones de canal (email/SMS/push) no se envían.
• La respuesta lleva meta.playground: true para que tu cliente pueda distinguirla.

Esto te deja correr smoke tests, integración continua y demos sin contaminar tus métricas de producción ni saturar a tus receptores de webhooks.

Datos de prueba reproducibles

No hay valores hardcodeados que devuelvan respuestas sintéticas — Banxico contesta lo que ve. Para escenarios deterministas:

• valid: usa una transferencia SPEI real propia (la puedes encontrar en tu app bancaria o estado de cuenta). Cualquier referencia con CEP emitido funciona.
• not_found: cambia un dígito del monto o de la clave_rastreo de una transferencia real. Banxico devuelve "no encontrado" determinísticamente.
• cep_unavailable: este estado depende de la disponibilidad de Banxico — no se puede forzar desde el cliente.
• error: envía una clave_rastreo con caracteres no alfanuméricos o un cuenta_beneficiaria con checksum inválido para gatillar errores de validación 422 del lado nuestro.

Para CLABE/tarjeta válidas en formato pero sin transferencia real asociada, espera not_found — el banco se infiere del prefijo y el pipeline llega hasta Banxico.

Idempotencia y reintentos

Las requests con playground=true participan del mismo flujo de idempotencia y reintentos automáticos que las normales. Pero como no consumen cuota, son baratas de reproducir — útil cuando estás escribiendo tests para tu handler de respuestas asíncronas.

Cuándo NO usar playground

Cualquier validación que quieras que cuente como real (para auditoría, reporting, o porque el receptor del webhook necesita enterarse) debe ir sin el flag — o con playground: false explícito. El default es false.

Si vas a integrar webhooks, ten en cuenta que tus endpoints suscritos no recibirán eventos de validaciones playground. Para probar tu pipeline de webhooks usa el botón Probar entrega en el panel de webhooks (envía un evento de prueba firmado con tu secret) en lugar del flag playground.