Flujo de validación

Flujos de validación — ¿Qué son?

En Veriko, definimos "flujo de validación" al proceso que toma los datos de una transferencia SPEI (en texto o imagen) y busca si Banxico emitió un CEP o un registro de transacción con esos datos.
Una validación siempre finaliza con un "Estado terminal" (ver más abajo).

Validación manual vs desde imagen (OCR)

• Manual (POST /v1/validate): Debes enviar los siguientes datos en texto plano:
  • clave_rastreo — Opcional si se envía referencia_numerica.
  • cuenta_beneficiaria
  • monto
  • fecha
  • emisor
  • receptor — Opcional si cuenta_beneficiaria es Clabe/Tarjeta.
  • receptor_participante — Opcional. 0 para cuentahabiente (por defecto) o 1 cuando el beneficiario es la propia institución receptora («Pago a Banco»).

Guía completa en: Validar una transferencia SPEI (manual)

• Desde imagen (OCR) (POST /v1/validate-ocr): Debes enviar una imagen (Base64) o una URL (https):
  • image — Opcional si se envía image_url.
  • image_url — Opcional si se envía image.
  • cuenta_beneficiaria, banco_emisor, banco_receptor — Opcionales. Solo si no vienen en la imagen.

Guía completa en: Validar una transferencia SPEI desde una imagen (OCR)

Sync vs async

Por default ambos endpoints son síncronos: Es decir, el sistema responde la petición hasta que Banxico responde (la mediana es 3-5s; el timeout recomendado es de 30s).
Si necesitas cerrar la conexión antes o configurar un timeout menor, simplemente agrega a la URL ?async=1 como parámetro GET. Entonces:

1. El endpoint al instante devuelve 202 con un validation_id, además de un ETag y meta.next_poll_after_seconds.
2. El sistema encola y comienza a procesar la validación.
3. Puedes sondear GET /v1/validations/{id} cada cierto tiempo para recuperar el estado de la validación (enviando preferentemente If-None-Match con el último ETag visto). Mientras la fila no transicione, el servidor responde 304 Not Modified; cuando cambia de status el ETag cambia y el cuerpo del sondeo trae el resultado final.

Detalle completo en: Validaciones async.

Estados terminales

Cada fila puede resolverse en uno de estos 7 valores:

• valid — CEP encontrado. Es el único veredicto que obtiene el CEP cuenta como "verificado" para tus finanzas (ver CEP y Finanzas).
• not_found — No hay CEP ni transacción encontrados con esos datos.
• cep_unavailable — Se encontró la transacción no el CEP (típicamente todavía no se liquidó o hay tardanzas en el sistema bancario).
• returned — El pago se liquidó y la institución beneficiaria lo devolvió después. El CEP, si existe, se sigue entregando.
• invalid — Banxico respondió de una forma que el servicio no reconoce; no es un problema de los datos enviados.
• failed — La validación se detuvo por un rechazo de los datos enviados; el motivo viaja en error_code.
• error — Fallo del servicio o de Banxico durante el procesamiento; el motivo viaja en error_code.

Revisión posterior de un valid

Un valid es el veredicto del momento de la consulta. Banxico puede reportar la devolución del pago horas o días después; entonces la validación pasa de valid a returned, conserva su CEP y emite el webhook validation.returned. Hay dos formas de detectarlo:

• Bajo demanda: POST /v1/validations/{id}/recheck consulta sólo el estado del pago. No consume cuota, admite una consulta cada 10 minutos por validación y sólo responde durante las primeras 72 horas.
• Automática: el servicio vuelve a revisar las validaciones valid de las últimas 72 horas, a la hora, a las 6 horas, al día y a los 3 días de edad.

Detalle completo en: CEP.

Conservar o borrar el comprobante

El archivo del comprobante se conserva de forma predeterminada. retain_image=false en POST /v1/validate-ocr lo borra cuando la validación llega a un estado terminal y deja el veredicto y los datos extraídos. Para borrar de forma definitiva una validación y todo lo que dejó, POST /v1/validations/{id}/purge/prepare y POST /v1/validations/{id}/purge/execute la dejan como una lápida: sin archivo, sin CEP y sin los datos extraídos, con su veredicto, sus fechas y su monto.

Detalle completo en: Retención de comprobantes y datos.

Reintentos

Una fila terminal puede entrar a un ciclo de reintentos cuando su outcome (estado terminal) es uno de estos:

• not_found
• cep_unavailable
• error

La política por omisión de la cuenta se establece con PUT /v1/users/me/retry-policy, y una validación concreta se ajusta con PUT /v1/validations/{id}/retry-policy. Define enabled, max_retries, interval_seconds y los outcomes específicos de la lista.

Detalle completo en: Política de reintentos.

Idempotency-Key

El header Idempotency-Key es opcional. Se maneja de esta forma:

• Nueva key → Se procesa la petición normalmente, se persiste la respuesta para replays.
• Mismo body con key repetida → Endpoint repite la respuesta guardada, con su mismo código de estado y la cabecera Idempotent-Replayed: true.
• Body distinto con key repetida → Endpoint responde 422 idempotency_key_reused.
• Misma key todavía procesando → Endpoint responde 409 idempotency_key_in_progress.

Detalle completo en: Idempotencia.