Playground y pruebas

La API no ofrece un host de pruebas, ni claves de prueba, ni un modo de simulación en la petición. Las pruebas y el tráfico real de integración llegan a los mismos endpoints, en el mismo dominio (api.veriko.mx) y con la misma clave. Toda llamada admitida a POST /v1/validate o POST /v1/validate-ocr consume cuota en el momento de admitirse, dispara webhooks y aparece en GET /v1/usage/summary.

La simulación existe, pero vive en la consola y no en el cuerpo de la petición: es el playground, y se describe más abajo.

Qué consume cuota y qué no

La cuota se consume al admitir la operación —después de validar el cuerpo y antes del trabajo contra Banxico—, y se devuelve cuando el desenlace no es imputable a quien llama. Se cobra el intento admitido salvo en estos casos:

• Un cuerpo rechazado. Una petición que no pasa la validación y responde 422 no consume cuota.
• Una clave de idempotencia repetida. Repetir un Idempotency-Key con el mismo cuerpo reproduce la respuesta guardada sin volver a entrar al endpoint, así que no se cobra dos veces. Ver idempotencia.
• Un fallo de la plataforma. Una validación que termina en error porque Banxico no contesta o porque falla el proveedor que extrae los datos de la imagen devuelve la cuota consumida.
• Una cuenta que no se pudo resolver. La familia cuenta_unresolvable —el comprobante no trae con qué identificar la cuenta beneficiaria, o lo que trae encaja con varias— devuelve la cuota.
• Un pago que no admite validación. Una transferencia dentro del mismo banco no genera CEP (intra_bank_no_cep), y una imagen que no es un comprobante SPEI no tiene qué consultar (image_not_spei_receipt). Ninguna de las dos llega a Banxico, y la cuota se devuelve.
• Los reintentos automáticos. Pertenecen a la validación que ya consumió la cuota. Ver política de reintentos.

Un not_found se cobra igual que un valid: saber que un pago no existe es un resultado, no un fallo. Una imagen ilegible (image_not_readable_receipt) también se cobra, porque el comprobante lo eligió quien llamó.

Nada de esto es un modo de prueba —la primera llamada que llega a Banxico se cobra—, pero abarata iterar sobre una prueba que falla. El detalle del ciclo y de las cabeceras de consumo está en cuotas y planes.

Dónde corre una llamada sin efectos

En el playground de la consola: la pestaña de ese nombre dentro de la sección API. La llamada no se hace desde el navegador: la consola la envía al servidor, que la ejecuta con las credenciales de la sesión abierta, de modo que la clave nunca aparece en el navegador ni en la respuesta.

Por omisión esas llamadas son reales en todos los sentidos: consumen cuota, producen efectos y aparecen en el historial. Las operaciones que traen escenarios de simulación ofrecen además un modo playground: con él activado, la operación corre su tubería real con el paso contra Banxico sustituido por una respuesta preparada, dentro de una transacción que siempre se revierte —no se mide nada, no se entrega ningún webhook, no se envía ninguna notificación y no sobrevive ninguna fila—. Ver playground.

El playground exige una sesión abierta en la consola, y no es una capa de acceso: una integración llama a la operación directamente con su propia clave.

Para ejercitar un receptor de webhooks sin producir validaciones, POST /v1/webhooks/{id}/test manda una entrega sintética firmada al endpoint suscrito, con el secreto de ese endpoint.

Datos de prueba reproducibles

Sobre la API no hay datos sintéticos que devuelvan una respuesta preparada: Banxico contesta lo que ve. Para escenarios deterministas:

• valid — una transferencia SPEI real de la cuenta. Sirve cualquier referencia con CEP emitido.
• not_found — un dígito cambiado en el monto o en la clave_rastreo de una transferencia real. Banxico contesta no-encontrado de forma determinista.
• cep_unavailable — depende de la disponibilidad de Banxico, y no se puede forzar desde el cliente.
• 422 — una clave_rastreo con caracteres fuera del conjunto permitido, o una cuenta_beneficiaria con dígito verificador malo. La petición se rechaza antes de llegar a Banxico, así que no cuesta nada.

Una CLABE o una tarjeta con formato válido pero sin transferencia detrás contesta not_found: la institución se infiere del prefijo o del BIN, y la tubería llega a Banxico igual.

Los estados terminales son valid, not_found, cep_unavailable, invalid, failed y error. Una petición asíncrona llega a uno de ellos por sondeo o por webhook, como describe validaciones asíncronas.