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.Documentation Index
Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
Use this file to discover all available pages before exploring further.
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.
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 objetobankingDetails 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 objetoregulatoryFields 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
Las partes relacionadas son individuos o entidades asociados con una Alias Account que tienen un rol definido y una relación con límite de tiempo. Representan a las personas u organizaciones reales conectadas a la cuenta — ya sea por titularidad, autoridad legal o responsabilidad operacional — y se utilizan en cumplimiento normativo, informes regulatorios y flujos de trabajo del CRM.Roles
Cada parte relacionada debe tener uno de los siguientes roles:| Rol | Descripción |
|---|---|
PRIMARY_HOLDER | El principal individuo o entidad que posee o detenta la cuenta. Típicamente es el propio cliente cuando la titularidad de la cuenta difiere del registro del Holder. |
LEGAL_REPRESENTATIVE | Alguien con autoridad legal para actuar en nombre del titular — por ejemplo, un tutor legal, abogado o representante autorizado. |
RESPONSIBLE_PARTY | Una entidad responsable de la cuenta en capacidad operacional o regulatoria, como un responsable de cumplimiento o una organización matriz. |
Relaciones con límite de tiempo
Cada relación de parte relacionada tiene un período activo definido:startDate— Requerido. La fecha en que la relación entró en vigor (AAAA-MM-DD).endDate— Opcional. La fecha en que la relación terminó (AAAA-MM-DD). Si se omite, la relación se considera actualmente activa. Cuando se proporciona,endDatedebe ser posterior astartDate.
Gestionando partes relacionadas
Las partes relacionadas se gestionan a través de los endpoints de Alias Account — no hay endpoints independientes de creación o listado:- Agregar en la creación — Incluye un array
relatedPartiesen el cuerpo de la solicitud de Crear Alias Account. - Agregar a una existente — Incluye un array
relatedPartiesen el cuerpo de la solicitud de Actualizar Alias Account. Las nuevas entradas se agregan a la lista existente — las partes relacionadas existentes no se reemplazan. - Eliminar — Usa el endpoint Eliminar Parte Relacionada con el
related_party_idespecífico. - Listar — Las partes relacionadas se devuelven como parte de la respuesta de la Alias Account en el array
relatedParties.
Campos
| 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. No puede estar vacío o contener solo espacios. |
| name | string | Sí | Nombre completo de la parte relacionada. No puede estar vacío o contener solo espacios. |
| 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. Debe ser posterior a startDate cuando se proporciona. |
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.
Para la lista completa de campos protegidos y estrategias de cifrado, consulta Seguridad de datos del CRM.
Gestionando Alias Accounts
Vía API
Usa la API del CRM para gestionar Alias Accounts programáticamente:- Crear una Alias Account — Vincular un Holder a una Cuenta del Ledger en Midaz.
- Listar Alias Accounts — Ver todas las Alias Accounts con paginación y filtros.
- Consultar una Alias Account — Obtener los detalles de una Alias Account específica.
- Actualizar una Alias Account — Editar los detalles de una Alias Account existente.
- Eliminar una Alias Account — Eliminar lógicamente o remover permanentemente una Alias Account.
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
Holders
Aprende sobre la entidad Holder a la que están vinculadas las Alias Accounts.
Buenas prácticas
Revisa las buenas prácticas operacionales y de gestión de datos para CRM.