> ## 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.

# Alias Accounts

> Vincula Holders a Cuentas del Ledger con Alias Accounts y añade contexto bancario, regulatorio y de partes relacionadas sin tocar la capa transaccional.

Una **Alias Account** agrega contexto de negocio a una [Cuenta del Ledger](/es/midaz/accounts) en Midaz. Vincula un [Holder](/es/midaz/crm/holders) a una cuenta específica en el ledger. Agrega detalles bancarios, información regulatoria y datos de partes relacionadas a esa cuenta.

Sin este vínculo, las funcionalidades del CRM que dependen del contexto de cuenta no funcionan como se espera.

<Tip>
  Para un recorrido paso a paso sobre cómo vincular holders a cuentas, consulte [Primeros pasos con CRM](/es/midaz/crm/crm-getting-started).
</Tip>

## 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 los detalles de cuenta orientados al cliente separados del ledger transaccional. Los números bancarios, los códigos de sucursal y los identificadores regulatorios permanecen en el CRM, no en el ledger. Esta separación admite configuraciones multi-banco e integración con sistemas externos.

<Warning>
  Vincula siempre una Alias Account a un Holder existente. Crea el Holder primero y luego crea la Alias Account. Consulta [Usando CRM](/es/midaz/crm/crm-using-overview) para el flujo de integración correcto.
</Warning>

## 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 sobre la institución financiera del 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 que los reguladores financieros exigen:

| 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

Una parte relacionada es una persona o entidad vinculada a una Alias Account. Cada parte relacionada tiene un rol definido y una relación con límite de tiempo. Las partes relacionadas representan a las personas u organizaciones reales conectadas a la cuenta, para titularidad, autoridad legal o responsabilidad operacional. El cumplimiento normativo, los informes regulatorios y los flujos de trabajo del CRM las utilizan.

#### 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 la omites, la relación permanece activa. Cuando la defines, `endDate` debe ser posterior a `startDate`.

Este diseño registra quién tuvo una relación con la cuenta, y en qué capacidad. Mantiene las relaciones pasadas en el registro.

#### Gestionando partes relacionadas

Gestionas las partes relacionadas 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 `relatedParties` en el cuerpo de la solicitud de [Crear Alias Account](/es/reference/midaz/crm/create-alias-account).
* **Agregar a una existente** — Incluye un array `relatedParties` en el cuerpo de la solicitud de [Actualizar Alias Account](/es/reference/midaz/crm/update-alias-account). Midaz **agrega** nuevas entradas a la lista existente. No reemplaza las partes relacionadas existentes.
* **Eliminar** — Usa el endpoint [Eliminar Parte Relacionada](/es/reference/midaz/crm/delete-related-party) con el `related_party_id` específico.
* **Listar** — La respuesta de la Alias Account devuelve las partes relacionadas 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. |

<Warning>
  Los errores de validación para campos de partes relacionadas devuelven códigos de error específicos: **CRM-0025** (rol inválido), **CRM-0026** (document requerido), **CRM-0027** (name requerido), **CRM-0028** (startDate requerido), **CRM-0029** (endDate inválido — debe ser posterior a startDate). Consulta la [referencia de errores del CRM](/es/reference/midaz/crm/crm-error-list) para más detalles.
</Warning>

## Seguridad de los datos

***

Midaz **cifra varios campos de la Alias Account en reposo**, incluyendo el campo `document` heredado y detalles bancarios como `account` e `iban`. El cifrado protege los datos financieros sensibles incluso si un atacante accede al almacenamiento subyacente.

<Warning>
  Nunca almacenes información sensible en el objeto `metadata`. Midaz **no** cifra los metadatos, y los almacena en texto plano.
</Warning>

Para la lista completa de campos protegidos y estrategias de cifrado, consulta [Seguridad de datos del CRM](/es/midaz/crm/crm-data-security).

## Gestionando Alias Accounts

***

### Vía API

Usa la API del CRM para gestionar Alias Accounts programáticamente:

* [Crear una Alias Account](/es/reference/midaz/crm/create-alias-account) — Vincular un Holder a una Cuenta del Ledger en Midaz.
* [Listar Alias Accounts](/es/reference/midaz/crm/list-alias-accounts) — Ver todas las Alias Accounts con paginación y filtros.
* [Consultar una Alias Account](/es/reference/midaz/crm/retrieve-alias-account) — Obtener los detalles de una Alias Account específica.
* [Actualizar una Alias Account](/es/reference/midaz/crm/update-alias-account) — Editar los detalles de una Alias Account existente.
* [Eliminar una Alias Account](/es/reference/midaz/crm/delete-alias-account) — Eliminar lógicamente o remover permanentemente una Alias Account.

<Note>
  El ID de la organización es un parámetro de la ruta de la URL para cada operación de Alias Account. El ID del Holder es un parámetro de la ruta para la mayoría de ellas. Si [Access Manager](/es/platform/access-manager/access-manager) está habilitado, agrega un header `Authorization` con un token Bearer.
</Note>

### 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](/es/platform/console/about-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.**](/es/midaz/console/managing-crm-alias-accounts)

## Próximos pasos

***

<CardGroup cols={2}>
  <Card title="Holders" icon="user" href="/es/midaz/crm/holders">
    Aprende sobre la entidad Holder a la que se vincula una Alias Account.
  </Card>

  <Card title="Buenas prácticas" icon="check" href="/es/midaz/crm/crm-best-practices">
    Revisa las buenas prácticas operacionales y de gestión de datos para CRM.
  </Card>
</CardGroup>