Validar una transferencia SPEI (OCR)

Tipo de recurso JSON:API. Siempre validation.

Identificador único de la validación (UUID v4).

Datos canónicos de la validación.

Modalidad de validación — direct: Captura manual de los campos; ocr: Lectura de la imagen del comprobante.

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.

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.

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.

Tiempo (en milisegundos) empleados en procesar la validación.

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).

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.

Fecha y hora, en ISO 8601 UTC, de creación de la validación.

Fecha y hora de la finalización, en ISO 8601 UTC. null mientras no haya terminado.

Fecha y hora, en ISO 8601 UTC, de entrada a la cola.

Fecha y hora, en ISO 8601 UTC, de inicio del procesamiento.

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.

Versión incremental (usada con If-None-Match en consultas condicionales).

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.

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).

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).

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.

Puntaje de la extracción OCR 0–1 (solo si validation_type es del tipo ocr).

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.

Advertencias de normalización presentes. Permiten explicar un resultado not_found inesperado.

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.

Identificador de la validación previa.

Fecha y hora, en ISO 8601 UTC, de creación de la validación previa.

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.

Últimos 4 dígitos de la cuenta enviada en cuenta_beneficiaria.

Últimos 4 dígitos de la cuenta que muestra la imagen (los visibles, 3 o 4, si está enmascarada).

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.

Posición (desde 0) de la cuenta ganadora en el arreglo cuentas_candidatas, tal como se envió.

Últimos 4 dígitos de la cuenta ganadora.

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.

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.

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.

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.

Clave de la operación dentro del sistema SPEI (ClaveSPEI del CEP). Distinta de la clave de rastreo.

Clave de rastreo de la operación SPEI — la misma que se envía en la petición de validación.

Sello digital del CEP (sello) — la firma que Banxico calcula sobre la operación.

Número del certificado digital que Banxico usó para sellar el CEP.

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.

Banco emisor de la operación, tal como lo identifica el CEP.

Nombre del ordenante de la operación, tal como lo reporta el CEP.

Tipo de cuenta del ordenante (por ejemplo, CLABE o tarjeta), tal como lo reporta el CEP.

Cuenta del ordenante, tal como la reporta el CEP, sin enmascarar en este recurso (consulta privada, propia del dueño de la validación).

RFC del ordenante, tal como lo reporta el CEP.

Banco receptor de la operación, tal como lo identifica el CEP.

Nombre del beneficiario de la operación, tal como lo reporta el CEP.

Tipo de cuenta del beneficiario (por ejemplo, CLABE o tarjeta), tal como lo reporta el CEP.

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).

RFC del beneficiario, tal como lo reporta el CEP.

Monto de la operación que Banxico confirmó por el CEP, en pesos.

IVA de la operación reportado por el CEP, en pesos.

Concepto de pago de la operación, tal como lo reporta el CEP.

Mensaje legible del error terminal (si aplica).

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.

Identificador del trabajo de importación masiva (si aplica).

Posición dentro del trabajo (comenzando en 1).

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.

true cuando la validación tiene reintentos configurados, aunque su ciclo ya haya terminado (terminal_state).

Número máximo de reintentos configurado; null cuando enabled es false.

Intervalo en segundos entre reintentos, de 300 a 86400; null cuando enabled es false.

Resultados que originan un reintento: not_found, cep_unavailable y error; null cuando enabled es false.

Cantidad de reintentos completados hasta el momento.

Fecha del próximo reintento; null cuando no hay uno programado.

Fecha en que un reintento obtuvo valid; null mientras no ocurra.

Fecha en que se agotaron los intentos; null mientras no ocurra.

Fecha de cancelación del ciclo; null mientras no ocurra.

Situación del ciclo: pending, resolved, exhausted o cancelled. Es null cuando la validación no tiene un ciclo de reintentos.

Enlaces relacionados (JSON:API links).

Enlace canónico al detalle de la validación.

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.

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.