¿Qué es un beneficiario?

En Veriko, denominamos "beneficiario" a cualquier cuenta bancaria que reciba transferencias SPEI. Los beneficiarios pueden estar o no guardados en Veriko. Aunque es muy útil guardarlos, tiene tres efectos concretos:

1. Auto-completa el banco en validaciones futuras.
2. Ayuda en las validaciones desde imagen (OCR) a identificar la cuenta_beneficiaria cuando está enmascarada o incompleta (común en algunos comprobantes).
3. Habilita los estado de cuenta de Finanzas y mejora la organización.

Los tres tipos de beneficiarios

El account_type (tipo de cuenta beneficiaria) se detecta mediante el número de dígitos:

• clabe — 18 dígitos. El banco se detecta y se deriva en automático. No requiere bank_code en el body.
• card — 16 dígitos. El banco se detecta y se deriva en automático. No requiere bank_code.
• phone — 10 dígitos exactos. Número celular asociado a una cuenta bancaria. Sí requiere bank_code y es obligatorio en el body porque no existe un mapeo público de teléfonos→bancos; el endpoint responde 422 bank_code_required_for_phone cuando falta bank_code.

Beneficiarios y validaciones desde imagen (OCR)

Cuando llamas a POST /v1/validate-ocr, la "cuenta beneficiaria" de la imagen puede venir incompleta o con la forma "••••5678" o "4111 •••• •••• 1111" (común en comprobantes de algunos bancos), el sistema de búsqueda de Veriko usa los últimos dígitos visibles y ejecuta una búsqueda en este orden:

1. Parámetro cuenta_beneficiaria de la petición (no recomendable): Agrega completa la cuenta receptora de la transferencia, la cuenta extraida de la imagen se ignorará y se validará con la que hayas indicado.
2. Lista blanca del usuario: Filtra los beneficiarios activos del usuario a raíz de los dígitos obtenidos de la imagen en relacion con la cuenta receptora (beneficiaria).

Sin beneficiarios registrados un comprobante enmascarado puede quedar ambiguo y no resolverse. Por ello es recomendable registrar las cuentas en las que recibes pagos frecuentemente.

Crear y gestionar beneficiarios

• POST /v1/beneficiaries: Crear un beneficiario — Acepta un alias opcional.
• GET /v1/beneficiaries: Listar beneficiarios guardados — Con filtros para archivados.
• DELETE /v1/beneficiaries/{id}: Archivar beneficiarios — Para que dejen de aparecer en las listas.
• PATCH /v1/beneficiaries/{id}: Editar beneficiario — Para mantener actualizado tu catálogo.