Una Alias Account define el contexto de negocio asociado con una Cuenta del Ledger en Midaz. Vincula un Holder a una cuenta específica en el ledger, enriqueciéndola con detalles bancarios, información regulatoria y datos de partes relacionadas.
Sin esta conexión, la mayoría de las funcionalidades impulsadas por el CRM — como tarifas, notificaciones y facturación — no funcionarán como se espera.
Cómo funciona
La Alias Account es una representación a nivel de CRM de una Cuenta del Ledger en Midaz. Al crear una Alias Account, proporcionas el ledgerId y el accountId que identifican la cuenta objetivo en el ledger. La Alias Account hereda automáticamente el document y el type del Holder asociado.
Este diseño mantiene la información de cuenta orientada al cliente (números bancarios, códigos de sucursal, identificadores regulatorios) separada del ledger transaccional, brindando flexibilidad para escenarios multi-banco e integración con sistemas externos.
Una Alias Account siempre debe estar vinculada a un Holder existente. Crea el Holder primero y luego crea la Alias Account. Consulta Usando CRM para el flujo de integración correcto. Campos de la Alias Account
Campos principales
| Campo | Tipo | Requerido | Descripción |
|---|
| id | uuid | Generado por el sistema | Identificador único de la Alias Account. |
| holderId | uuid | Generado por el sistema | El ID del Holder asociado (derivado de la ruta de la URL). |
| ledgerId | string | Sí | El UUID del Ledger en Midaz. |
| accountId | string | Sí | El UUID de la Cuenta del Ledger en Midaz. |
| document | string | Generado por el sistema | Heredado del Holder asociado. |
| type | string | Generado por el sistema | Heredado del Holder asociado (NATURAL_PERSON o LEGAL_PERSON). |
| metadata | object | No | Pares clave-valor para datos personalizados y no sensibles. Claves limitadas a 100 caracteres y valores a 2000 caracteres. |
| createdAt | datetime | Generado por el sistema | Timestamp de creación (RFC 3339). |
| updatedAt | datetime | Generado por el sistema | Timestamp de última actualización (RFC 3339). |
| deletedAt | datetime | Generado por el sistema | Timestamp de eliminación lógica, si aplica (RFC 3339). |
Detalles bancarios
El objeto bankingDetails almacena información de la institución financiera asociada al alias:
| Campo | Tipo | Requerido | Descripción |
|---|
| branch | string | No | Código de sucursal bancaria (ej.: 0001). |
| account | string | No | Número de cuenta bancaria (ej.: 123450). |
| type | string | No | Código del tipo de cuenta (ej.: CACC para cuenta corriente). |
| openingDate | string | No | Fecha de apertura de la cuenta en formato AAAA-MM-DD. |
| closingDate | string | No | Fecha de cierre de la cuenta, si aplica, en formato AAAA-MM-DD. |
| iban | string | No | Número Internacional de Cuenta Bancaria (IBAN). |
| countryCode | string | No | Código de país de la institución financiera (ej.: BR, US). |
| bankId | string | No | Identificador del banco o institución financiera. |
Campos regulatorios
El objeto regulatoryFields almacena datos requeridos por reguladores financieros:
| Campo | Tipo | Requerido | Descripción |
|---|
| participantDocument | string | No | Número de documento que identifica la entidad del grupo financiero propietaria de la relación. |
Partes relacionadas
El array relatedParties define individuos o entidades relacionados con la Alias Account con roles específicos. Cada entrada contiene:
| Campo | Tipo | Requerido | Descripción |
|---|
| id | uuid | Generado por el sistema | Identificador único de la parte relacionada. |
| document | string | Sí | Número de documento de la parte relacionada. |
| name | string | Sí | Nombre completo de la parte relacionada. |
| role | enum | Sí | PRIMARY_HOLDER, LEGAL_REPRESENTATIVE o RESPONSIBLE_PARTY. |
| startDate | string | Sí | Fecha de inicio de la relación en formato AAAA-MM-DD. |
| endDate | string | No | Fecha de fin de la relación, si aplica. |
Las partes relacionadas pueden agregarse al crear o actualizar una Alias Account. Para eliminar una parte relacionada específica, usa el endpoint dedicado Eliminar Parte Relacionada. Seguridad de los datos
Varios campos de la Alias Account están cifrados en reposo, incluyendo el campo document heredado y detalles bancarios como account e iban. Esto garantiza que los datos financieros sensibles estén protegidos incluso si el almacenamiento subyacente se ve comprometido.
Nunca almacenes información sensible en el objeto metadata. Los metadatos no están cifrados y se almacenan en texto plano.
Gestionando Alias Accounts
Vía API
Usa la API del CRM para gestionar Alias Accounts programáticamente:
Todas las solicitudes a la API del CRM requieren el header X-Organization-Id. El ID del Holder forma parte de la ruta de la URL para la mayoría de las operaciones de Alias Account. Si Access Manager está habilitado, también se requiere un header Authorization con un token Bearer. Vía Lerian Console
Puedes gestionar Alias Accounts a través de la página Alias Accounts en el Módulo Midaz de Lerian Console. La consola ofrece una interfaz visual para crear, ver, editar y eliminar Alias Accounts sin escribir código.
Aprende más en la guía de Gestión de Alias Accounts.
Próximos pasos
