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

# Ledgers

> Use os Ledgers como espinha dorsal financeira da sua Organização, rastreando cada Transação com rastreabilidade e segregação completas.

Um **Ledger** atua como a espinha dorsal financeira da Organização, mantendo um registro preciso de todas as Transações e Operações. Cada evento financeiro — depósitos, saques, transferências, taxas — é rastreado dentro de um Ledger, garantindo rastreabilidade e controle completos.

As Organizações podem usar **múltiplos Ledgers** para segregar operações financeiras. Por exemplo, um banco pode manter Ledgers separados para diferentes linhas de negócio, regiões geográficas ou requisitos regulatórios. Alternativamente, um único Ledger pode gerenciar todas as operações para uma abordagem simplificada.

## Estrutura do Ledger

***

* **Ledger > Organização:** Cada Organização pode possuir múltiplos Ledgers, mas cada Ledger pertence a apenas uma Organização. Isso garante separação financeira e responsabilidade.
  * **Múltiplos Ledgers devem ser usados apenas quando a segregação de dados ou operações é necessária** — por exemplo, para operações de tesouraria interna versus contas de clientes.

<Warning>
  Transações **não podem** ocorrer diretamente entre Ledgers sem orquestração. Se você precisa gerenciar transações entre Ledgers, deve implementar fluxos de trabalho apropriados para garantir consistência.
</Warning>

### Como orquestrar transações entre Ledgers

Para mover fundos entre dois Ledgers, você precisará criar um fluxo de trabalho orquestrado que divide a transferência em duas transações separadas:

1. **Débito do Ledger de origem:** Comece transferindo o valor desejado de uma conta no **Ledger 1** para uma **Conta Externa**. Essa conta atua como uma ponte e está sempre vinculada a um Ativo específico.
2. **Crédito no Ledger de destino:** Em seguida, crie uma segunda transação que move o mesmo valor da **Conta Externa** para a conta de destino no **Ledger 2**.

Esse processo em duas etapas garante que cada Ledger processe uma transação válida e independente, enquanto a Conta Externa mantém a consistência em todo o ecossistema.

<Note>
  **Nota**

  Você pode usar o [Flowker](/pt/flowker/what-is-flowker) para automatizar essa orquestração e incluir validações, condições e lógica de rollback conforme necessário.
</Note>

## Características principais

***

* Os Ledgers garantem integridade financeira e transparência operacional.
* Todas as Contas e Transações existem dentro de um Ledger, formando um sistema financeiro completo.
* Cada Ledger mantém um conjunto balanceado de Contas.
* Múltiplos Ledgers podem ser usados para segmentação, mas transações entre Ledgers requerem tratamento explícito.

## Múltiplos Ledgers

***

O Midaz oferece a capacidade de criar **múltiplos Ledgers** para cada organização, proporcionando flexibilidade e controle aprimorados. Esse recurso é particularmente benéfico para empresas com necessidades operacionais diversas, como separar registros financeiros por país, departamento ou função de negócio específica.

### Exemplo de caso de uso

Considere uma empresa global com negócios em múltiplas regiões:

* Ledger 1: Negócios nos EUA
* Ledger 2: Negócios na UE
* Ledger 3: Negócios na APAC

Usando Ledgers separados, a empresa pode manter registros de transações específicos por região, considerações fiscais e configurações de moeda, mantendo uma visão unificada de todas as operações.

### Quando criar um novo Ledger

