Validaciones asíncronas

Una validación consulta el CEP en Banxico, y ese tiempo de espera pertenece a un servicio externo. El parámetro ?async=1 desacopla ambas cosas: la petición encola el trabajo y responde de inmediato, en lugar de sostener la conexión hasta que Banxico conteste.

POST /v1/validate?async=1
POST /v1/validate-ocr?async=1

La respuesta es 202 con el identificador de la validación, sin veredicto todavía:

{
  "data": {
    "type": "validation",
    "id": "9f3c2a1b-4d5e-6f70-8192-a3b4c5d6e7f8",
    "attributes": { "status": "queued", "expires_at": "2026-08-21T15:12:44Z" }
  }
}

El veredicto se obtiene consultando GET /v1/validations/{id} hasta que el estado sea terminal.

Estados

estado	terminal	significado
`queued`	No	Encolada, sin procesar todavía
`processing`	No	En curso contra Banxico
`valid`	Sí	El CEP existe y coincide con los datos enviados
`not_found`	Sí	Banxico no tiene un CEP con esos datos
`cep_unavailable`	Sí	Banxico identificó la operación pero no entregó el comprobante
`returned`	Sí	El pago se liquidó y la institución beneficiaria lo devolvió después
`invalid`	Sí	Banxico respondió de una forma que el servicio no reconoce
`failed`	Sí	La validación se detuvo por un rechazo de los datos enviados; el motivo viaja en `error_code`
`error`	Sí	Fallo durante el procesamiento; el motivo viaja en `error_code`

Cadencia del sondeo

La respuesta del sondeo indica cuándo volver a preguntar, de modo que el cliente no tiene que elegir un intervalo:

señal	contenido
`Retry-After`	Segundos sugeridos hasta el siguiente sondeo
`meta.next_poll_after_seconds`	El mismo valor, en el cuerpo, para clientes que no leen cabeceras
`ETag`	Firma del estado actual, con la forma `W/"{versión}-{estado}"`

La sugerencia es de 2 segundos en cada sondeo; el servidor no la amplía. Un estado terminal deja de emitir Retry-After: es la señal de que el sondeo debe detenerse.

Sondeo condicional

El ETag cambia en cada transición de estado. Reenviarlo como If-None-Match permite que un sondeo sin novedad se resuelva con un 304 sin cuerpo:

GET /v1/validations/9f3c2a1b-…
If-None-Match: W/"3-processing"

Un 304 significa que el estado no ha cambiado desde la consulta anterior. Es la forma económica de sondear: la respuesta no transporta el recurso.

Caducidad

La validación encolada lleva un expires_at. Superado ese plazo sin haber alcanzado un estado terminal, la validación se cierra como caducada (status error, error_code ttl_expired) y deja de procesarse. El valor viene en la respuesta 202 y permite fijar un tope al ciclo de sondeo del cliente.

Elección entre síncrono y asíncrono

Sin ?async=1 la petición devuelve el veredicto en la misma respuesta, a costa de sostener la conexión mientras Banxico contesta. La vía asíncrona es la indicada cuando el volumen es alto, cuando el cliente no puede mantener conexiones largas, o cuando el resultado se procesa después mediante webhooks.