Midaz para clientes com várias contas

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	Identidade por trás das contas (`NATURAL_PERSON` ou `LEGAL_PERSON`), indexada por `document`. Não carrega saldo.
Cada posição de saldo	Conta	Fonte de verdade para saldo, lançamentos e extrato.
A natureza de cada saldo	Tipo de Conta	Classifica uma conta (principal, benefício, bloqueada) e habilita a validação de rota.
Todas as contas de um cliente	Portfolio	Agrupa as contas de um cliente para ver o relacionamento total.
Endereço externo → conta	Alias de conta + `entityId`	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)	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.

Habilite a validação de Tipo de Conta

Ative a validação para que toda conta precise declarar um tipo registrado. É isso que permite ao Ledger aplicar a natureza de cada conta.

PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings

{
  "accounting": {
    "validateAccountType": true
  }
}

As configurações entram em vigor imediatamente — sem necessidade de redeploy.

Registre os Tipos de Conta

Crie um Tipo de Conta por natureza de saldo. O keyValue é o valor com o qual o campo type de cada conta precisa corresponder.

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.

Crie as três contas

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

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.

Registre o cliente como um Holder

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 para a configuração do serviço e o schema completo.

curl -X POST http://localhost:4003/v1/holders \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-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.

Vincule cada conta ao Holder

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.

curl -X POST http://localhost:4003/v1/holders/<holder-id>/aliases \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -d '{
    "ledgerId": "<your-ledger-id>",
    "accountId": "<main-account-id>",
    "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.

Evento externo

Uma transação, consulta ou liquidação chega carregando um identificador externo.

O middleware resolve o identificador

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 lança na conta certa

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

Contas

A unidade financeira central — aliases, entityId e contas externas.

Tipos de Conta

Classifique contas e aplique sua natureza com a validação de rota.

Portfolios

Agrupe as contas de um cliente para ver o relacionamento total.

CRM: Holders e Alias Accounts

Centralize a identidade e anexe contexto bancário e regulatório.

​Por que isso importa

​A arquitetura de referência

​Como o Midaz mapeia o modelo

​Pré-requisitos

​Criando três contas para um cliente

​A fronteira transacional

​O que isso destrava

​O que você precisa para começar

​Próximos passos

Contas

Tipos de Conta

Portfolios

CRM: Holders e Alias Accounts

Por que isso importa

A arquitetura de referência

Como o Midaz mapeia o modelo

Pré-requisitos

Criando três contas para um cliente

A fronteira transacional

O que isso destrava

O que você precisa para começar

Próximos passos