GEThttps://api.veriko.mx/v1/validations/{id}

Obtener una verificación

Audiencia
public
Autenticación
API key
Permiso
validations:read
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ámetros
ParámetroUbicaciónTipoObligatorioDescripción
id*pathstring (uuid)obligatorio

UUID de la validación

If-None-Matchheaderstringopcional

ETag recibido en peticiones anteriores. Si los datos no han cambiado y el etag_version sigue igual, el server responde 304 Not Modified (sin cuerpo) — evita recibir los datos de nuevo cuando el estado del recurso NO ha cambiado.

p. ej. W/"3-processing"
Petición
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.

Respuesta 2xxValidation
CampoTipoDescripción
type*string

Tipo de recurso JSON:API. Siempre validation.

p. ej. 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_typestring

direct para peticiones con parámetros textuales; ocr para peticiones con imagen de comprobante.

p. ej. direct
is_playgroundboolean

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
statusstring

Estado del ciclo de vida: queued — encolado para trabajador; processing — trabajador 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).

p. ej. valid
banxico_statusstring | nullanulable

Estado reportado por Banxico tras la consulta. null antes de consultar.

p. ej. valid
processing_time_msinteger | nullanulable

Milisegundos transcurridos entre encolado y resolución terminal.

p. ej. 1320
request_dataobject

Snapshot literal de los campos del request original.

created_atstring (date-time)

Marca temporal UTC del encolado.

p. ej. 2025-03-15T14:22:10Z
completed_atstring | nullanulable

Marca temporal UTC de resolución terminal. null mientras status esté en queued/processing.

p. ej. 2025-03-15T14:22:11Z
enqueued_atstring | nullanulable

Marca temporal del encolado en el bus de mensajería.

p. ej. 2026-04-30T10:15:00Z
processing_started_atstring | nullanulable

Marca temporal del primer XCLAIM del trabajador.

p. ej. 2026-04-30T10:15:00Z
expires_atstring | nullanulable

Marca temporal de expiración para validaciones encoladas. Tras esta marca, la importación pasa a failed.

p. ej. 2026-04-30T10:15:00Z
etag_versioninteger | nullanulable

Versión incremental para If-None-Match en consultas polling.

p. ej. 1
image_pathstring | nullanulable

Ruta relativa de la imagen del comprobante. Solo OCR.

p. ej. ocr/2026/04/a1b2c3d4.jpg
ocr_resultobject | nullanulable

Resultado bruto del OCR. Solo OCR.

ocr_confidencenumber | nullanulable

Puntaje OCR 0–1. Solo OCR; null para direct.

p. ej. 0.94
normalized_dataobject | nullanulable

Campos normalizados post-OCR para consulta a Banxico.

normalization_warningsarray | nullanulable

Advertencias de la pipeline de normalización.

is_maskedboolean | nullanulable

Indica si el PAN viene enmascarado en el comprobante OCR.

banxico_resultobject | nullanulable

Payload literal devuelto por Banxico CEP.

error_messagestring | nullanulable

Mensaje legible del error terminal cuando aplique.

p. ej. Banxico no respondió tras tres intentos.
error_codeValidationErrorCode | null

Código machine-readable del error terminal.

batch_idinteger | nullanulable

Identificador del lote de import masivo si aplica.

p. ej. 318
batch_positioninteger | nullanulable

Posición dentro del lote (1-indexed).

p. ej. 12
retry_stateobject

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.

enabledboolean

Indica si el ciclo de reintentos está activo para esta validación.

p. ej. true
max_retriesinteger | nullanulable

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.

p. ej. 3
interval_secondsinteger | nullanulable

Intervalo entre reintentos en segundos (300–86400). null si enabled=false.

p. ej. 600
outcomesarray | nullanulable

Resultados de validación que habilitan un reintento (not_found, cep_unavailable, error). null si enabled=false.

p. ej. ["not_found","cep_unavailable","error"]
attempts_completedinteger

Número de reintentos completados hasta el momento.

p. ej. 1
next_attempt_atTimestampUTC | null

Timestamp del próximo reintento programado. null si el ciclo está en estado terminal o si no hay reintentos activos.

resolved_atTimestampUTC | null

Timestamp cuando un reintento resolvió la validación a valid. null si el ciclo no ha terminado por resolución.

exhausted_atTimestampUTC | null

Timestamp cuando se agotaron los reintentos sin resolución. null si el ciclo no ha terminado por agotamiento.

cancelled_atTimestampUTC | null

Timestamp cuando el ciclo fue cancelado explícitamente. null si no fue cancelado.

terminal_statestring | nullanulable

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. null si la validación no tiene ciclo de reintentos.

p. ej. pending
linksobject

Enlaces relacionados (JSON:API links).

selfstring

URL de la validación.

p. ej. /v1/validations/3fa85f64-5717-4562-b3fc-2c963f66afa6
cep_xmlstring | nullanulable

URL del CEP en formato XML. null si status no es valid.

p. ej. /v1/validations/a1b2c3d4-e5f6-7890-abcd-ef0123456789/cep.xml
cep_pdfstring | nullanulable

URL del CEP en formato PDF. null si status no es valid.

p. ej. /v1/validations/a1b2c3d4-e5f6-7890-abcd-ef0123456789/cep.pdf
Códigos de respuestaGET /v1/validations/{id}
CódigoClaseDescripciónCuerpo
2002xxDetalle de la validación. En estados pre-terminales (queued, processing) incluye los headers Retry-After y meta.next_poll_after_seconds.Sin cuerpo
3043xxEl 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
4014xxSe requiere autenticación o las credenciales son inválidasErrorResponse
4034xxPermisos insuficientesErrorResponse
4044xxValidación no encontrada o no pertenece al usuario autenticado (not_found).ErrorResponse
4224xxUUID inválido en el path (invalid_uuid).ErrorResponse
Cabeceras de respuesta200
CabeceraTipoDescripción
ETagstringWeak 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-AfterintegerSegundos a esperar antes del próximo poll. Solo presente en queued y processing.
Errores de GET /v1/validations/{id}
CódigoClaveEjemplo
401unauthorized

Credenciales de autenticación ausentes o inválidas.

Envelope
meta.request_id
c4d5e6f7a8b9
403forbidden

No tienes permiso para acceder a este recurso.

Envelope
meta.request_id
d5e6f7a8b9c0