> ## 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 Ledgers para rastrear as Transações e Operações de cada Organização e orquestrar transferências entre ledgers pela Conta Externa de cada Ledger.

Um **Ledger** mantém um registro preciso de todas as Transações e Operações de uma Organização. Um Ledger rastreia cada evento financeiro: depósitos, saques, transferências e tarifas.

As Organizações podem usar vários Ledgers para segregar operações financeiras. Por exemplo, um banco mantém Ledgers separados para diferentes linhas de negócio, regiões ou exigências regulatórias. Um único Ledger também pode lidar com todas as operações, para uma configuração mais simples.

## Estrutura do Ledger

***

* **Ledger > Organização:** Cada Organização pode ter vários Ledgers, mas cada Ledger pertence a apenas uma Organização.
  * Use vários Ledgers apenas quando você precisar segregar dados ou operações, por exemplo operações internas de tesouraria versus contas de clientes.

> [!WARNING]
>
> Por padrão, uma transação **não pode** mover fundos entre Ledgers. Uma transação pode abranger vários Ledgers apenas quando cada Ledger envolvido habilita a configuração `crossLedger.enabled`.

### Como orquestrar transações entre Ledgers

Quando cada Ledger envolvido habilita `crossLedger.enabled`, envie uma transação `direct` ou `hold` pela API v2. Cada perna informa o `organizationId` e o `ledgerId` da sua conta. O Midaz divide a transferência em uma transação balanceada por Ledger:

1. **Débito do Ledger de origem:** A conta no Ledger 1 envia o valor para a Conta Externa do Ledger 1 (`@external/<asset>`).
2. **Crédito no Ledger de destino:** A Conta Externa do Ledger 2 envia o valor para a conta de destino.

As transações compartilham um único `groupId`. Em uma transação `direct`, elas são concluídas ou falham juntas.

## Características principais

***

* Todas as Contas e Transações existem dentro de um Ledger.
* Cada Ledger mantém um conjunto equilibrado de Contas.
* Você pode usar vários Ledgers para segmentação, mas transações entre ledgers precisam de tratamento explícito.

## Vários Ledgers

***

O Midaz permite criar vários Ledgers para cada organização. Por exemplo, uma empresa pode separar os registros financeiros por país, departamento ou função de negócio.

### Exemplo de caso de uso

Considere uma empresa global com negócios em várias regiões:

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

Com Ledgers separados, a empresa mantém registros de transação, regras fiscais e configurações de moeda específicos de cada região. Ainda assim, ela tem uma supervisão unificada de todas as operações.

### Quando criar um novo Ledger

