`Validation`

Recurso JSON:API de una validación SPEI devuelto por la consulta individual y la validación síncrona.

ExtiendeJsonApiResourceBase

Propiedades

Campo	Tipo	Descripción
`type`*	`string`	Tipo de recurso JSON:API. Siempre `validation`.
`id`*	`string (uuid)`	Identificador único de la validación (UUID v4).
`attributes`*	`object`	Datos canónicos de la validación.
`validation_type`	`string`	Modalidad de validación — `direct`: Captura manual de los campos; `ocr`: Lectura de la imagen del comprobante.
`is_playground`	`boolean`	`true` cuando el resultado proviene de una simulación del banco de pruebas (Playground). La simulación se ejecuta sin llamadas a Banxico, sin consumo de cuota, sin persistencia y sin emisión de webhooks o notificaciones.
`status`	`string`	Estado del ciclo de vida — `queued`: Pendiente de procesamiento; `processing`: En proceso; `valid`: El CEP fue encontrado y cuadra; `not_found`: Banxico no encuentra la operación; `cep_unavailable`: Banxico reconoce la transacción pero el CEP no está disponible; `invalid`: Banxico no devolvió un veredicto reconocible; `returned`: la operación se liquidó y después se devolvió; `failed`: La validación se detuvo por un problema en los datos enviados; `error`: La validación se detuvo por un fallo del servicio.
`banxico_status`	`string \| null`	Veredicto reportado por Banxico. Puede ser: `valid`, `not_found`, `cep_unavailable`, `invalid`, `returned` o `error`. Permanece `pending` mientras no exista un veredicto de Banxico. `returned` significa que la operación se liquidó y la institución beneficiaria la devolvió después — el CEP, si existe, se sigue entregando. Un `valid` no es definitivo: es el veredicto del momento de la consulta, y pasa a `returned` cuando Banxico reporta la devolución en una revisión posterior, que se pide con `POST /v1/validations/{id}/recheck` o que el servicio hace solo durante las primeras 72 horas (se emite el webhook `validation.returned`). Solo toma `error` cuando la petición llegó a Banxico y el servicio falló; `error_code` identifica la causa.
`processing_time_ms`	`integer \| null`	Tiempo (en milisegundos) empleados en procesar la validación.
`request_data`	`object`	Copia de los campos de la petición original. `fecha` conserva la fecha de envío tal como se envió, aunque Banxico haya encontrado el pago con otra (`banxico_result._fecha`).
`client_ref`	`string`	Referencia propia que se envió en la petición (`client_ref`), devuelta tal cual. Solo aparece cuando la petición la incluyó. Sirve para relacionar la validación con un pedido propio, y `GET /v1/validations` la acepta como filtro exacto. No debe contener datos personales.
`created_at`	`string (date-time)`	Fecha y hora, en ISO 8601 UTC, de creación de la validación.
`completed_at`	`string \| null`	Fecha y hora de la finalización, en ISO 8601 UTC. `null` mientras no haya terminado.
`enqueued_at`	`string \| null`	Fecha y hora, en ISO 8601 UTC, de entrada a la cola.
`processing_started_at`	`string \| null`	Fecha y hora, en ISO 8601 UTC, de inicio del procesamiento.
`expires_at`	`string \| null`	Fecha y hora, en ISO 8601 UTC, de expiración para validaciones en cola. Tras esta marca, la validación pasa a `error` con `error_code` `ttl_expired`.
`etag_version`	`integer \| null`	Versión incremental (usada con `If-None-Match` en consultas condicionales).
`image_path`	`string \| null`	Referencia relativa del comprobante, imagen o PDF (solo si `validation_type` es del tipo `ocr`). No se publica cuando el archivo no se conserva: ver `image_retained`.
`image_retained`	`boolean`	`true` cuando la plataforma conserva el archivo del comprobante; `false` cuando no, porque la petición envió `retain_image=false` o porque la validación se purgó. Solo aparece en las validaciones de tipo `ocr`. Con `false`, `GET /v1/validations/{id}/image` responde un estado HTTP `410` (con `image_not_retained` o `validation_purged` en el cuerpo).
`purged_at`	`string (date-time)`	Fecha y hora, en ISO 8601 UTC, en que la validación se purgó con `POST /v1/validations/{id}/purge/execute`. Solo aparece en una validación purgada, que queda como una lápida. Una lápida conserva `id`, `validation_type`, `status`, `banxico_status`, las fechas, `processing_time_ms`, `error_code` y el monto en `normalized_data.monto`. No conserva el archivo, el CEP, `request_data`, `ocr_result` ni `banxico_result`, y sus recursos derivados responden un estado HTTP `410` (con `validation_purged` en el cuerpo).
`ocr_result`	`object \| null`	Campos extraídos del comprobante (solo si `validation_type` es del tipo `ocr`). `extraction_source` vale `cep_pdf` cuando el comprobante era el CEP de Banxico en PDF y sus datos se leyeron de su texto, sin OCR. `comprobantes_detectados` es el número de comprobantes que se encontraron en un PDF.
`ocr_confidence`	`number \| null`	Puntaje de la extracción OCR 0–1 (solo si `validation_type` es del tipo `ocr`).
`normalized_data`	`object \| null`	Campos normalizados después de la extracción OCR (si `validation_type` es del tipo `ocr`), o la cuenta ganadora en `cuenta_beneficiaria` cuando una validación directa envió `cuentas_candidatas`. Una lápida conserva aquí solo el monto.
`normalization_warnings`	`array \| null`	Advertencias de normalización presentes. Permiten explicar un resultado `not_found` inesperado.
`duplicate_of`	`object`	Validación previa que ya había confirmado esta misma transferencia en la misma cuenta. Solo aparece cuando existe una validación `valid`, no retirada, con la misma clave de rastreo; nunca apunta a una validación de otra cuenta. Es la forma estructurada del aviso que también se añade a `normalization_warnings`. No cambia el veredicto: la validación se consulta y se cobra igual.
`id`*	`string (uuid)`	Identificador de la validación previa.
`created_at`*	`string (date-time)`	Fecha y hora, en ISO 8601 UTC, de creación de la validación previa.
`account_conflict`	`object`	Conflicto entre la cuenta enviada y la que muestra la imagen. Solo aparece en validaciones de tipo `ocr`, cuando se envió `cuenta_beneficiaria` y la imagen muestra otra cuenta completa de la misma longitud, válida y con confianza suficiente, o una cuenta enmascarada cuyos dígitos finales visibles (3 o más) no son el final de la cuenta enviada. Prevalece la cuenta enviada, que es la que se consulta en Banxico: el campo no cambia el veredicto. Si el pago fue a la cuenta de la imagen, lo esperable es un `not_found`. Solo trae los últimos 4 dígitos de cada cuenta, y el conflicto también se añade a `normalization_warnings`. Con una cuenta enmascarada, `read_last4` trae los dígitos finales que el propio comprobante muestra (3 o 4), nunca más.
`sent_last4`*	`string`	Últimos 4 dígitos de la cuenta enviada en `cuenta_beneficiaria`.
`read_last4`*	`string`	Últimos 4 dígitos de la cuenta que muestra la imagen (los visibles, 3 o 4, si está enmascarada).
`candidate_match`	`object`	Cuál de las `cuentas_candidatas` enviadas ganó. Solo aparece cuando la petición llevó esa lista y una de las cuentas coincidió con la transferencia. La cuenta completa va en `normalized_data.cuenta_beneficiaria`; este objeto indica qué posición de la lista es, para correlacionarla con la entidad propia del integrador sin comparar cuentas. No cambia el veredicto.
`index`*	`integer`	Posición (desde 0) de la cuenta ganadora en el arreglo `cuentas_candidatas`, tal como se envió.
`account_last4`*	`string`	Últimos 4 dígitos de la cuenta ganadora.
`is_masked`	`boolean \| null`	Indica si la cuenta beneficiaria viene enmascarada en el comprobante cargado, sea una CLABE, una tarjeta o un celular. Solo se incluye cuando vale `true` y solo si `validation_type` es del tipo `ocr`.
`banxico_result`	`object \| null`	Datos devueltos por Banxico. Las propiedades tipadas abajo son las 20 que declara el esquema oficial del complemento SPEI. `_ocr_correction` conserva los campos corregidos, su lectura original (`requested`), el valor consultado (`used`) y la confirmación (`confirmed_by`). `status_query` indica una hipótesis confirmada por la consulta de estado; `cep` indica que también se obtuvo el comprobante. La consulta de estado por sí sola no verifica una transferencia. `_cep_upload` aparece cuando el comprobante subido era el CEP en PDF y Banxico confirmó el pago. `authenticated` es `true` cuando su sello y su cadena original coinciden con los del CEP oficial; con `false`, `differing_fields` lista los campos que difieren y `normalization_warnings` lo avisa. El veredicto sigue siendo el de Banxico. `_payment_status` es el estado oficial del pago, tal como lo dio Banxico la última vez que se le preguntó: `code` (`liquidado`, `en_proceso`, `cancelado`, `rechazado`, `en_proceso_devolucion`, `devuelto` o `desconocido`), `label`, `settled`, `reversed` y `checked_at` (ISO 8601 UTC). Su ausencia significa que no se pudo saber, nunca que el pago esté liquidado. Se actualiza en cada revisión posterior, y con `devuelto` o `en_proceso_devolucion` la validación pasa a `returned`. `_fecha` aparece cuando Banxico no encontró el pago con la fecha enviada y sí con otra. `used` es la fecha con la que se encontró, `requested` es la fecha con la que se consultó primero y `reason` es el motivo por el que se probó `used`. Valores de `reason`: `clave_embedded_date`: La clave de rastreo incrusta otra fecha, a un día hábil SPEI o menos de la enviada; `cutoff_18h`: La clave no incrusta fecha y el comprobante indica una hora cercana al corte de las 18:00, así que se probó el día siguiente; `dia_operacion`: La clave incrusta la fecha enviada, porque el comprobante trae la de operación, y se probó un día anterior hasta el día hábil previo. El veredicto sigue siendo el de Banxico, y `request_data.fecha` conserva la fecha enviada.
`operationDate`	`string`	Día hábil SPEI que Banxico asignó a la operación, tal como lo reporta el CEP (`YYYY-MM-DD`), en hora del centro de México. Puede diferir de la fecha de envío: lo enviado a partir de las 18:00, en sábado, en domingo o en un día inhábil opera el siguiente día hábil.
`processingTime`	`string`	Hora de la operación tal como la reporta el CEP (`HH:MM:SS`), en hora del centro de México y no en UTC.
`speiKey`	`string`	Clave de la operación dentro del sistema SPEI (`ClaveSPEI` del CEP). Distinta de la clave de rastreo.
`trackingKey`	`string`	Clave de rastreo de la operación SPEI — la misma que se envía en la petición de validación.
`digitalSignature`	`string`	Sello digital del CEP (`sello`) — la firma que Banxico calcula sobre la operación.
`certificateNumber`	`string`	Número del certificado digital que Banxico usó para sellar el CEP.
`cadenaCda`	`string`	Cadena original de la operación (`cadenaCDA`): los 47 campos que la institución envió a Banxico, separados por `\|`, incluidas ambas fechas (operación y captura) y el tipo de pago. Permite auditar el CEP sin volver a pedirlo.
`senderBank`	`string`	Banco emisor de la operación, tal como lo identifica el CEP.
`senderName`	`string`	Nombre del ordenante de la operación, tal como lo reporta el CEP.
`senderAccountType`	`string`	Tipo de cuenta del ordenante (por ejemplo, CLABE o tarjeta), tal como lo reporta el CEP.
`senderAccount`	`string`	Cuenta del ordenante, tal como la reporta el CEP, sin enmascarar en este recurso (consulta privada, propia del dueño de la validación).
`senderRfc`	`string`	RFC del ordenante, tal como lo reporta el CEP.
`receiverBank`	`string`	Banco receptor de la operación, tal como lo identifica el CEP.
`beneficiaryName`	`string`	Nombre del beneficiario de la operación, tal como lo reporta el CEP.
`beneficiaryAccountType`	`string`	Tipo de cuenta del beneficiario (por ejemplo, CLABE o tarjeta), tal como lo reporta el CEP.
`beneficiaryAccount`	`string`	Cuenta del beneficiario, tal como la reporta el CEP, sin enmascarar en este recurso (consulta privada, propia del dueño de la validación). Los webhooks salientes sí la enmascaran a los últimos 4 dígitos en `banxico_confirmed.beneficiaryAccount` (ver la guía de webhooks).
`beneficiaryRfc`	`string`	RFC del beneficiario, tal como lo reporta el CEP.
`amount`	`number (float)`	Monto de la operación que Banxico confirmó por el CEP, en pesos.
`iva`	`number (float)`	IVA de la operación reportado por el CEP, en pesos.
`paymentConcept`	`string`	Concepto de pago de la operación, tal como lo reporta el CEP.
`error_message`	`string \| null`	Mensaje legible del error terminal (si aplica).
`error_code`	`ValidationErrorCode \| null`	Código estable del error terminal (si aplica). Tras `not_found`, el diagnóstico puede indicar `not_found_identity` (fecha, criterio o bancos), `not_found_account` (cuenta), `not_found_amount` (importe), `not_found_account_and_amount` (ambos) o `not_found_account_or_amount` (operación encontrada, sin aislar el campo). Un diagnóstico no cambia el veredicto ni acredita el pago. Sin respuesta concluyente, el campo queda en `null`.
`batch_id`	`integer \| null`	Identificador del trabajo de importación masiva (si aplica).
`batch_position`	`integer \| null`	Posición dentro del trabajo (comenzando en 1).
`retry_state`	`object`	Estado completo del ciclo de reintentos (siempre presente). Si la validación no tiene reintentos activos, `enabled` es `false` y los campos de política son `null`. Las validaciones de importación masiva siempre tienen `enabled` igual a `false`.
`enabled`	`boolean`	`true` cuando la validación tiene reintentos configurados, aunque su ciclo ya haya terminado (`terminal_state`).
`max_retries`	`integer \| null`	Número máximo de reintentos configurado; `null` cuando `enabled` es `false`.
`interval_seconds`	`integer \| null`	Intervalo en segundos entre reintentos, de `300` a `86400`; `null` cuando `enabled` es `false`.
`outcomes`	`array \| null`	Resultados que originan un reintento: `not_found`, `cep_unavailable` y `error`; `null` cuando `enabled` es `false`.
`attempts_completed`	`integer`	Cantidad de reintentos completados hasta el momento.
`next_attempt_at`	`TimestampUTC \| null`	Fecha del próximo reintento; `null` cuando no hay uno programado.
`resolved_at`	`TimestampUTC \| null`	Fecha en que un reintento obtuvo `valid`; `null` mientras no ocurra.
`exhausted_at`	`TimestampUTC \| null`	Fecha en que se agotaron los intentos; `null` mientras no ocurra.
`cancelled_at`	`TimestampUTC \| null`	Fecha de cancelación del ciclo; `null` mientras no ocurra.
`terminal_state`	`string \| null`	Situación del ciclo: `pending`, `resolved`, `exhausted` o `cancelled`. Es `null` cuando la validación no tiene un ciclo de reintentos.
`links`	`object`	Enlaces relacionados (JSON:API `links`).
`self`	`string`	Enlace canónico al detalle de la validación.
`cep_xml`	`string \| null`	URL del CEP en formato XML. Solo aparece cuando `banxico_status` es `valid`, o es `returned` con comprobante, y la validación no se purgó; si no, se omite el objeto `links`.
`cep_pdf`	`string \| null`	URL del CEP en formato PDF. Solo aparece cuando `banxico_status` es `valid`, o es `returned` con comprobante, y la validación no se purgó; si no, se omite el objeto `links`.

Usado en operaciones

POST /v1/validate
POST /v1/validate-ocr
GET /v1/validations/{id}
POST /v1/validations/{id}/recheck