Uma Alias Account define o contexto de negócio associado a uma Conta do Ledger no Midaz. Ela vincula um Holder a uma conta específica no ledger, enriquecendo-a com detalhes bancários, informações regulatórias e dados de partes relacionadas. Sem essa conexão, a maioria dos recursos impulsionados pelo CRM — como taxas, notificações e cobranças — não funcionarão como esperado.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.
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 então herda automaticamente o document e o type do Holder associado.
Esse design mantém as informações de conta voltadas ao cliente (números bancários, códigos de agência, identificadores regulatórios) separadas do ledger transacional, oferecendo flexibilidade para cenários multi-banco e integração com sistemas externos.
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 objetobankingDetails armazena informações da instituição financeira associada ao 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 objetoregulatoryFields armazena dados exigidos por reguladores financeiros:
| 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
Partes relacionadas são indivíduos ou entidades associados a uma Alias Account com um papel definido e um relacionamento com prazo determinado. Eles representam as pessoas ou organizações reais conectadas à conta — seja para titularidade, autoridade legal ou responsabilidade operacional — e são utilizados em conformidade, relatórios regulatórios e fluxos de trabalho do CRM.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 omitido, o relacionamento é considerado atualmente ativo. Quando fornecido,endDatedeve ser posterior astartDate.
Gerenciando partes relacionadas
As partes relacionadas são gerenciadas através dos endpoints de Alias Account — não há endpoints independentes de criação ou listagem:- Adicionar na criação — Inclua um array
relatedPartiesno corpo da requisição de Criar Alias Account. - Adicionar a uma existente — Inclua um array
relatedPartiesno corpo da requisição de Atualizar Alias Account. Novas entradas são anexadas à lista existente — as partes relacionadas existentes não são substituídas. - Remover — Use o endpoint Excluir Parte Relacionada com o
related_party_idespecífico. - Listar — As partes relacionadas são retornadas como parte da resposta da Alias Account 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. |
Segurança dos dados
Vários campos da Alias Account são criptografados em repouso, incluindo o campo
document herdado e detalhes bancários como account e iban. Isso garante que dados financeiros sensíveis estejam protegidos mesmo se o armazenamento subjacente for comprometido.
Para a lista completa de campos protegidos e estratégias de criptografia, consulte Segurança de dados do CRM.
Gerenciando Alias Accounts
Via API
Use a API do CRM para gerenciar Alias Accounts programaticamente:- Criar uma Alias Account — Vincular um Holder a uma Conta do Ledger no Midaz.
- Listar Alias Accounts — Visualizar todas as Alias Accounts com paginação e filtros.
- Consultar uma Alias Account — Obter os detalhes de uma Alias Account específica.
- Atualizar uma Alias Account — Editar os detalhes de uma Alias Account existente.
- Excluir uma Alias Account — Excluir logicamente ou remover permanentemente uma Alias Account.
Todas as requisições à API do CRM requerem o header
X-Organization-Id. O ID do Holder faz parte do caminho da URL para a maioria das operações de Alias Account. Se o Access Manager estiver habilitado, um header Authorization com um token Bearer também é necessário.Via Lerian Console
Você pode gerenciar Alias Accounts através da página Alias Accounts no Módulo Midaz do 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.Próximos passos
Holders
Saiba mais sobre a entidade Holder à qual as Alias Accounts estão vinculadas.
Boas práticas
Revise as boas práticas operacionais e de gerenciamento de dados para o CRM.