Um Ledger é um limite rígido. Todo movimento entre Ledgers passa pela Conta Externa de cada Ledger (veja [Como orquestrar transações entre Ledgers](#how-to-orchestrate-cross-ledger-transactions)). Esse custo orienta a decisão. Crie um novo Ledger apenas quando os segmentos raramente movimentam dinheiro entre si.

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

| Mecanismo | O que ele separa | Use quando |
| - | - | - |
| **Ledger** | Um conjunto completo e independente de livros, com suas próprias contas, saldos e configuração de ativos | Você precisa de isolamento real: uma entidade legal, país ou regime regulatório separado, em que os saldos nunca devem se misturar e os movimentos entre segmentos são raros. |
| **[Portfólio](https://docs.lerian.studio/pt/products/midaz/portfolios.md)** | 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 ainda transacionam livremente com o resto do Ledger. |
| **[Conta](https://docs.lerian.studio/pt/products/midaz/accounts.md) / [Tipo de Conta](https://docs.lerian.studio/pt/products/midaz/account-types.md)** | Um saldo individual e suas regras | Um único saldo precisa do seu próprio extrato, natureza ou restrições. |

Se dois conjuntos de saldos transacionam entre si com frequência, mantenha-os no **mesmo** Ledger. Separe-os com Portfólios ou Contas. Divida em vários Ledgers apenas quando o isolamento valer a sobrecarga de orquestração.

## Personalizando Ledgers

***

No Midaz, você pode adaptar a configuração de cada Ledger às suas necessidades. Os Ativos são vinculados a um Ledger, então o mesmo código é um registro independente em cada Ledger, com seu próprio nome, tipo, status e metadados.

**Exemplo** Para representar o Bitcoin (BTC) em vários Ledgers, crie o ativo BTC de forma independente em cada Ledger e defina o nome, o status e os metadados que cada Ledger precisa.

> [!NOTE]
>
> Os valores no Midaz são decimais de precisão arbitrária. Não existe uma configuração de casas decimais por ativo ou por Ledger. Você não configura uma escala ao criar um ativo.

## Benefícios de usar Ledgers no Midaz

***

* **Organização clara**: mantenha registros financeiros claros e distintos para cada parte do seu negócio.
* **Configurações personalizadas**: ajuste as configurações de ativos, moedas ou outros parâmetros por Ledger, para necessidades locais ou departamentais.
* **Escalabilidade**: adicione ou altere Ledgers conforme sua organização cresce ou se diversifica.
* **Transparência**: tenha uma visão completa de todas as atividades financeiras. Cada Ledger contribui para uma única visão operacional.

## Configurações do Ledger

***

Cada Ledger tem configurações ajustáveis que controlam como ele valida transações. Por exemplo, você pode exigir que toda transação siga uma rota predefinida. Você também pode exigir que os tipos de conta correspondam às regras do seu negócio. O Ledger então rejeita movimentos inválidos antes de registrá-los.

Você pode alterar essas configurações a qualquer momento pela API. Você não precisa reiniciar o serviço nem alterar código.

### Configurações disponíveis

| Configuração | Padrão | Descrição |
| - | - | - |
| `accounting.validateAccountType` | `false` | Quando habilitado, cada nova conta deve usar um tipo de conta registrado para o Ledger. O Ledger rejeita a criação da conta se o tipo não estiver registrado. |
| `accounting.validateRoutes` | `false` | Quando habilitado, toda transação deve incluir uma rota de transação associada. Cada operação também é validada de acordo com as regras da sua rota de operação. |
| `accounting.requireHolder` | `false` | Quando habilitado, cada conta que você cria pela API v2 deve informar um titular existente. |
| `overrides.allowFeeSkip` | `false` | Quando habilitado, uma requisição de transação pode definir `skip.fees` como `true` para ser lançada sem o cálculo de tarifas. Se a configuração estiver desabilitada, o Midaz recusa essa requisição com o erro `0490`. |
| `overrides.allowTracerSkip` | `false` | Quando habilitado, uma requisição de transação pode definir `skip.tracer` como `true` para pular a chamada ao Tracer. Se a configuração estiver desabilitada, o Midaz recusa essa requisição com o erro `0490`. |
| `overrides.allowHolderSkip` | `false` | Quando habilitado, uma requisição de criação de conta pode pular a verificação do titular. |
| `tracer.mode`, `tracer.failPosture`, `tracer.timeoutMs` | `off`, `open`, `250` | Controlam como o Ledger chama o Tracer. Veja o [guia de integração do Tracer](https://docs.lerian.studio/pt/products/tracer/integration-guide.md#midaz-ledger-reservation-seam). |
| `crossLedger.enabled` | `false` | Quando habilitado, o Ledger pode participar de uma transação que abrange vários Ledgers. |

> [!TIP]
>
> Comece com `validateAccountType` e `validateRoutes` desabilitadas enquanto você configura suas rotas de operação e rotas de transação. Depois que a configuração de rotas estiver completa, habilite a validação para impor as regras do seu negócio.

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

Quando você habilita `validateRoutes` para um Ledger:

1. Toda transação para esse Ledger **deve** referenciar uma rota de transação válida.
2. O Ledger valida cada operação de acordo com as regras da rota de operação correspondente.
3. O Ledger rejeita qualquer transação não conforme antes de registrar o movimento.

Quando você habilita `validateAccountType`:

1. O Ledger verifica cada nova conta de acordo com seus tipos de conta registrados.
2. Se o tipo de conta não estiver registrado, o Ledger rejeita a criação da conta.

> [!WARNING]
>
> Se você habilitar a validação em um Ledger que já processa transações, os registros existentes não mudam. A validação se aplica às requisições que você enviar depois de habilitar a configuração. Isso inclui um commit, cancelamento ou estorno de uma transação anterior.

### Gerenciando configurações pela API

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

* [Buscar Configurações do Ledger](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-ledger-settings.md): veja as configurações atuais de um Ledger.
* [Atualizar Configurações do Ledger](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-ledger-settings.md): altere uma ou mais configurações com uma atualização parcial (deep merge).

> [!NOTE]
>
> O Midaz aplica as mudanças com um deep merge e modifica apenas os campos que você incluir na requisição.

## Gerenciando Ledgers

***

Você pode gerenciar seus Ledgers pela API ou pelo Lerian Console.

### Ver API

* [Listar Ledgers](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-ledgers.md) - Veja os detalhes de todos os Ledgers.
* [Buscar um Ledger](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-ledger-by-id.md) - Obtenha os detalhes de um Ledger específico.
* [Criar um Ledger](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-ledger.md) - Registre um novo Ledger.
* [Atualizar um Ledger](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-ledger.md) - Edite os detalhes de um Ledger existente.
* [Excluir um Ledger](https://docs.lerian.studio/pt/reference/products/midaz/v2/delete-ledger.md) - Marque um Ledger como excluído.

> [!NOTE]
>
> Quando você exclui um Ledger, o Midaz não o remove permanentemente.
>
> Em vez disso, o Midaz define um timestamp `deletedAt`. O Midaz então exclui o Ledger de toda leitura, e você não pode mais usá-lo. Seu `status.code` não muda. Isso preserva os dados históricos para trilhas de auditoria. O Midaz rejeita a exclusão de Ledger em um ambiente de produção.

### Via Lerian Console

Você pode ver, criar, editar e excluir Ledgers na página Ledgers do Módulo Midaz do Lerian Console.

[**Saiba mais no guia Gerenciando Ledgers.**](https://docs.lerian.studio/pt/products/midaz/console/managing-ledgers-via-console)

> [!TIP]
>
> Se você criar seu primeiro Ledger no Lerian Console, você faz isso como parte do fluxo de onboarding. Para saber mais, veja o guia [Onboarding do Módulo Midaz](https://docs.lerian.studio/pt/products/midaz/console/midaz-console-onboarding.md).


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