VerikoDocs

Escribe para buscar. Enter abre el primer resultado.

EN

Crear, actualizar y exportar beneficiarios

Objetivo

Construye y mantiene una lista blanca de cuentas beneficiarias de confianza — CLABEs, números de tarjeta de débito/crédito y números de teléfono DiMo. La lista blanca es usada por el pipeline de OCR para completar los dígitos visibles de una cuenta enmascarada y por tu aplicación para validar que el destino de una transferencia es conocido antes de enviarla.

La lista no sirve para averiguar a cuál de tus cuentas llegó una transferencia. Si la captura no muestra la cuenta, envía cuenta_beneficiaria en la validación.

Requisitos previos

  • Una API key activa (veriko_…) con permisos beneficiaries:read y beneficiaries:create.
  • Para actualizar: beneficiaries:update. Para eliminar/archivar: beneficiaries:delete.
  • Para importar muchas cuentas de una sola vez desde una hoja de cálculo, usa POST /v1/beneficiaries/imports — ver Importación masiva de beneficiarios.

Pasos

1. Listar beneficiarios existentes

Obtén tu lista blanca completa. La respuesta no está paginada; usa with_archived para controlar la visibilidad de las cuentas archivadas.

# Solo cuentas activas
curl 'https://api.veriko.mx/v1/beneficiaries?with_archived=0' \
  -H 'Authorization: Bearer veriko_••••'
{
  "data": [
    {
      "type": "beneficiary",
      "id": "42",
      "attributes": {
        "account_number": "012180004412345678",
        "account_type": "clabe",
        "bank_code": "40012",
        "bank_name": "BBVA MEXICO",
        "label": "Proveedor Alpha",
        "status": "active",
        "created_at": "2025-01-10T09:00:00Z"
      }
    }
  ]
}

2. Añadir un beneficiario

El listado incluye meta.plan_cap.max y meta.plan_cap.current: el tope del plan y la cantidad activa, independientemente del filtro with_archived. max=-1 significa sin tope. Al alcanzar el cupo, la app y el bot bloquean el alta y piden archivar una cuenta para liberar espacio. El servidor responde 422 plan_cap_exceeded; reactivar una cuenta archivada también ocupa un lugar. Editar una etiqueta o archivar una cuenta sigue permitido.

curl -X POST 'https://api.veriko.mx/v1/beneficiaries' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Proveedor Beta",
    "account_number": "646180157000001234"
  }'

Los campos del alta son account_number (obligatorio) y label (opcional, máximo 100 caracteres). El tipo de cuenta no se envía: se deduce por la longitud de account_number, con 18 dígitos para una CLABE, 16 para una tarjeta y 10 para un celular DiMo.

Para un celular DiMo, bank_code es obligatorio: el número por sí solo no identifica a la institución, y lo encuentras en la lista de bancos. Para una CLABE o una tarjeta el código se deriva del prefijo o del BIN, y el que envíes se ignora.

Respuesta 201:

{
  "data": {
    "type": "beneficiary",
    "id": "87",
    "attributes": {
      "account_number": "646180157000001234",
      "account_type": "clabe",
      "bank_code": "90646",
      "bank_name": "STP",
      "label": "Proveedor Beta",
      "status": "active",
      "created_at": "2025-04-22T14:15:00Z"
    }
  }
}

3. Actualizar un beneficiario

Cambia la etiqueta (label). Si envías un account_number nuevo, el tipo de cuenta y el banco se vuelven a deducir con las mismas reglas que en el alta. En un celular DiMo también puedes cambiar solo el bank_code.

curl -X PUT 'https://api.veriko.mx/v1/beneficiaries/87' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{ "label": "Proveedor Beta S.A." }'

Devuelve 200 con el registro actualizado.

4. Archivar un beneficiario

Realiza un soft-delete de una cuenta para quitarla de la lista activa sin eliminar permanentemente el historial. Si vuelves a dar de alta el mismo número, por la API, la app, el bot o una importación, la cuenta archivada se reactiva en lugar de duplicarse y conserva su alias salvo que envíes uno nuevo.

curl -X DELETE 'https://api.veriko.mx/v1/beneficiaries/87' \
  -H 'Authorization: Bearer veriko_••••'

Devuelve 204. Para ver cuentas archivadas: GET /v1/beneficiaries?with_archived=1.

5. Exportar la lista

Descarga tu lista completa de beneficiarios como archivo para auditoría o sincronización de sistemas:

curl 'https://api.veriko.mx/v1/beneficiaries/export?format=csv' \
  -H 'Authorization: Bearer veriko_••••' \
  --output beneficiarios.csv

Usa format=xlsx para una hoja de cálculo. La exportación respeta el mismo filtro with_archived que el endpoint de listado.

Siguientes pasos