Um Ledger é uma **fronteira rígida**, não apenas um rótulo. Contas em Ledgers diferentes não podem transacionar diretamente — toda movimentação entre Ledgers precisa ser orquestrada através de uma Conta Externa (veja [Como orquestrar transações entre Ledgers](#como-orquestrar-transações-entre-ledgers)). Esse custo é o fator decisivo: abra um novo Ledger apenas quando os segmentos raramente precisam mover dinheiro entre si.

Use esta heurística para escolher o nível certo de separação:

| Mecanismo                                                                  | O que separa                                                                                                 | Use quando                                                                                                                                                                          |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ledger**                                                                 | Um conjunto de livros completo e autossuficiente — com suas próprias contas, saldos e configuração de ativos | Você precisa de isolamento real: uma entidade jurídica, país ou regime regulatório separado, em que os saldos nunca devem se misturar e as movimentações entre segmentos são raras. |
| **[Portfolio](/pt/midaz/portfolios)**                                      | Um agrupamento de contas *dentro* de um Ledger                                                               | Você quer uma visão consolidada de um cliente ou unidade de negócio, mas as contas continuam transacionando livremente com o resto do Ledger.                                       |
| **[Conta](/pt/midaz/accounts) / [Tipo de Conta](/pt/midaz/account-types)** | Um saldo individual e suas regras                                                                            | Um único saldo precisa ter sua própria verdade — seu próprio extrato, natureza ou restrições.                                                                                       |

Em resumo: se dois conjuntos de saldos precisam transacionar entre si com frequência, mantenha-os no **mesmo** Ledger e separe-os com Portfolios ou Contas. Divida em múltiplos Ledgers apenas quando o isolamento compensar o overhead de orquestração.

## Customizando Ledgers

***

Uma das funcionalidades de destaque dos Ledgers no Midaz é a capacidade de personalizar configurações com base em requisitos individuais. Por exemplo, o mesmo ativo pode ser configurado de forma diferente em Ledgers separados:

**Exemplo** Para representar o Bitcoin (BTC) com configurações únicas em diferentes Ledgers:

* Ledger 1: BTC com 10 casas decimais.
* Ledger 2: BTC com 20 casas decimais.

Nesse caso, basta criar o ativo BTC de forma independente em cada Ledger, aplicando a configuração necessária.

Essa abordagem permite controle granular sobre o gerenciamento de ativos, alinhando-se a necessidades operacionais ou regulatórias específicas.

## Benefícios de usar Ledgers no Midaz

***

* **Organização aprimorada**: Mantenha registros financeiros claros e distintos, adaptados a diversos aspectos do seu negócio.
* **Configurações customizadas**: Ajuste configurações de ativos, moedas ou outros parâmetros por Ledger para atender necessidades locais ou departamentais.
* **Escalabilidade**: Adicione ou modifique Ledgers facilmente conforme sua organização cresce ou se diversifica.
* **Transparência**: Obtenha insights abrangentes sobre todas as atividades financeiras, com cada Ledger contribuindo para um panorama operacional coeso.

## Configurações do ledger

***

Cada Ledger possui configurações ajustáveis que controlam como as transações são validadas. Por exemplo, você pode exigir que cada transação siga uma rota predefinida, ou que os tipos de conta correspondam às suas regras de negócio — de modo que o ledger rejeite movimentações inválidas antes de serem registradas.

Essas configurações podem ser alteradas a qualquer momento pela API, sem necessidade de reiniciar o serviço ou fazer alterações no código.

### Configurações disponíveis

As seguintes configurações estão disponíveis:

| Configuração          | Valor padrão | Descrição                                                                                                                                                 |
| --------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validateAccountType` | `false`      | Quando habilitada, valida que os tipos de conta em cada operação correspondam às regras definidas nas rotas de operação associadas.                       |
| `validateRoutes`      | `false`      | Quando habilitada, cada transação deve incluir uma rota de transação associada. Cada operação também é validada contra as regras da sua rota de operação. |

<Tip>
  Comece com ambas as configurações desabilitadas enquanto você configura suas rotas de operação e rotas de transação. Quando sua configuração de roteamento estiver completa, habilite a validação para aplicar suas regras de negócio.
</Tip>

### Como as configurações afetam as transações

Quando `validateRoutes` está habilitada para um Ledger:

1. Cada transação submetida a esse Ledger **deve** referenciar uma rota de transação válida.
2. Cada operação dentro da transação é validada contra as regras da rota de operação correspondente.
3. Transações que não estejam em conformidade são **rejeitadas antes do registro** — protegendo a integridade do seu ledger.

Quando `validateAccountType` está habilitada:

1. A conta de cada operação é verificada contra as regras de tipo de conta definidas na rota de operação.
2. Se o tipo de conta não corresponder à regra esperada, a transação é rejeitada.

<Warning>
  Habilitar a validação em um Ledger que já processa transações não afetará os registros existentes. A validação se aplica apenas a **novas transações** submetidas após a habilitação da configuração.
</Warning>

### Gerenciando configurações via API

Use os endpoints de Configurações do Ledger para recuperar e atualizar essas configurações:

* [Recuperar Configurações do Ledger](/pt/reference/midaz/retrieve-ledger-settings) — Visualize as configurações atuais de um Ledger.
* [Atualizar Configurações do Ledger](/pt/reference/midaz/update-ledger-settings) — Altere uma ou mais configurações usando uma atualização parcial (deep merge).

<Note>
  As atualizações de configurações entram em vigor imediatamente. As alterações são aplicadas por deep merge — apenas os campos incluídos na requisição são modificados.
</Note>

## Gerenciando Ledgers

***

Você pode gerenciar seus Ledgers via API ou através do Lerian Console.

### Via API

* [Listar Ledgers](/pt/reference/midaz/list-ledgers) - Visualize os detalhes de todos os Ledgers.
* [Recuperar um Ledger](/pt/reference/midaz/retrieve-a-ledger) - Obtenha detalhes de um Ledger específico.
* [Criar um Ledger](/pt/reference/midaz/create-a-ledger) - Registre um novo Ledger.
* [Atualizar um Ledger](/pt/reference/midaz/update-a-ledger) - Edite os detalhes de um Ledger existente.
* [Excluir um Ledger](/pt/reference/midaz/delete-a-ledger) - Marque um Ledger como excluído.

<Note>
  Quando você exclui um Ledger, ele não é permanentemente removido do sistema.

  Uma tag de exclusão com timestamp é adicionada, e o Ledger se torna inativo e inutilizável — ajudando a preservar dados históricos para trilhas de auditoria.
</Note>

### Via Lerian Console

Todas as ações de gerenciamento de Ledgers, incluindo visualização, criação, edição e exclusão, podem ser feitas através da página de Ledgers no Módulo Midaz do Lerian Console.

[**Saiba mais no guia de Gerenciamento de Ledgers.**](/pt/midaz/console/managing-ledgers-via-console)

<Tip>
  Se você está criando seu **primeiro Ledger** no Lerian Console, fará isso como parte do fluxo de onboarding. Para saber mais, confira o guia de [onboarding do Módulo Midaz](/pt/midaz/console/midaz-console-onboarding).
</Tip>