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 bloqueada, uma subconta de produto ou um saldo promocional. Cada saldo tem suas próprias regras, seu próprio extrato e suas próprias necessidades de conciliação. O atalho comum trata tudo como rótulos de uma única conta e resolve isso no código da aplicação. Isso funciona até saldos, ledgers, extratos ou regras operacionais precisarem divergir. Nesse ponto, 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 com várias contas Midaz. Ela mapeia cada parte do modelo para uma entidade nativa da plataforma. Depois percorre um exemplo: três contas para o mesmo documento de cliente.

Por que isso importa

Para times de produto e operações, cada saldo se torna sua própria conta. O Ledger aplica então cada regra de segregação — uma saída bloqueada, um gasto exclusivo de benefício, um saldo promocional com validade. A regra vive no Ledger, não 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, cada endereço externo resolve para uma conta específica antes de o Midaz lançar uma transação. Os números de core banking e os identificadores de trilho de pagamento apontam cada um para um saldo. Você nunca adivinha a qual saldo um evento de entrada pertence. 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. Ela resolve cada identificador para a conta correta antes da chamada ao Midaz. O Midaz continua sendo a fonte de verdade para contas, saldos e lançamentos.

Um cliente, várias contas — arquitetura de referência — Arquitetura de referência: um cliente, várias contas.

Quando o saldo, o ledger, o extrato ou a regra operacional difere por destino, aponte cada identificador para uma conta distinta. Um identificador externo não é apenas um apelido de um saldo compartilhado.

Como o Midaz mapeia o modelo

Cada parte dessa arquitetura mapeia para uma entidade nativa do Midaz. Você não constrói um repositório de saldos separado nem inventa 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	Instrument (CRM)	Anexa agência, número da conta e campos regulatórios. Vincula 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. O entityId armazena o identificador do seu sistema externo. O trabalho do middleware é estreito — 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)	Parte do binário do ledger — use-o para anexar contexto de identidade, bancário e regulatório

O Midaz representa os valores 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. A conta principal é livre para movimentação ordinária. A conta benefício segue regras de produto. A conta bloqueada 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 sob regras de produto) e restricted_account. A restricted_account é a conta bloqueada: aceita entradas mas condiciona ou bloqueia as saídas.

Crie as três contas

Cada conta se vincula ao asset BRL e declara seu type. Ela 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 e type benefit_account. Crie a conta bloqueada com alias @cust_12345678900_blocked, entityId 0002/77777-0 e 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 é dono das três contas e mantém a identidade em um só lugar.

No Midaz v4, o CRM faz parte do binário do ledger, portanto não precisa de um serviço nem de uma porta separada. O ID de organização viaja na rota da URL — veja Primeiros passos com o CRM para o schema completo.

curl -X POST http://localhost:3002/v2/organizations/{org_id}/holders \
  -H "Content-Type: application/json" \
  -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 um Instrument por conta do ledger para anexar contexto bancário e regulatório. O Instrument permanece dentro do binário Ledger unificado, mas mantém os detalhes voltados ao cliente fora do modelo transacional de contas e saldos.

curl -X POST http://localhost:3002/v2/organizations/{org_id}/holders/{holder_id}/instruments \
  -H "Content-Type: application/json" \
  -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. Esse endereço externo agora resolve para uma conta específica. Repita para as contas benefício e bloqueada, e aponte o accountId para cada uma.

O resultado: um cliente, três contas, três endereços externos distintos. Cada conta mantém seu próprio saldo, extrato e regras sob 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 da chamada ao Midaz. Cada camada se mantém no seu papel, e isso preserva a clareza contábil.

Evento externo

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

O middleware resolve o identificador

O middleware busca o identificador externo e o resolve para o alias de conta Midaz correto. Ele também aplica validação de status (ativo, bloqueado, encerrado).

O Midaz lança na conta certa

O Midaz registra o lançamento na conta resolvida e preserva 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 da chamada ao Midaz. 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. Você não pode gastar um saldo bloqueado 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 um Instrument 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 Instruments

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

Midaz Core

CRM

Fees

Midaz para clientes com várias contas

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 Instruments

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

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