> ## 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 várias contas do 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 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 mostrar 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.

## Cada saldo como sua própria conta

***

Para **equipes de produto e operações**, cada saldo se torna sua própria conta. O Ledger então aplica regras de segregação, como uma saída bloqueada ou um gasto restrito a benefício. 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](https://mintcdn.com/lerian-49cb71fc/vdBt8wfgjsNRO1rf/images/pt/d2/flowchart-multiaccounts.svg?fit=max\&auto=format\&n=vdBt8wfgjsNRO1rf\&q=85\&s=fdc96d76d7ce00c1406b760e14372eab)

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

> [!NOTE]
>
> Quando o saldo, o ledger, o extrato ou a regra operacional diferem por destino, aponte cada identificador para uma conta distinta. Não trate um identificador externo como 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**](https://docs.lerian.studio/pt/products/midaz/crm/holders.md) | Identidade por trás das contas (`NATURAL_PERSON` ou `LEGAL_PERSON`), indexada por `document`. É dono de cada conta pelo `holderId` dela. Não carrega saldo. |
| Cada posição de saldo | [**Conta**](https://docs.lerian.studio/pt/products/midaz/accounts.md) | Fonte da verdade para saldo, lançamentos e extrato. |
| A natureza de cada saldo | [**Tipo de Conta**](https://docs.lerian.studio/pt/products/midaz/account-types.md) | Classifica uma conta (principal, benefício, bloqueada) e habilita a validação de rota. |
| Todas as contas de um cliente | [**Portfólio**](https://docs.lerian.studio/pt/products/midaz/portfolios.md) | Agrupa as contas de um cliente para visualizar o relacionamento total. |
| Endereço externo → conta | [**Alias da conta**](https://docs.lerian.studio/pt/products/midaz/accounts.md#account-aliases) + [**`entityId`**](https://docs.lerian.studio/pt/products/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 | [**Instrumento (CRM)**](https://docs.lerian.studio/pt/products/midaz/crm/crm-getting-started.md) | Anexa agência, número de conta e campos regulatórios. Vincula um Titular a uma conta específica. |

> [!TIP]
>
> 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** (v4.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 novas contas usem um tipo registrado (veja a Etapa 1) |
| **CRM** | Parte do binário do ledger. Use-o para anexar contexto de identidade, bancário e regulatório |

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

**1. Habilite a validação de Tipo de Conta**

Ative a validação para que novas contas declarem um tipo registrado.

```json theme={null}
PATCH /v2/organizations/{org_id}/ledgers/{ledger_id}/settings

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

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

**2. 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.

```json theme={null}
POST /v2/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**. O tipo sozinho não restringe nada. Com a validação de rotas ativa, as rotas de transação podem condicionar as saídas dela. Para bloqueá-las, defina `allowSending` como `false` no saldo dela.

**3. 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.

> [!NOTE]
>
> 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](https://docs.lerian.studio/pt/products/midaz/crm/crm-getting-started.md) para o esquema completo.

```bash theme={null}
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 `id` retornado. Ele é o `holderId` das próximas etapas.

**4. 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). O `holderId` torna o Titular o dono da conta. Você não pode alterar o dono depois.

```json theme={null}
POST /v2/organizations/{org_id}/ledgers/{ledger_id}/accounts

{
  "name": "Main account - 12345678900",
  "assetCode": "BRL",
  "alias": "@cust_12345678900_main",
  "entityId": "0001/12345-1",
  "holderId": "<holder-id>",
  "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`. Use o mesmo `holderId` nas duas.

> [!TIP]
>
> 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.

**5. 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.

```bash theme={null}
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"
    }
  }'
```

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.

**1. Evento externo**

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

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

**3. 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. |

> [!TIP]
>
> 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.

## Resultados de várias contas por cliente

***

* **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**: 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** (v4.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](https://docs.lerian.studio/pt/products/midaz/ledgers.md#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** | Um Titular por cliente, mais um Instrumento opcional por conta do ledger |

## Próximos passos

***

> [card] [Contas](https://docs.lerian.studio/pt/products/midaz/accounts.md)
>
> A unidade financeira principal: aliases, `entityId` e contas externas.

> [card] [Tipos de Conta](https://docs.lerian.studio/pt/products/midaz/account-types.md)
>
> Classifique contas e aplique sua natureza com validação de rota.

> [card] [Portfólios](https://docs.lerian.studio/pt/products/midaz/portfolios.md)
>
> Agrupe as contas de um cliente para visualizar o relacionamento total.

> [card] [CRM: Titulares e Instrumentos](https://docs.lerian.studio/pt/products/midaz/crm/holders.md)
>
> Centralize a identidade e anexe contexto bancário e regulatório.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.