> ## 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. # Midaz para clientes com várias contas > Modele múltiplas contas Midaz sob um único cliente — com saldos, ledgers, extratos e identificadores externos segregados por conta. Um único cliente raramente tem um único saldo. A mesma pessoa pode ter uma conta principal, uma conta benefício, uma conta judicial ou bloqueada, uma subconta de produto ou um saldo promocional — cada um com suas próprias regras, seu próprio extrato e suas próprias necessidades de conciliação. O atalho comum é tratar tudo como rótulos de uma única conta e resolver isso no código da aplicação. Isso funciona até o dia em que saldos, ledgers, extratos ou regras operacionais precisam divergir — e aí uma única conta não consegue mais dizer a verdade sobre onde o dinheiro está. Esta página mostra a arquitetura de referência para **um cliente sendo dono de várias contas Midaz**, como as entidades nativas da plataforma mapeiam esse modelo, e um exemplo passo a passo de como criar três contas para o mesmo documento de cliente. ## Por que isso importa *** Para **times de produto e operações**, modelar cada saldo como sua própria conta significa que cada regra de segregação — uma saída bloqueada, um gasto exclusivo de benefício, um saldo promocional com validade — é aplicada pelo Ledger, e não enterrada na lógica da aplicação. Cada conta carrega seu próprio extrato e sua própria trilha de conciliação. Para **times de engenharia**, os endereços externos do cliente (números de core banking, identificadores de trilho de pagamento) resolvem para uma conta específica antes de a transação ser lançada. Não há adivinhação sobre a qual saldo um evento de entrada pertence, e não há um repositório de saldos separado para manter sincronizado com o Ledger. | Uma conta com rótulos | Várias contas por cliente | | --------------------------------------------------------- | ---------------------------------------------------------------- | | "Tipos" de saldo vivem em metadata ou no código da app | Cada saldo é sua própria Conta, com seu próprio ledger e extrato | | Bloquear ou restringir fundos exige lógica customizada | Regras de Tipo de Conta e de rota aplicam restrições no Ledger | | Extratos precisam ser filtrados e remontados por saldo | Cada conta produz um extrato limpo e independente | | Identificadores externos apontam todos para o mesmo saldo | Cada identificador externo resolve para uma conta específica | | A conciliação mistura movimentações sem relação entre si | A conciliação fica separada por conta, por design | ## A arquitetura de referência *** O modelo é **um dono, N contas, N identificadores externos**: * **Um dono** — o cliente, identificado por um documento (CPF, CNPJ, tax ID). O dono representa *quem* detém o relacionamento. Ele não carrega saldo e não decide o roteamento transacional. * **N contas** — cada conta é uma posição contábil autossuficiente, com seu próprio saldo, ledger, extrato e regras. * **N identificadores externos** — os endereços que outros sistemas (uma plataforma de core banking, um trilho de pagamento) usam para alcançar uma conta específica. Cada identificador resolve para exatamente uma conta. Uma camada de middleware mantém o mapa entre identificadores externos e contas, e resolve cada identificador para a conta correta *antes* de chamar o Midaz. O Midaz continua sendo a fonte de verdade para contas, saldos e lançamentos. Um cliente, várias contas — arquitetura de referência Cada identificador externo **não** é apenas um apelido de um saldo compartilhado. Quando saldo, ledger, extrato ou regra operacional difere por destino, cada identificador precisa apontar para uma conta distinta. ## Como o Midaz mapeia o modelo *** Cada parte dessa arquitetura mapeia para uma entidade nativa do Midaz — você não precisa construir um repositório de saldos separado nem inventar uma camada contábil. | Conceito | Entidade Midaz | O que faz | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | O dono (cliente) | [**Holder**](/pt/midaz/crm/holders) | Identidade por trás das contas (`NATURAL_PERSON` ou `LEGAL_PERSON`), indexada por `document`. Não carrega saldo. | | Cada posição de saldo | [**Conta**](/pt/midaz/accounts) | Fonte de verdade para saldo, lançamentos e extrato. | | A natureza de cada saldo | [**Tipo de Conta**](/pt/midaz/account-types) | Classifica uma conta (principal, benefício, bloqueada) e habilita a validação de rota. | | Todas as contas de um cliente | [**Portfolio**](/pt/midaz/portfolios) | Agrupa as contas de um cliente para ver o relacionamento total. | | Endereço externo → conta | [**Alias de conta**](/pt/midaz/accounts#account-aliases) + [**`entityId`**](/pt/midaz/accounts#entity-id-external-system-reference) | O alias é como as transações endereçam uma conta; o `entityId` a vincula ao identificador de um sistema externo. | | Contexto bancário e regulatório | [**Alias Account (CRM)**](/pt/midaz/crm/alias-accounts) | Anexa agência, número da conta e campos regulatórios, vinculando um Holder a uma conta específica. | Boa parte do que um "alias registry" externo faria já é nativo: o **alias** da conta é o endereço dentro do Ledger, e o **`entityId`** armazena o identificador do seu sistema externo. O trabalho do middleware é mais estreito do que parece à primeira vista — traduzir um identificador de trilho externo para o alias de conta correto e, então, lançar. ## Pré-requisitos *** Este exemplo assume um ambiente Midaz em execução com o seguinte já configurado: | Requisito | Detalhes | | ------------------------------ | --------------------------------------------------------------------------------------- | | **Midaz** (v3.x.x+) | Ledger central com uma Organization e um Ledger já criados | | **Um asset registrado** | `BRL` registrado como o asset operacional no Ledger | | **Validação de Tipo de Conta** | Habilitada por Ledger, para que a natureza de cada conta seja aplicada (veja o Passo 1) | | **CRM** (opcional) | Em execução, caso você queira anexar contexto de identidade, bancário e regulatório | Valores no Midaz são representados na menor unidade da moeda. Para BRL, `15000` significa R\$ 150,00 (centavos). ## Criando três contas para um cliente *** O cliente com documento `12345678900` precisa de três contas: uma conta **principal** para movimentação ordinária, uma conta **benefício** governada por regras de produto, e uma conta **bloqueada** que aceita entradas mas restringe saídas. Ative a validação para que toda conta precise declarar um tipo registrado. É isso que permite ao Ledger aplicar a natureza de cada conta. ```json theme={null} PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings { "accounting": { "validateAccountType": true } } ``` As configurações entram em vigor imediatamente — sem necessidade de redeploy. Crie um Tipo de Conta por natureza de saldo. O `keyValue` é o valor com o qual o campo `type` de cada conta precisa corresponder. ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/account-types { "name": "Main Account", "description": "Ordinary account, free for regular movement", "keyValue": "main_account" } ``` Repita para `benefit_account` ("Movimentação governada por regras de produto") e `restricted_account` — a conta **bloqueada**, onde entradas são permitidas mas saídas são condicionadas ou bloqueadas. Cada conta é vinculada ao asset `BRL`, declara seu `type` e carrega um `alias` (seu endereço dentro do Ledger) e um `entityId` (seu identificador no seu sistema externo). ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/accounts { "name": "Main account — 12345678900", "assetCode": "BRL", "alias": "@cust_12345678900_main", "entityId": "0001/12345-1", "type": "main_account" } ``` Crie a conta benefício com `alias` `@cust_12345678900_benefit`, `entityId` `0001/88888-2`, `type` `benefit_account`; e a conta bloqueada com `alias` `@cust_12345678900_blocked`, `entityId` `0002/77777-0`, `type` `restricted_account`. O `entityId` é onde você armazena o endereço externo que outros sistemas usam para alcançar esta conta — o seu mapa entre o Midaz e o seu sistema de origem. Crie um Holder para o cliente. O mesmo Holder será dono das três contas, mantendo a identidade centralizada. O CRM roda como um serviço separado, e toda requisição exige o header `X-Organization-Id`. Veja [Primeiros passos com o CRM](/pt/midaz/crm/crm-getting-started) para a configuração do serviço e o schema completo. ```bash theme={null} curl -X POST http://localhost:4003/v1/holders \ -H "Content-Type: application/json" \ -H "X-Organization-Id: " \ -d '{ "type": "NATURAL_PERSON", "name": "Jane Smith", "document": "12345678900", "contact": { "primaryEmail": "jane.smith@example.com" } }' ``` Salve o `holderId` retornado — você vai usá-lo no próximo passo. Crie uma Alias Account por conta do ledger para anexar contexto bancário e regulatório. É isso que viabiliza as funcionalidades baseadas em CRM e mantém os detalhes voltados ao cliente separados do Ledger. ```bash theme={null} curl -X POST http://localhost:4003/v1/holders//aliases \ -H "Content-Type: application/json" \ -H "X-Organization-Id: " \ -d '{ "ledgerId": "", "accountId": "", "bankingDetails": { "branch": "0001", "account": "12345", "type": "CACC", "countryCode": "BR" }, "metadata": { "purpose": "main" } }' ``` Note como o `entityId` da conta principal (`0001/12345-1`) se decompõe na `branch` (`0001`) e na `account` (`12345`) que você registra aqui — é o endereço externo resolvendo para uma conta específica. Repita para as contas benefício e bloqueada, apontando o `accountId` para cada uma. O resultado: um cliente, três contas, três endereços externos distintos — cada um com seu próprio saldo, extrato e regras, todos pertencentes a um único Holder. | Dono | Identificador externo | Conta Midaz | Uso | Tratamento | | ------------- | --------------------- | ------------------- | -------------------- | -------------------------------------------------- | | `12345678900` | `0001/12345-1` | `@cust_..._main` | Conta principal | Livre para movimentação ordinária | | `12345678900` | `0001/88888-2` | `@cust_..._benefit` | Conta benefício | Movimentação governada por regras de produto | | `12345678900` | `0002/77777-0` | `@cust_..._blocked` | Judicial / bloqueada | Entrada permitida, saída condicionada ou bloqueada | ## A fronteira transacional *** Quando um evento externo chega, a resolução acontece *antes* de o Midaz ser chamado. Manter cada camada no seu papel é o que preserva a clareza contábil. Uma transação, consulta ou liquidação chega carregando um identificador externo. O middleware busca o identificador externo e o resolve para o alias de conta Midaz correto, aplicando validação de status (ativo, bloqueado, encerrado). O Midaz registra o lançamento na conta resolvida, preservando saldo e ledger. Extrato e conciliação permanecem separados por conta. | Camada | Responsabilidade | Não deve fazer | | ------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | **CRM / cadastro** | Manter a visão comercial e de identidade do cliente, incluindo o vínculo entre documento e relacionamento. | Roteamento transacional, decisões de conta destino ou regras de liquidação. | | **Middleware** | Resolver identificadores externos para uma conta Midaz antes da transação, e aplicar validação de status. | Inventar saldos, duplicar contabilidade ou depender do CRM em tempo real para o roteamento. | | **Midaz** | Registrar contas, saldos, lançamentos, ledgers e extratos como fonte de verdade financeira. | Conhecer detalhes do trilho externo além dos identificadores necessários para a integração. | Um identificador de uma conta bloqueada ou encerrada deve falhar na validação **antes** de o Midaz ser chamado. As decisões de roteamento pertencem ao middleware; o Ledger permanece a fonte de verdade para saldos e lançamentos. ## O que isso destrava *** * **Segregação real** — cada saldo tem seu próprio ledger e extrato, então um saldo bloqueado nunca pode ser gasto pela conta principal por acidente. * **Roteamento inequívoco** — todo evento externo tem uma única conta de destino bem definida. * **Identidade centralizada** — um único Holder é dono de várias contas; identidade e dados de contato vivem em um só lugar, enquanto os saldos permanecem separados. * **Nativo, não improvisado** — contas, tipos, aliases e `entityId` são primitivos da plataforma, então não há um repositório de saldos paralelo para conciliar contra o Ledger. ## O que você precisa para começar *** | Requisito | Detalhes | | ------------------------------ | ----------------------------------------------------------------------------------------------- | | **Midaz** (v3.x.x+) | Organization, Ledger e um asset registrado | | **Validação de Tipo de Conta** | Habilitada por Ledger via a [API de Configurações do Ledger](/pt/midaz/ledgers#ledger-settings) | | **Tipos de Conta** | Um por natureza de saldo (principal, benefício, bloqueada, …) | | **Contas** | Uma por saldo, cada uma com um `alias` e um `entityId` | | **CRM** (opcional) | Um Holder por cliente, mais uma Alias Account por conta do ledger | ## Próximos passos *** A unidade financeira central — aliases, `entityId` e contas externas. Classifique contas e aplique sua natureza com a validação de rota. Agrupe as contas de um cliente para ver o relacionamento total. Centralize a identidade e anexe contexto bancário e regulatório.