Docs
EN

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 resolver números de cuenta enmascarados y por tu aplicación para validar que el destino de una transferencia es conocido antes de enviarla.

Requisitos previos

  • Una API key activa (mxcep_…) 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.example.com/v1/beneficiaries?with_archived=0' \
  -H 'Authorization: Bearer mxcep_••••'
{
  "data": [
    {
      "type": "beneficiary",
      "id": 42,
      "attributes": {
        "alias": "Proveedor Alpha",
        "account": "012180004412345678",
        "account_type": "clabe",
        "bank_code": "40012",
        "bank_name": "BBVA MEXICO",
        "archived": false,
        "created_at": "2025-01-10T09:00:00Z"
      }
    }
  ]
}

2. Añadir un beneficiario

curl -X POST 'https://api.example.com/v1/beneficiaries' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "alias": "Proveedor Beta",
    "account": "646180157000001234",
    "account_type": "clabe"
  }'

Para cuentas DiMo (número de celular), establece account_type como phone y proporciona el número de 10 dígitos. Los códigos de banco se derivan automáticamente del prefijo CLABE o del BIN de la tarjeta; puedes sobreescribirlos explícitamente si es necesario.

Respuesta 201:

{
  "data": {
    "type": "beneficiary",
    "id": 87,
    "attributes": {
      "alias": "Proveedor Beta",
      "account": "646180157000001234",
      "account_type": "clabe",
      "bank_code": "90646",
      "bank_name": "STP",
      "archived": false,
      "created_at": "2025-04-22T14:15:00Z"
    }
  }
}

3. Actualizar un beneficiario

Cambia el alias o cualquier campo editable. El número de cuenta en sí es inmutable — elimina y vuelve a añadir si necesitas cambiarlo.

curl -X PUT 'https://api.example.com/v1/beneficiaries/87' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{ "alias": "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. Las cuentas previamente archivadas con el mismo número se reactivan en lugar de duplicarse en una importación.

curl -X DELETE 'https://api.example.com/v1/beneficiaries/87' \
  -H 'Authorization: Bearer mxcep_••••'

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.example.com/v1/beneficiaries/export?format=csv' \
  -H 'Authorization: Bearer mxcep_••••' \
  --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