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 de 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 isso como rótulos em uma única conta e resolve tudo no código da aplicação. Isso funciona até que saldos, ledgers, extratos ou regras operacionais precisem divergir. Nesse ponto, uma única conta não consegue mais dizer a verdade sobre onde está o dinheiro. Esta página mostra a arquitetura de referência para um cliente com várias contas do 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 equipes de produto e operações, cada saldo se torna sua própria conta. O Ledger então aplica cada regra de segregação: uma saída bloqueada, um gasto restrito a 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 equipes de engenharia, cada endereço externo se resolve em uma conta específica antes de o Midaz registrar uma transação. Números de core banking e identificadores de trilhos de pagamento apontam cada um para um saldo. Você nunca precisa adivinhar a qual saldo um evento recebido pertence. Não existe um repositório de saldo separado para manter sincronizado com o Ledger.

Uma conta com rótulos	Várias contas por cliente
”Tipos” de saldo vivem em metadados ou no código da aplicação	Cada saldo é sua própria Conta, com seu próprio ledger e extrato
Bloquear ou restringir fundos exige lógica personalizada	O Tipo de Conta e as regras de rota aplicam restrições no Ledger
Extratos devem ser filtrados e remontados por saldo	Cada conta produz um extrato limpo e independente
Identificadores externos todos apontam para o mesmo saldo	Cada identificador externo se resolve em uma conta específica
A conciliação mistura movimentações não relacionadas	A conciliação é separada por conta, de forma intencional

A arquitetura de referência

O modelo é um titular, N contas, N identificadores externos:

Um titular: o cliente, identificado por um documento (CPF, CNPJ, identificação fiscal). O titular representa quem detém o relacionamento. Ele não carrega saldo nem decide o roteamento da transação.
N contas: cada conta é uma posição contábil autocontida, 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 se resolve em 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 da 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 diferem por destino, aponte cada identificador para uma conta distinta. Um identificador externo não é apenas um apelido para 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 saldo separado nem inventa uma camada contábil.

Conceito	Entidade do Midaz	O que faz
O titular (cliente)	Titular	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 da 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	Portfólio	Agrupa as contas de um cliente para visualizar o relacionamento total.
Endereço externo → conta	Alias da 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	Instrumento (CRM)	Anexa agência, número de conta e campos regulatórios. Vincula um Titular a uma conta específica.

Boa parte do que um “registro de aliases” externo faria já é nativo. O alias da conta é o endereço dentro do Ledger. O entityId guarda 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 registrar.

Pré-requisitos

Este exemplo pressupõe um ambiente Midaz em funcionamento com o seguinte já configurado:

Requisito	Detalhes
Midaz (v3.x.x+)	Core Ledger com uma Organização e um Ledger já criados
Um ativo registrado	`BRL` registrado como o ativo operacional no Ledger
Validação de Tipo de Conta	Habilitada por Ledger para que a natureza de cada conta seja aplicada (veja a Etapa 1)
CRM (opcional)	Parte do binário do ledger — use-o para anexar contexto de identidade, bancário e regulatório

O Midaz representa valores na menor unidade da moeda. Para BRL, 15000 significa R$ 150,00 (centavos).

Construindo três contas para um cliente

O cliente com o documento 12345678900 precisa de três contas. A conta principal é livre para movimentação comum. A conta de 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 declare um tipo registrado. Isso é o que permite que o Ledger aplique a natureza de cada conta.

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

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

As configurações valem imediatamente. Você não precisa fazer um novo deploy.

Registre os Tipos de Conta

Crie um Tipo de Conta para cada natureza de saldo. O keyValue é o que o campo type de cada conta deve 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: ela aceita entradas, mas condiciona ou bloqueia saídas.

Crie as três contas

Cada conta se vincula ao ativo 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 de 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ê guarda o endereço externo que outros sistemas usam para alcançar essa conta. É o seu mapa entre o Midaz e o seu sistema de origem.

Registre o cliente como um Titular

Crie um Titular para o cliente. O mesmo Titular é dono das três contas e mantém a identidade em um só lugar.

