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

# Lançamentos contábeis

> Mapeie ações de transação e direções de rota para classificações contábeis e anote cada operação com o código e a descrição contábil dela.

Lançamentos contábeis (também conhecidos como **Rubricas**) mapeiam uma ação de transação e uma direção de rota para um `code` e uma `description` contábeis. Eles anotam uma operação depois da resolução da rota. As regras da Rota de Operação e as pernas da transação determinam as contas participantes.

## O que são Lançamentos contábeis

***

Uma **rubrica** mapeia uma ação de transação e uma direção de rota para uma classificação contábil. Em vez de calcular cada classificação à mão, você registra as rubricas uma vez. O Midaz então as resolve automaticamente enquanto processa as transações.

Cada rubrica carrega:

* **`code`**: um código contábil (por exemplo, `1.1.1.001`).
* **`description`**: um rótulo legível para o lançamento (por exemplo, `Customer checking — outbound`).

Quando o motor processa uma transação com a validação de rota (`accounting.validateRoutes`) habilitada e uma rubrica correspondente registrada, ele resolve a rubrica de cada operação. Ele grava o **`routeCode`** e o **`routeDescription`** resultantes na operação. Isso dá a você uma trilha de auditoria completa, da transação para a operação e para a rubrica. Seus times conseguem rastrear exatamente qual regra contábil se aplicou a cada movimentação.

> [!NOTE]
>
> Configure as rubricas por ação em cada Rota de Operação. Para as ações `direct` e `commit`, as rotas de **Origem** exigem a rubrica de **débito** e as rotas de **Destino** exigem a rubrica de **crédito**. Rubricas dedicadas de `block` e `unblock` são opcionais. Se estiverem ausentes, o Midaz resolve a rubrica `direct` para essas ações. As ações `hold` e `cancel` do lado da origem exigem **as duas** rubricas, e `overdraft` exige **as duas** em cada tipo de rota compatível. Rotas **Bidirecionais** sempre exigem **as duas**.

## Os 9 tipos de ação

***

Cada ação é um evento transacional distinto. As cinco primeiras ações cobrem o ciclo de vida da transação. As três seguintes cobrem movimentações de overdraft, block e unblock. A última cobre transações que abrangem vários Ledgers. Uma Rota de Operação pode mapear rubricas de débito e de crédito diferentes para cada ação. Cada etapa de uma operação então recebe a anotação contábil certa.

As linhas Hold e Cancel mostram um saldo com `direction: credit`. Em um saldo com `direction: debit`, um hold aumenta `available` e um cancelamento o diminui. `onHold` se move da mesma forma nos dois.

| Ação | Identificador | Descrição |
| :- | :- | :- |
| **Direct** | `direct` | Débito/crédito imediato, em uma única etapa, sem estágios intermediários (por exemplo, uma tarifa ou um ajuste). |
| **Hold** | `hold` | Reserva recursos criando uma movimentação pendente (move valor de `available` para `onHold` na conta de origem). |
| **Commit** | `commit` | Confirma um valor retido antes, liberando o valor em `onHold` para a conta de destino. |
| **Cancel** | `cancel` | Cancela/reverte um hold, devolvendo o valor em `onHold` ao saldo `available` na conta de origem. |
| **Revert** | `revert` | Reverte uma transação `APPROVED` criando uma contratransação que desfaz a original. |
| **Overdraft** | `overdraft` | Classifica movimentações de overdraft. A rubrica de **débito** marca o uso do overdraft (o déficit cresce) e a rubrica de **crédito** marca o pagamento (o déficit encolhe). As duas rubricas são obrigatórias quando esse lançamento está configurado. |
| **Block** | `block` | Classifica opcionalmente uma movimentação de bloqueio de recursos que congela valor em uma conta (por exemplo, um `asset-freeze`). |
| **Unblock** | `unblock` | Classifica opcionalmente a liberação de recursos bloqueados antes, de volta ao saldo `available`. |
| **Cross-ledger** | `crossLedger` | Classifica as pernas da Conta Externa que o Midaz adiciona quando uma transação abrange vários Ledgers. A rubrica de **débito** marca o valor que chega de outro Ledger. A rubrica de **crédito** marca o valor que sai para outro Ledger. As duas rubricas são obrigatórias. |

**Overdraft** classifica as operações acompanhantes que o motor gera automaticamente durante o uso e o pagamento do overdraft. Para cada tipo de rota e direção compatível, configure as duas rubricas, de débito e de crédito. **Block** e **unblock** podem usar rubricas dedicadas para as operações que os endpoints de transação de block e unblock produzem. Sem essas rubricas, essas ações usam a rubrica `direct`. Quando precisar, registre rubricas dedicadas para essas ações do mesmo jeito que para as outras ações.

> [!TIP]
>
> Cada ação pode apontar para rubricas de débito e de crédito diferentes na mesma Rota de Operação. Mapeie apenas as ações que uma rota usa. Se você habilitar a validação estrita (abaixo), cubra cada ação que as suas transações emitem.

## Configurar Lançamentos contábeis

***

Você registra as rubricas pela API, como parte das suas Rotas de Operação. O bloco `accountingEntries` em uma rota define um lançamento por ação. Cada lançamento carrega a rubrica `debit` e/ou `credit` dele:

```json accountingEntries theme={null}
{
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.1.001",
                "description": "Customer checking — outbound"
            },
            "credit": {
                "code": "1.1.1.002",
                "description": "Customer checking — inbound"
            }
        }
    }
}
```

Você gerencia esses lançamentos pelos endpoints de Rota de Operação. Veja [Criar uma Rota de Operação](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-operation-route.md) e [Atualizar uma Rota de Operação](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-operation-route.md). Para o fluxo completo de configuração, consulte [Roteamento de Transações](https://docs.lerian.studio/pt/products/midaz/transaction-routing-entities.md#4-configure-accounting-entries-actions).

## Modos de validação

***

O Midaz reage a uma rubrica ausente conforme as configurações contábeis do Ledger. Dois controles distintos governam esse comportamento:

### Padrão (graceful)

Por padrão (`accounting.validateRoutes` desabilitado), o Midaz não resolve rubrica nenhuma: a transação segue normalmente e os campos `routeCode` e `routeDescription` ficam vazios (nil) em cada operação. Ele não levanta erro.

### Estrito (opt-in)

Defina `accounting.validateRoutes` como `true` nas [Configurações do Ledger](https://docs.lerian.studio/pt/products/midaz/ledgers.md#ledger-settings) para aplicar a validação de rota. No modo estrito, o Midaz retorna `0157` quando nenhuma Rota de Operação da Rota de Transação tem um lançamento para a ação solicitada. Ele retorna `0117` quando uma perna não informa uma Rota de Operação, ou informa uma que a Rota de Transação não oferece para essa ação. Uma movimentação de overdraft em uma rota sem um lançamento `overdraft` retorna `0492`.

```json PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/settings theme={null}
{
  "accounting": {
    "validateRoutes": true
  }
}
```

> [!TIP]
>
> Use o **modo estrito** em ledgers de produção onde cada tipo de transação precisa de uma classificação contábil. O padrão graceful ajuda enquanto você cadastra as rotas. Em produção, ele pode deixar movimentações sem classificação, em silêncio.

Quando o Midaz encontra uma rubrica correspondente, ele anota a operação com dois campos:

* **routeCode**: o `code` do `AccountingRubric` resolvido para essa ação e direção.
* **routeDescription**: a descrição da rubrica resolvida, preenchida junto com `routeCode`.


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