https://api.veriko.mx/v1/validations/{id}Obtener una verificación
Guía de uso →Devuelve el detalle completo de una verificación, y es también el punto por el que se recoge el veredicto de una validación asíncrona. Mientras la verificación no llega a un estado terminal —queued o processing—, la respuesta trae la cabecera Retry-After y meta.next_poll_after_seconds, que marcan cuándo tiene sentido volver a preguntar. Reenviar el ETag recibido en If-None-Match devuelve 304 si el estado no ha cambiado, con lo que el sondeo no descarga dos veces lo mismo; el mecanismo completo está en la caché condicional.
| Parámetro | Ubicación | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
id* | path | string (uuid) | obligatorio | UUID de la validación |
If-None-Match | header | string | opcional | ETag recibido en peticiones anteriores. Si los datos no han cambiado y el W/"3-processing" |
curl -X GET 'https://api.veriko.mx/v1/validations/{id}' \
-H 'Authorization: Bearer veriko_••••'Ejemplo en Python — próximamente.
Ejemplo en JavaScript — próximamente.
Ejemplo en PHP — próximamente.
| Campo | Tipo | Descripción |
|---|---|---|
type* | string | Tipo de recurso JSON:API. Siempre validation |
id* | string (uuid) | Identificador único de la validación (UUID v4). p. ej.3fa85f64-5717-4562-b3fc-2c963f66afa6 |
attributes* | object | Datos canónicos de la validación. |
validation_type | string |
direct |
is_playground | boolean | Indica si la validación fue ejecutada en modo playground. Las ejecuciones playground sí consultan Banxico pero no consumen cuota, no emiten webhooks ni notificaciones. p. ej.false |
status | string | Estado del ciclo de vida: valid |
banxico_status | string | nullanulable | Estado reportado por Banxico tras la consulta. valid |
processing_time_ms | integer | nullanulable | Milisegundos transcurridos entre encolado y resolución terminal. p. ej.1320 |
request_data | object | Snapshot literal de los campos del request original. |
created_at | string (date-time) | Marca temporal UTC del encolado. p. ej.2025-03-15T14:22:10Z |
completed_at | string | nullanulable | Marca temporal UTC de resolución terminal. 2025-03-15T14:22:11Z |
enqueued_at | string | nullanulable | Marca temporal del encolado en el bus de mensajería. p. ej.2026-04-30T10:15:00Z |
processing_started_at | string | nullanulable | Marca temporal del primer XCLAIM del trabajador. p. ej.2026-04-30T10:15:00Z |
expires_at | string | nullanulable | Marca temporal de expiración para validaciones encoladas. Tras esta marca, la importación pasa a 2026-04-30T10:15:00Z |
etag_version | integer | nullanulable | Versión incremental para 1 |
image_path | string | nullanulable | Ruta relativa de la imagen del comprobante. Solo OCR. p. ej.ocr/2026/04/a1b2c3d4.jpg |
ocr_result | object | nullanulable | Resultado bruto del OCR. Solo OCR. |
ocr_confidence | number | nullanulable | Puntaje OCR 0–1. Solo OCR; 0.94 |
normalized_data | object | nullanulable | Campos normalizados post-OCR para consulta a Banxico. |
normalization_warnings | array | nullanulable | Advertencias de la pipeline de normalización. |
is_masked | boolean | nullanulable | Indica si el PAN viene enmascarado en el comprobante OCR. |
banxico_result | object | nullanulable | Payload literal devuelto por Banxico CEP. |
error_message | string | nullanulable | Mensaje legible del error terminal cuando aplique. p. ej.Banxico no respondió tras tres intentos. |
error_code | ValidationErrorCode | null | Código machine-readable del error terminal. |
batch_id | integer | nullanulable | Identificador del lote de import masivo si aplica. p. ej.318 |
batch_position | integer | nullanulable | Posición dentro del lote (1-indexed). p. ej.12 |
retry_state | object | Estado completo del ciclo de reintentos. Siempre presente; si la validación no tiene reintentos activos, |
enabled | boolean | Indica si el ciclo de reintentos está activo para esta validación. p. ej.true |
max_retries | integer | nullanulable | Número máximo de reintentos configurado. El tope superior depende del plan ( 3 |
interval_seconds | integer | nullanulable | Intervalo entre reintentos en segundos (300–86400). 600 |
outcomes | array | nullanulable | Resultados de validación que habilitan un reintento ( ["not_found","cep_unavailable","error"] |
attempts_completed | integer | Número de reintentos completados hasta el momento. p. ej.1 |
next_attempt_at | TimestampUTC | null | Timestamp del próximo reintento programado. |
resolved_at | TimestampUTC | null | Timestamp cuando un reintento resolvió la validación a |
exhausted_at | TimestampUTC | null | Timestamp cuando se agotaron los reintentos sin resolución. |
cancelled_at | TimestampUTC | null | Timestamp cuando el ciclo fue cancelado explícitamente. |
terminal_state | string | nullanulable | Estado terminal del ciclo: pending |
links | object | Enlaces relacionados (JSON:API |
self | string | URL de la validación. p. ej./v1/validations/3fa85f64-5717-4562-b3fc-2c963f66afa6 |
cep_xml | string | nullanulable | URL del CEP en formato XML. /v1/validations/a1b2c3d4-e5f6-7890-abcd-ef0123456789/cep.xml |
cep_pdf | string | nullanulable | URL del CEP en formato PDF. /v1/validations/a1b2c3d4-e5f6-7890-abcd-ef0123456789/cep.pdf |
| Código | Clase | Descripción | Cuerpo |
|---|---|---|---|
| 200 | 2xx | Detalle de la validación. En estados pre-terminales (queued, processing) incluye los headers Retry-After y meta.next_poll_after_seconds. | Sin cuerpo |
| 304 | 3xx | El etag_version y status no cambiaron desde el If-None-Match enviado. Sin cuerpo. El cliente debe esperar Retry-After segundos antes del próximo poll.
| Sin cuerpo |
| 401 | 4xx | Se requiere autenticación o las credenciales son inválidas | ErrorResponse |
| 403 | 4xx | Permisos insuficientes | ErrorResponse |
| 404 | 4xx | Validación no encontrada o no pertenece al usuario autenticado (not_found). | ErrorResponse |
| 422 | 4xx | UUID inválido en el path (invalid_uuid). | ErrorResponse |
| Cabecera | Tipo | Descripción |
|---|---|---|
ETag | string | Weak ETag que sube en cada transición de estado. Formato: W/"{etag_version}-{status}". Envíalo en If-None-Match para recibir 304 si nada cambió. |
Retry-After | integer | Segundos a esperar antes del próximo poll. Solo presente en queued y processing. |
| Código | Clave | Ejemplo |
|---|---|---|
| 401 | unauthorized | Credenciales de autenticación ausentes o inválidas. Envelope
|
| 403 | forbidden | No tienes permiso para acceder a este recurso. Envelope
|