← Volver al índice de esquemas

`OcrValidationRequest`

Cuerpo de `POST /v1/validate-ocr` con el comprobante en `image` o `image_url`; exige al menos uno de ambos campos. `cuenta_beneficiaria` y `cuentas_candidatas` no pueden ir juntas.

Propiedades

Campo	Tipo	Descripción
`image`	`string (byte)`	Comprobante codificado en base64, en imagen o en PDF. Si también se proporciona `image_url`, solo se considera `image_url`. Formatos aceptados: JPEG, PNG, WebP o PDF de 1 a 3 páginas. Tamaño máximo: `12 MB`. Dimensiones máximas de una imagen: `12000px` por lado. Admite el prefijo `data:image/...;base64,` o `data:application/pdf;base64,`.
`image_url`	`string (uri)`	URL pública (HTTPS) del comprobante. Sigue los mismos límites de formato y tamaño que `image`: JPEG, PNG, WebP o PDF de 1 a 3 páginas, con un máximo de `12 MB`. Una URL `http` responde un estado HTTP `422` (con `invalid_url_scheme` en el cuerpo), y una redirección hacia `http` no se sigue.
`cuenta_beneficiaria`	`string`	Cuenta receptora de la transferencia (útil cuando falta o está incompleta en la imagen). Requerida para celular DiMo; opcional si la imagen muestra la cuenta completa o sus últimos dígitos, que se completan con los beneficiarios guardados (estos no sustituyen a este campo). Acepta CLABE (18 dígitos), tarjeta (16 dígitos) o celular DiMo (10 dígitos). No puede enviarse junto con `cuentas_candidatas`: enviar las dos responde un estado HTTP `422` (con `cuenta_y_candidatas_excluyentes` en el cuerpo).
`cuentas_candidatas`	`array`	Cuentas entre las que está la receptora de la transferencia, para cuando la imagen no la muestra y no se sabe cuál fue. Va en lugar de `cuenta_beneficiaria`: enviar las dos responde un estado HTTP `422` (con `cuenta_y_candidatas_excluyentes` en el cuerpo). Tiene prioridad sobre la cuenta que se lea en la imagen. Admite de 2 al máximo vigente de la plataforma, 3 por defecto y nunca más de 10; el `422` por exceso informa el máximo en `meta.max`. Cada cuenta es una CLABE (18 dígitos), una tarjeta (16) o un celular DiMo (10), con su dígito verificador válido y sin repetirse. Una lista que no cumple responde un `422` con `cuentas_candidatas_invalidas`, y señala en `field_errors` la posición que falló. Los dos errores ocurren antes de consumir cuota. Consume una sola unidad de cuota, lleve las cuentas que lleve, también con `?async=1`. La consulta recorre las candidatas en el orden enviado y adopta la primera que coincide con la transferencia. La ganadora se publica completa en `normalized_data.cuenta_beneficiaria`, y `candidate_match` indica su posición. Si ninguna coincide, la respuesta es un estado HTTP `422` con el motivo en `code` (`cuenta_unresolvable_after_probes` cuando no hay un diagnóstico más preciso).
`banco_emisor`	`string`	Código SPEI del banco emisor (4 o 5 dígitos, p. ej. `40012`), para corregir el que se leyó del comprobante. Sustituye al leído antes de consultar Banxico. Un valor que no son 4 o 5 dígitos (un nombre, por ejemplo) se ignora y se conserva el leído.
`banco_receptor`	`string`	Código SPEI del banco receptor (4 o 5 dígitos, p. ej. `40002`), para corregir el que se leyó del comprobante. Sustituye al leído antes de consultar Banxico. Un valor que no son 4 o 5 dígitos (un nombre, por ejemplo) se ignora y se conserva el leído.
`retry_policy`	`object`	Política de reintentos automáticos para esta validación. Si se omite, se aplica la política general del usuario, configurada en `PUT /v1/users/me/retry-policy`. Los reintentos no consumen cuota de validaciones.
`enabled`	`boolean`	`true` cuando el ciclo de reintentos está activo. Si es `false`, los demás campos pueden ser ignorados.
`max_retries`	`integer`	Número máximo de reintentos automáticos. Una vez alcanzado, el ciclo pasa al estado terminal `exhausted`.
`interval_seconds`	`integer`	Segundos de espera entre cada reintento. Valores válidos: 300–86400 (5 min a 24h).
`outcomes`	`array`	Resultados que originan un reintento. De forma predeterminada son `not_found`, `cep_unavailable` y `error`; la combinación `["not_found", "cep_unavailable"]` excluye `error`.
`client_ref`	`string`	Referencia propia que se devuelve tal cual en la validación, en los webhooks de validación y como filtro exacto de `GET /v1/validations`. Texto de 1 a 64 caracteres, sin saltos de línea ni emoji; se recorta antes de guardarse. Un valor que no cumple se rechaza con un estado HTTP `422` (con `invalid_client_ref` en el cuerpo). No debe contener datos personales.
`retain_image`	`boolean`	`true` cuando la plataforma conserva el archivo del comprobante después de validarlo, que es lo habitual. Con `false`, el archivo se borra en cuanto la validación llega a un estado terminal del que ya no se necesita; el veredicto y los datos extraídos se conservan. Con `false`, la validación publica `image_retained=false` y `GET /v1/validations/{id}/image` responde un estado HTTP `410` (con `image_not_retained` en el cuerpo). Vale igual con `?async=1`. El archivo existe mientras la validación se procesa. Si entró como un CEP en PDF y tiene reintentos automáticos activos, el borrado espera a que ese ciclo cierre, porque cada reintento vuelve a comparar el sello del PDF. Un valor que no es booleano responde un estado HTTP `422` (con `invalid_retain_image` en el cuerpo), antes de consumir cuota.

Variantes

Debe incluir al menos uno de estos campos:

image
image_url

Usado en operaciones

POST /v1/validate-ocr