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.
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.
Uma Alias Account deve estar sempre vinculada a um Holder existente. Crie o Holder primeiro e depois crie a Alias Account. Consulte Usando o CRM para o fluxo de integração correto. 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 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 objeto regulatoryFields 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
O array relatedParties define indivíduos ou entidades relacionados à Alias Account com papéis específicos. Cada entrada contém:
| 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. |
| name | string | Sim | Nome completo da parte relacionada. |
| 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. |
Partes relacionadas podem ser adicionadas ao criar ou atualizar uma Alias Account. Para remover uma parte relacionada específica, use o endpoint dedicado Excluir Parte Relacionada. 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.
Nunca armazene informações sensíveis no objeto metadata. Os metadados não são criptografados e são armazenados em texto simples.
Gerenciando Alias Accounts
Via API
Use a API do CRM para gerenciar Alias Accounts programaticamente:
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
