`Validation`

Registro completo de una validación SPEI en forma de JSON:API. Devuelto por `GET /v1/validations/{id}` y `POST /v1/validate` síncrono.

Propiedades

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`	Estado reportado por Banxico tras la consulta. `null` antes de consultar.
`processing_time_ms`	`integer \| null`	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`	Marca temporal UTC de resolución terminal. `null` mientras `status` esté en `queued`/`processing`.
`enqueued_at`	`string \| null`	Marca temporal del encolado en el bus de mensajería.
`processing_started_at`	`string \| null`	Marca temporal del primer XCLAIM del worker.
`expires_at`	`string \| null`	Marca temporal de expiración para validaciones encoladas. Tras esta marca, el job pasa a `failed`.
`etag_version`	`integer \| null`	Versión incremental para `If-None-Match` en consultas polling.
`image_path`	`string \| null`	Ruta relativa de la imagen del comprobante. Solo OCR.
`ocr_result`	`object \| null`	Resultado bruto del OCR. Solo OCR.
`ocr_confidence`	`number \| null`	Puntaje OCR 0–1. Solo OCR; `null` para `direct`.
`normalized_data`	`object \| null`	Campos normalizados post-OCR para consulta a Banxico.
`normalization_warnings`	`array \| null`	Advertencias de la pipeline de normalización.
`is_masked`	`boolean \| null`	Indica si el PAN viene enmascarado en el comprobante OCR.
`banxico_result`	`object \| null`	Payload literal devuelto por Banxico CEP.
`error_message`	`string \| null`	Mensaje legible del error terminal cuando aplique.
`error_code`	`string \| null`	Código machine-readable del error terminal.
`batch_id`	`integer \| null`	Identificador del lote de import masivo si aplica.
`batch_position`	`integer \| null`	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`	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`	Intervalo entre reintentos en segundos (300–86400). `null` si `enabled=false`.
`outcomes`	`array \| null`	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`	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`	URL del CEP en formato XML. `null` si `status` no es `valid`.
`cep_pdf`	`string \| null`	URL del CEP en formato PDF. `null` si `status` no es `valid`.

Usado en operaciones

POST /v1/validate
POST /v1/validate-ocr
GET /v1/validations/{id}
GET /v1/admin/validations/{id}/raw

Referenciado por esquemas

AdminValidationRawData