> ## 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 para as contas do ledger que elas debitam e creditam, e anote cada operation com sua classificação contábil.
Os Lançamentos Contábeis (também conhecidos como **Rubricas**) mapeiam uma ação de transação para os lançamentos no ledger que ela gera. O motor usa esse mapeamento para resolver quais contas debitar e creditar em cada ação. Em seguida, ele anota cada operation com os códigos contábeis corretos de partidas dobradas em cada etapa do ciclo de vida da transação.
## O que são Lançamentos Contábeis
***
Uma **rubrica** mapeia uma ação de transação para as contas do ledger que o motor deve debitar e creditar. Em vez de calcular cada classificação manualmente, você registra as rubricas uma única vez. O Midaz então as resolve automaticamente à medida que processa as transações.
Cada rubrica carrega:
* **`code`** — um identificador único (o código do plano de contas, ex.: `1.1.1.001`).
* **`description`** — um rótulo legível para o lançamento (ex.: `Customer checking — outbound`).
* Um conjunto de **mapeamentos de ação** — um lançamento por tipo de ação, cada um com sua própria rubrica de débito e/ou crédito.
Quando o motor processa uma transação, ele resolve a rubrica de cada operation. Ele registra na operation o **`routeCode`** e o **`routeDescription`** resultantes. Isso fornece uma trilha de auditoria completa, da transação até a operation e a rubrica. Suas equipes podem rastrear exatamente qual regra contábil se aplicou a cada movimentação.
Configure as rubricas por ação em cada Operation Route. Rotas de **origem** (Source) exigem a rubrica de **débito**. Rotas de **destino** (Destination) exigem a rubrica de **crédito**. Rotas **bidirecionais** exigem **ambas**.
## Os 8 tipos de ação
***
Cada ação representa um evento transacional distinto. As primeiras cinco ações cobrem o ciclo de vida da transação. As últimas três cobrem os movimentos de cheque especial, bloqueio e desbloqueio. Uma única rubrica pode mapear diferentes contas de débito e crédito para cada ação. Cada etapa de uma operação então cai no lançamento correto do ledger.
| Ação | Identificador | Descrição |
| :------------ | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Direct** | `direct` | Débito/crédito imediato de etapa única entre duas contas, sem estágios intermediários (ex.: uma taxa ou ajuste). |
| **Hold** | `hold` | Reserva fundos criando uma movimentação pendente (move o valor de `available` para `on_hold` na conta de origem). |
| **Commit** | `commit` | Confirma um valor previamente reservado, liberando o valor `on_hold` para a conta de destino. |
| **Cancel** | `cancel` | Cancela/reverte uma reserva, retornando o valor `on_hold` para o saldo `available` na conta de origem. |
| **Revert** | `revert` | Reverte uma transação `direct` concluída criando uma contratransação que desfaz a original. |
| **Overdraft** | `overdraft` | Classifica os movimentos de cheque especial — a rubrica de **débito** marca o uso do cheque especial (o déficit cresce) e a rubrica de **crédito** marca o pagamento (o déficit diminui). Ambas as rubricas são obrigatórias quando este lançamento é configurado. |
| **Block** | `block` | Classifica um movimento de bloqueio de fundos que congela valor em uma conta (por exemplo, um `asset-freeze`). |
| **Unblock** | `unblock` | Classifica a liberação de fundos previamente bloqueados de volta para o saldo `available`. |
**Overdraft** classifica as operations complementares que o motor gera automaticamente durante o uso e o pagamento do cheque especial. **Block** e **unblock** classificam as operations que os endpoints de transação dedicados de bloqueio e desbloqueio produzem. Você registra as rubricas das três da mesma forma que as demais ações.
Cada ação pode apontar para mapeamentos de conta de débito e crédito diferentes dentro da mesma rubrica. Mapeie apenas as ações que uma rota usa. Se você habilitar a validação estrita (abaixo), cubra toda ação que suas transações emitirem.
## Configurando Lançamentos Contábeis
***
Você registra as rubricas via API como parte das suas Operation Routes. O bloco `accountingEntries` em uma rota define um lançamento por ação. Cada lançamento carrega sua rubrica de `debit` e/ou `credit`:
```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"
}
},
"hold": {
"debit": {
"code": "1.1.1.001",
"description": "Customer checking — reserve"
},
"credit": {
"code": "2.1.1.001",
"description": "Pending settlement — hold"
}
}
}
}
```
Você gerencia esses lançamentos por meio dos endpoints de Operation Route — veja [Criar uma Operation Route](/pt/reference/midaz/create-an-operation-route) e [Atualizar uma Operation Route](/pt/reference/midaz/update-an-operation-route). Para o fluxo completo de configuração, consulte [Roteamento de Transações](/pt/midaz/transaction-routing-entities#4-configurar-lançamentos-contábeis-actions).
## Modos de validação
***
O Midaz reage a uma rubrica ausente com base nas configurações contábeis do Ledger. Dois gates distintos controlam esse comportamento:
### Padrão (graceful)
Por padrão, a transação prossegue normalmente quando nenhuma rubrica corresponde a uma ação. O Midaz deixa os campos `routeCode` e `routeDescription` vazios (nil) para aquela operation. Ele não gera nenhum erro.
### Estrito (opt-in)
Defina `accounting.validateRoutes` como `true` nas [Configurações do Ledger](/pt/midaz/ledgers#ledger-settings) para exigir uma rubrica registrada em cada ação. O Midaz então rejeita qualquer operation cuja ação e direção não tenha um mapeamento registrado. Ele retorna o erro `0117 ErrAccountingRouteNotFound`.
```json PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings theme={null}
{
"accounting": {
"validateRoutes": true
}
}
```
No modo estrito, se uma rota tiver lançamentos contábeis mas uma transação usar uma ação não mapeada, o Midaz nega a transação com `0117 ErrAccountingRouteNotFound`. Uma Transação em Duas Etapas dispara isso quando você mapeia apenas `direct`. Esse gate mantém cada etapa de uma operação mapeada antes da execução, de modo que seus relatórios contábeis permaneçam consistentes.
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ê configura as rotas. Em produção, ele pode deixar movimentações sem classificação de forma silenciosa.
Quando o Midaz encontra uma rubrica correspondente, ele anota a operation com dois campos:
* **routeCode** — o `code` da `AccountingRubric` resolvida para aquela ação e direção.
* **routeDescription** — a descrição da rubrica resolvida, preenchida junto com o `routeCode`.