No Midaz v4, o CRM é parte do binário do ledger, então não precisa de um serviço ou porta separados. O ID da organização viaja no caminho da URL. Veja Primeiros passos com o CRM para o esquema 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 na próxima etapa.

Vincule cada conta ao Titular

Crie um Instrumento para cada conta do ledger para anexar contexto bancário e regulatório. O Instrumento permanece dentro do binário unificado do Ledger, mas mantém os detalhes voltados ao cliente fora do modelo transacional de conta e saldo.

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"
    }
  }'

Veja 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 se resolve em uma conta específica. Repita para as contas de benefício e bloqueada, e aponte o accountId para cada uma.

Agora você tem um cliente, três contas e três endereços externos distintos. Cada conta mantém seu próprio saldo, extrato e regras sob um único Titular.

Titular	Identificador externo	Conta do Midaz	Uso	Tratamento
`12345678900`	`0001/12345-1`	`@cust_..._main`	Conta principal	Livre para movimentação comum
`12345678900`	`0001/88888-2`	`@cust_..._benefit`	Conta de benefício	Movimentação regida por regras de produto
`12345678900`	`0002/77777-0`	`@cust_..._blocked`	Por ordem judicial / bloqueada	Entrada permitida, saída condicionada ou bloqueada

O limite da transação

Quando um evento externo chega, a resolução acontece antes da chamada ao Midaz. Cada camada permanece em sua função, o que 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 correto do Midaz. Ele também aplica a validação de status (ativa, bloqueada, encerrada).

O Midaz registra na conta certa

O Midaz registra o lançamento na conta resolvida e preserva o saldo e o ledger. Extrato e conciliação permanecem separados por conta.

Camada	Responsabilidade	Não deve fazer
CRM / cadastro	Guardar a visão comercial e de identidade do cliente, incluindo o vínculo entre documento e relacionamento.	Roteamento de transação, decisões de destino ou regras de liquidação.
Middleware	Resolver identificadores externos para uma conta do Midaz antes da transação, e aplicar a validação de status.	Inventar saldos, duplicar contabilidade ou depender do CRM em tempo real para roteamento.
Midaz	Registrar contas, saldos, lançamentos, ledgers e extratos como a fonte da verdade financeira.	Conhecer detalhes do trilho externo além dos identificadores necessários para a integração.

Um identificador de conta bloqueada ou encerrada deve falhar a validação antes da chamada ao Midaz. As decisões de roteamento pertencem ao middleware. O Ledger continua sendo a fonte da verdade para saldos e lançamentos.

O que isso viabiliza

Segregação real: cada saldo tem seu próprio ledger e extrato. Você não consegue 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 Titular é dono de várias contas. Os dados de identidade e contato vivem em um só lugar, enquanto os saldos permanecem separados.
Nativo, não construído por fora: contas, tipos, aliases e entityId são primitivas da plataforma, então não existe um repositório de saldo paralelo para conciliar com o Ledger.

O que você precisa para começar

Requisito	Detalhes
Midaz (v3.x.x+)	Organização, Ledger e um ativo registrado
Validação de Tipo de Conta	Habilitada por Ledger pela 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 Titular por cliente, mais um Instrumento por conta do ledger

Próximos passos

Contas

A unidade financeira principal: aliases, entityId e contas externas.

Tipos de Conta

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

Portfólios

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

CRM: Titulares e Instrumentos

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

Construindo três contas para um cliente

O limite da transação

O que isso viabiliza

O que você precisa para começar

Próximos passos

Contas

Tipos de Conta

Portfólios

CRM: Titulares e Instrumentos

​Por que isso importa

​A arquitetura de referência

​Como o Midaz mapeia o modelo

​Pré-requisitos

​Construindo três contas para um cliente

​O limite da transação

​O que isso viabiliza

​O que você precisa para começar

​Próximos passos

Contas

Tipos de Conta

Portfólios

CRM: Titulares e Instrumentos

Por que isso importa

A arquitetura de referência

Como o Midaz mapeia o modelo

Pré-requisitos

Construindo três contas para um cliente

O limite da transação

O que isso viabiliza

O que você precisa para começar

Próximos passos