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

> Vincule Holders a Contas do Ledger Midaz com Alias Accounts e adicione contexto bancário, regulatório e de partes relacionadas ao CRM.

Uma **Alias Account** adiciona contexto de negócio a uma [Conta do Ledger](/pt/midaz/accounts) no Midaz. Ela vincula um [Holder](/pt/midaz/crm/holders) a uma conta específica no ledger. Ela adiciona detalhes bancários, informações regulatórias e dados de partes relacionadas a essa conta.

Sem esse vínculo, os recursos do CRM que dependem do contexto de conta não funcionam como esperado.

<Tip>
  Para um passo a passo sobre como vincular holders a contas, consulte [Primeiros passos com o CRM](/pt/midaz/crm/crm-getting-started).
</Tip>

## Como funciona

***

A Alias Account é uma representação a nível de CRM de uma Conta do Ledger no Midaz. Ao criar uma Alias Account, você fornece o `ledgerId` e o `accountId` que identificam a conta-alvo no ledger. A Alias Account herda automaticamente o `document` e o `type` do Holder associado.

Esse design mantém os detalhes de conta voltados ao cliente separados do ledger transacional. Os números bancários, os códigos de agência e os identificadores regulatórios permanecem no CRM, não no ledger. Essa separação suporta cenários multi-banco e integração com sistemas externos.

<Warning>
  Vincule sempre uma Alias Account a um Holder existente. Crie o Holder primeiro e depois crie a Alias Account. Consulte [Usando o CRM](/pt/midaz/crm/crm-using-overview) para o fluxo de integração correto.
</Warning>

## Campos da Alias Account

***

### Campos principais

| Campo         | Tipo       | Obrigatório         | Descrição                                                                                                                 |
| :------------ | :--------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------ |
| **id**        | `uuid`     | Gerado pelo sistema | Identificador único da Alias Account.                                                                                     |
| **holderId**  | `uuid`     | Gerado pelo sistema | O ID do Holder associado (derivado do caminho da URL).                                                                    |
| **ledgerId**  | `string`   | Sim                 | O UUID do Ledger no Midaz.                                                                                                |
| **accountId** | `string`   | Sim                 | O UUID da Conta do Ledger no Midaz.                                                                                       |
| **document**  | `string`   | Gerado pelo sistema | Herdado do Holder associado.                                                                                              |
| **type**      | `string`   | Gerado pelo sistema | Herdado do Holder associado (`NATURAL_PERSON` ou `LEGAL_PERSON`).                                                         |
| **metadata**  | `object`   | Não                 | Pares chave-valor para dados customizados e não sensíveis. Chaves limitadas a 100 caracteres e valores a 2000 caracteres. |
| **createdAt** | `datetime` | Gerado pelo sistema | Timestamp de criação (RFC 3339).                                                                                          |
| **updatedAt** | `datetime` | Gerado pelo sistema | Timestamp da última atualização (RFC 3339).                                                                               |
| **deletedAt** | `datetime` | Gerado pelo sistema | Timestamp da exclusão lógica, se aplicável (RFC 3339).                                                                    |

### Detalhes bancários

O objeto `bankingDetails` armazena informações sobre a instituição financeira do alias:

| Campo           | Tipo     | Obrigatório | Descrição                                                             |
| :-------------- | :------- | :---------- | :-------------------------------------------------------------------- |
| **branch**      | `string` | Não         | Código da agência bancária (ex.: `0001`).                             |
| **account**     | `string` | Não         | Número da conta bancária (ex.: `123450`).                             |
| **type**        | `string` | Não         | Código do tipo de conta (ex.: `CACC` para conta corrente).            |
| **openingDate** | `string` | Não         | Data de abertura da conta no formato `AAAA-MM-DD`.                    |
| **closingDate** | `string` | Não         | Data de encerramento da conta, se aplicável, no formato `AAAA-MM-DD`. |
| **iban**        | `string` | Não         | Número Internacional de Conta Bancária (IBAN).                        |
| **countryCode** | `string` | Não         | Código do país da instituição financeira (ex.: `BR`, `US`).           |
| **bankId**      | `string` | Não         | Identificador do banco ou instituição financeira.                     |

### Campos regulatórios

O objeto `regulatoryFields` armazena dados que os reguladores financeiros exigem:

| Campo                   | Tipo     | Obrigatório | Descrição                                                                                         |
| :---------------------- | :------- | :---------- | :------------------------------------------------------------------------------------------------ |
| **participantDocument** | `string` | Não         | Número do documento que identifica a entidade do grupo financeiro proprietária do relacionamento. |

### Partes relacionadas

Uma parte relacionada é uma pessoa ou entidade vinculada a uma Alias Account. Cada parte relacionada tem um papel definido e um relacionamento com prazo determinado. As partes relacionadas representam as pessoas ou organizações reais conectadas à conta, para titularidade, autoridade legal ou responsabilidade operacional. A conformidade, os relatórios regulatórios e os fluxos de trabalho do CRM as utilizam.

#### Papéis

Cada parte relacionada deve ter um dos seguintes papéis:

| Papel                  | Descrição                                                                                                                                                   |
| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PRIMARY_HOLDER`       | O principal indivíduo ou entidade que possui ou detém a conta. Normalmente é o próprio cliente quando a titularidade da conta difere do registro do Holder. |
| `LEGAL_REPRESENTATIVE` | Alguém com autoridade legal para agir em nome do titular — por exemplo, um tutor legal, advogado ou representante autorizado.                               |
| `RESPONSIBLE_PARTY`    | Uma entidade responsável pela conta em capacidade operacional ou regulatória, como um responsável de compliance ou uma organização matriz.                  |

#### Relacionamentos com prazo determinado

Todo relacionamento de parte relacionada tem um período ativo definido:

* **`startDate`** — Obrigatório. A data em que o relacionamento entrou em vigor (`AAAA-MM-DD`).
* **`endDate`** — Opcional. A data em que o relacionamento terminou (`AAAA-MM-DD`). Se você omitir, o relacionamento permanece ativo. Quando você define, `endDate` deve ser posterior a `startDate`.

Esse design registra quem teve um relacionamento com a conta, e em qual capacidade. Ele mantém os relacionamentos passados no registro.

#### Gerenciando partes relacionadas

Você gerencia as partes relacionadas através dos endpoints de Alias Account. Não há endpoints independentes de criação ou listagem:

* **Adicionar na criação** — Inclua um array `relatedParties` no corpo da requisição de [Criar Alias Account](/pt/reference/midaz/crm/create-alias-account).
* **Adicionar a uma existente** — Inclua um array `relatedParties` no corpo da requisição de [Atualizar Alias Account](/pt/reference/midaz/crm/update-alias-account). O Midaz **anexa** novas entradas à lista existente. Ele não substitui as partes relacionadas existentes.
* **Remover** — Use o endpoint [Excluir Parte Relacionada](/pt/reference/midaz/crm/delete-related-party) com o `related_party_id` específico.
* **Listar** — A resposta da Alias Account retorna as partes relacionadas no array `relatedParties`.

#### Campos

| Campo         | Tipo     | Obrigatório         | Descrição                                                                                           |
| :------------ | :------- | :------------------ | :-------------------------------------------------------------------------------------------------- |
| **id**        | `uuid`   | Gerado pelo sistema | Identificador único da parte relacionada.                                                           |
| **document**  | `string` | Sim                 | Número do documento da parte relacionada. Não pode ser vazio ou apenas espaços.                     |
| **name**      | `string` | Sim                 | Nome completo da parte relacionada. Não pode ser vazio ou apenas espaços.                           |
| **role**      | `enum`   | Sim                 | `PRIMARY_HOLDER`, `LEGAL_REPRESENTATIVE` ou `RESPONSIBLE_PARTY`.                                    |
| **startDate** | `string` | Sim                 | Data de início do relacionamento no formato `AAAA-MM-DD`.                                           |
| **endDate**   | `string` | Não                 | Data de término do relacionamento, se aplicável. Deve ser posterior a `startDate` quando fornecido. |

<Warning>
  Erros de validação para campos de partes relacionadas retornam códigos de erro específicos: **CRM-0025** (papel inválido), **CRM-0026** (document obrigatório), **CRM-0027** (name obrigatório), **CRM-0028** (startDate obrigatório), **CRM-0029** (endDate inválido — deve ser posterior ao startDate). Consulte a [referência de erros do CRM](/pt/reference/midaz/crm/crm-error-list) para detalhes.
</Warning>

## Segurança dos dados

***

O Midaz **criptografa vários campos da Alias Account em repouso**, incluindo o campo `document` herdado e detalhes bancários como `account` e `iban`. A criptografia protege dados financeiros sensíveis mesmo se um atacante acessar o armazenamento subjacente.

<Warning>
  Nunca armazene informações sensíveis no objeto `metadata`. O Midaz **não** criptografa os metadados, e os armazena em texto simples.
</Warning>

Para a lista completa de campos protegidos e estratégias de criptografia, consulte [Segurança de dados do CRM](/pt/midaz/crm/crm-data-security).

## Gerenciando Alias Accounts

***

### Via API

Use a API do CRM para gerenciar Alias Accounts programaticamente:

* [Criar uma Alias Account](/pt/reference/midaz/crm/create-alias-account) — Vincular um Holder a uma Conta do Ledger no Midaz.
* [Listar Alias Accounts](/pt/reference/midaz/crm/list-alias-accounts) — Visualizar todas as Alias Accounts com paginação e filtros.
* [Consultar uma Alias Account](/pt/reference/midaz/crm/retrieve-alias-account) — Obter os detalhes de uma Alias Account específica.
* [Atualizar uma Alias Account](/pt/reference/midaz/crm/update-alias-account) — Editar os detalhes de uma Alias Account existente.
* [Excluir uma Alias Account](/pt/reference/midaz/crm/delete-alias-account) — Excluir logicamente ou remover permanentemente uma Alias Account.

<Note>
  O ID da organização é um parâmetro do caminho da URL para toda operação de Alias Account. O ID do Holder é um parâmetro do caminho para a maioria delas. Se o [Access Manager](/pt/platform/access-manager/access-manager) estiver habilitado, adicione um header `Authorization` com um token Bearer.
</Note>

### Via Lerian Console

Você pode gerenciar Alias Accounts através da página **Alias Accounts** no Módulo Midaz do [Lerian Console](/pt/platform/console/about-lerian-console). O console oferece uma interface visual para criar, visualizar, editar e excluir Alias Accounts sem escrever código.

[**Saiba mais no guia de Gerenciamento de Alias Accounts.**](/pt/midaz/console/managing-crm-alias-accounts)

## Próximos passos

***

<CardGroup cols={2}>
  <Card title="Holders" icon="user" href="/pt/midaz/crm/holders">
    Saiba mais sobre a entidade Holder à qual uma Alias Account se vincula.
  </Card>

  <Card title="Boas práticas" icon="check" href="/pt/midaz/crm/crm-best-practices">
    Revise as boas práticas operacionais e de gerenciamento de dados para o CRM.
  </Card>
</CardGroup>