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=1La 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 no pudo responder en el intento |
invalid | Sí | Los datos enviados no forman una transferencia consultable |
failed | Sí | El procesamiento se agotó sin resultado |
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 arranca en 2 segundos y se amplía a 5 a partir del décimo intento. 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 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.