Docs
EN

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.
    • cuenta_beneficiaria
    • monto
    • fecha
    • emisor
    • receptor — Opcional si cuenta_beneficiaria es Clabe/Tarjeta.

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 un header Retry-After.
  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 6 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).
  • invalid — Banxico respondió de una forma inesperada la solicitud (datos malformados).
  • failed — Excepción(error) de aplicación.
  • error — Excepción(error) de transporte (típicamente 5xx).

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 se establece a nivel de cuenta con PUT /v1/validations/{id}/retry-policy y 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 responde 200 con la respuesta de caché.
  • 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.