> ## 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`).
* Um conjunto de **mapeamentos de ação**: um lançamento por tipo de ação, cada um com a própria rubrica de débito e/ou de crédito.
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.
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 8 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 últimas cobrem movimentações de overdraft, block e unblock. Uma única rubrica pode mapear classificações 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.
| Ação | Identificador | Descrição |
| :------------ | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Direct** | `direct` | Débito/crédito imediato, em uma única etapa, entre duas contas, 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 `on_hold` na conta de origem). |
| **Commit** | `commit` | Confirma um valor retido antes, liberando o valor em `on_hold` para a conta de destino. |
| **Cancel** | `cancel` | Cancela/reverte um hold, devolvendo o valor em `on_hold` ao 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 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`. |
**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.
Cada ação pode apontar para classificações contábeis de débito e de 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 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"
}
},
"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 pelos endpoints de Rota de Operação. Veja [Criar uma Rota de Operação](/pt/reference/products/midaz/v2/create-operation-route) e [Atualizar uma Rota de Operação](/pt/reference/products/midaz/v2/update-operation-route). Para o fluxo completo de configuração, consulte [Roteamento de Transações](/pt/products/midaz/transaction-routing-entities#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](/pt/products/midaz/ledgers#ledger-settings) para aplicar a validação de rota. No modo estrito, uma ação solicitada sem rotas no cache de rotas de transação retorna `0157 ErrNoRoutesForAction`. `0117 ErrAccountingRouteNotFound` vale quando um ID de rota de operação está ausente desse cache.
```json PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings theme={null}
{
"accounting": {
"validateRoutes": true
}
}
```
No modo estrito, não trate `0117 ErrAccountingRouteNotFound` como o erro de cada ação não mapeada: ele vale quando um ID de rota de operação está ausente do cache de rotas de transação. Uma ação solicitada sem rotas nesse cache retorna `0157 ErrNoRoutesForAction`.
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`.