Obtener una verificación

GET https://api.veriko.mx/v1/validations/{id}

Audiencia: public
Autenticación: API key
Permiso: validations:read

Devuelve el detalle completo de una verificación. Para validaciones async en estados pre-terminales (queued, processing), incluye Retry-After y meta.next_poll_after_seconds para guiar el polling. Envía el ETag recibido en If-None-Match para obtener 304 cuando el estado no cambió.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`id` *	path	`string (uuid)`	obligatorio	UUID de la validación
`If-None-Match`	header	`string`	opcional	Weak ETag previamente recibido. Si el `etag_version` y `status` del row siguen iguales, el server responde 304 Not Modified sin cuerpo — útil para evitar transferir el body cuando el estado async no cambió desde el último poll.

Petición

cURLPython•JavaScript•PHP•

curl -X GET 'https://api.veriko.mx/v1/validations/{id}' \
  -H 'Authorization: Bearer mxcep_••••'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 2xx** `Validation`
Campo	Tipo	Descripción
`id` *	`string (uuid)`	Identificador único de la validación (UUID v4).
`type` *	`string`	Tipo de recurso JSON:API. Siempre `validation`.
`attributes` *	`object`	Datos canónicos de la validación.
`validation_type`	`string`	`direct` para peticiones con parámetros textuales; `ocr` para peticiones con imagen de comprobante.
`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.
`status`	`string`	Estado del ciclo de vida: `queued` — encolado para worker; `processing` — worker procesando; `valid` — CEP encontrado y datos coinciden; `not_found` — Banxico consultado, transferencia no encontrada; `cep_unavailable` — servicio Banxico no disponible; `invalid` — payload rechazado post-encolado; `failed` — fallo terminal; `error` — error retriable (Banxico HTTP 5xx).
`banxico_status`	`string \| null` anulable	Estado reportado por Banxico tras la consulta. `null` antes de consultar.
`processing_time_ms`	`integer \| null` anulable	Milisegundos transcurridos entre encolado y resolución terminal.
`request_data`	`object`	Snapshot literal de los campos del request original.
`created_at`	`string (date-time)`	Marca temporal UTC del encolado.
`completed_at`	`string \| null` anulable	Marca temporal UTC de resolución terminal. `null` mientras `status` esté en `queued`/`processing`.
`enqueued_at`	`string \| null` anulable	Marca temporal del encolado en el bus de mensajería.
`processing_started_at`	`string \| null` anulable	Marca temporal del primer XCLAIM del worker.
`expires_at`	`string \| null` anulable	Marca temporal de expiración para validaciones encoladas. Tras esta marca, el job pasa a `failed`.
`etag_version`	`integer \| null` anulable	Versión incremental para `If-None-Match` en consultas polling.
`image_path`	`string \| null` anulable	Ruta relativa de la imagen del comprobante. Solo OCR.
`ocr_result`	`object \| null` anulable	Resultado bruto del OCR. Solo OCR.
`ocr_confidence`	`number \| null` anulable	Puntaje OCR 0–1. Solo OCR; `null` para `direct`.
`normalized_data`	`object \| null` anulable	Campos normalizados post-OCR para consulta a Banxico.
`normalization_warnings`	`array \| null` anulable	Advertencias de la pipeline de normalización.
`is_masked`	`boolean \| null` anulable	Indica si el PAN viene enmascarado en el comprobante OCR.
`banxico_result`	`object \| null` anulable	Payload literal devuelto por Banxico CEP.
`error_message`	`string \| null` anulable	Mensaje legible del error terminal cuando aplique.
`error_code`	`string \| null` anulable	Código machine-readable del error terminal.
`batch_id`	`integer \| null` anulable	Identificador del lote de import masivo si aplica.
`batch_position`	`integer \| null` anulable	Posición dentro del batch (1-indexed).
`retry_state`	`object`	Estado completo del ciclo de reintentos. Siempre presente; si la validación no tiene reintentos activos, `enabled=false` y los campos de política son `null`. Las validaciones de import masivo siempre tienen `enabled=false`.
`enabled`	`boolean`	Indica si el ciclo de reintentos está activo para esta validación.
`max_retries`	`integer \| null` anulable	Número máximo de reintentos configurado. El tope superior depende del plan (`retry_max_retries`) o del default global `max_retries_cap` (típicamente 5–10). `null` si `enabled=false`.
`interval_seconds`	`integer \| null` anulable	Intervalo entre reintentos en segundos (300–86400). `null` si `enabled=false`.
`outcomes`	`array \| null` anulable	Resultados de validación que habilitan un reintento (`not_found`, `cep_unavailable`, `error`). `null` si `enabled=false`.
`attempts_completed`	`integer`	Número de reintentos completados hasta el momento.
`next_attempt_at`	`union`	Timestamp del próximo reintento programado. `null` si el ciclo está en estado terminal o si no hay reintentos activos.
`resolved_at`	`union`	Timestamp cuando un reintento resolvió la validación a `valid`. `null` si el ciclo no ha terminado por resolución.
`exhausted_at`	`union`	Timestamp cuando se agotaron los reintentos sin resolución. `null` si el ciclo no ha terminado por agotamiento.
`cancelled_at`	`union`	Timestamp cuando el ciclo fue cancelado explícitamente. `null` si no fue cancelado.
`terminal_state`	`string \| null` anulable	Estado terminal del ciclo: `pending` — activo, sin resultado final aún; `resolved` — un reintento obtuvo `valid`; `exhausted` — se agotaron los intentos; `cancelled` — cancelado por el usuario.
`links`	`object`	Enlaces relacionados (JSON:API `links`).
`self`	`string`	URL de la validación.
`cep_xml`	`string \| null` anulable	URL del CEP en formato XML. `null` si `status` no es `valid`.
`cep_pdf`	`string \| null` anulable	URL del CEP en formato PDF. `null` si `status` no es `valid`.

**Códigos de respuesta** `GET /v1/validations/{id}`
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`

**Cabeceras de respuesta** `200`
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`.

**Errores de `GET /v1/validations/{id}`**
Código	Clave	Detalle
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`