> ## 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. # Passo a passo de contabilidade > Um guia prático de ponta a ponta para desenhar e implementar a contabilidade no Midaz, do plano de contas até um exemplo funcional de pagamento Pix. Este guia mostra como implementar a contabilidade no Midaz do começo ao fim. Ele supõe que você é desenvolvedor. Você quer apenas o contexto contábil suficiente para modelar um produto real. Ao final, você entende como as primitivas se encaixam. Você também consegue montar um pagamento Pix completo com registros de partidas dobradas corretos. Para a visão geral conceitual e os links de cada página de referência, veja **[Contabilidade](https://docs.lerian.studio/pt/products/midaz/accounting-in-midaz)**. ## 1. Fundamentos de partidas dobradas *** O Midaz aceita a escrituração por partidas dobradas pelas rotas de transação dele. Configure uma rota com Rotas de Operação de origem e de destino, ou uma Rota de Operação Bidirecional que cobre os dois lados. Com **Validate Routes** habilitado, o Midaz valida cada transação contra as regras de rota configuradas. A validação de rota vem desabilitada por padrão. Habilite-a apenas depois de configurar as rotas que o seu Ledger precisa. Nem todas as ações de ciclo de vida usam os dois lados: o cancelamento é apenas de origem e libera os recursos retidos na Conta de origem. > [!NOTE] > > Pense em *de onde o valor vem* (o lado do débito / origem) e *para onde ele vai* (o lado do crédito / destino). Cada operação do Midaz cai em um dos lados dessa equação. ## 2. Plano de Contas no Midaz *** Na contabilidade tradicional, o Plano de Contas (CoA) define as categorias de conta (Ativo, Passivo, Patrimônio Líquido, Receitas, Despesas), a hierarquia delas e como classificar as movimentações. > [!NOTE] > > O Midaz não tem uma API dedicada de Plano de Contas. O CoA é o resultado de como você combina ativos, contas, segmentos, portfólios e tipos de conta. O campo `code` dos Lançamentos contábeis (por exemplo `1.1.1.001`) é onde a numeração tradicional de contas aparece na prática. Cada `code` anota um registro contábil com a classificação dele. O Midaz permite espelhar ou adaptar um CoA digitalmente com um conjunto pequeno de primitivas: * **Ativos** definem *o que* se move: moedas (BRL, USD), pontos/milhas, tokens de cripto ou unidades internas de valor. * **Contas** são recipientes de saldo. Cada uma tem um código de ativo e um tipo. Ela também pode pertencer a um portfólio e a um segmento. Um **alias** (por exemplo `@external/BRL`) identifica cada conta e mantém o roteamento intuitivo. * **Segmentos** categorizam e isolam contas (recursos de clientes vs. internos, unidades de negócio, separação multi-tenant). * **Portfólios** agrupam contas que compartilham uma finalidade ou pertencem à mesma entidade. Para mapear um CoA no Midaz, você decide quais saldos precisa e os classifica com Tipos de Conta. Depois você os organiza com segmentos e portfólios em um ledger e atribui valores de `code` nos seus Lançamentos contábeis para bater com o seu esquema de numeração. ### Um processo recomendado **1. Mapeie o seu modelo financeiro** Liste os saldos que você precisa: saldos de clientes, contas internas, contas de reserva/liquidação, contas de tarifa e de receita. Esta é a planta do seu CoA. **2. Defina os tipos de conta** Crie um Tipo de Conta por categoria conceitual, por exemplo `CASH`, `SETTLEMENT`, `FEE_REVENUE`, `FEE_EXPENSE`, `TREASURY`. **3. Crie segmentos e portfólios** Segmentos separam domínios de negócio (`CUSTOMER_FUNDS`). Portfólios gerenciam a titularidade e o agrupamento (`customer_12345_wallet`). **4. Crie as contas** Para cada saldo lógico, crie uma conta no ledger (conta BRL do cliente, conta de tesouraria, conta de despesa com tarifa de provedor, conta de liquidação do estabelecimento). ## 3. Configurar os Tipos de Conta *** Tipos de Conta classificam contas por natureza e finalidade. Com `validateAccountType` habilitado, o `type` de uma nova Conta não externa deve corresponder a um `keyValue` registrado. Uma Rota de Operação pode, separadamente, usar `ruleType: account_type` para validar uma conta durante o processamento da rota. Os Tipos de Conta em si não definem as operações permitidas, o status interno ou externo, nem as regras de conciliação. Uma configuração típica para um produto de pagamentos: * **CASH** → recursos líquidos de clientes * **SETTLEMENT** → recursos aguardando compensação * **FEE\_REVENUE** → tarifas recebidas * **FEE\_EXPENSE** → tarifas de provedores * **TREASURY** → operações internas Para habilitar a validação de Tipo de Conta, entender o campo `type` e gerenciar Tipos de Conta pela API, veja **[Tipos de conta](https://docs.lerian.studio/pt/products/midaz/account-types.md)**. ### Entender os compartimentos de saldo Antes de montar fluxos em duas fases, entenda que cada saldo acompanha os recursos em campos distintos: * **`available`**: recursos que você pode gastar ou enviar agora. Débitos e créditos em um saldo movem esse número. * **`onHold`**: recursos que um `hold` pendente reserva e ainda não confirma. Eles continuam pertencendo à conta até você confirmar ou cancelar o hold. * **`overdraftUsed`**: o overdraft consumido pelo saldo, quando o overdraft está habilitado. Os três campos carregam strings decimais com precisão exata (por exemplo, `"12.50"`). Não existe um campo `scale` separado para interpretar. Veja [Valor da transação](https://docs.lerian.studio/pt/products/midaz/amount.md) para o modelo de valor decimal. As ações em duas fases alteram `available` e `onHold` no saldo de origem. Estas linhas 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 | `available` | `onHold` | | - | - | - | | **Direct** | Debitado (origem) / creditado (destino) | sem alteração | | **Hold** | ↓ diminui na origem | ↑ aumenta na origem | | **Commit** | creditado no destino | ↓ liberado da origem | | **Cancel** | ↑ devolvido à origem | ↓ liberado de volta para `available` | | **Revert** | restaurado nos dois lados por uma contratransação | sem alteração | Para o modelo completo de saldo (vários saldos por conta, flags de permissão, overdraft e histórico), veja **[Saldos](https://docs.lerian.studio/pt/products/midaz/balances.md)**. ## 4. Definir os Lançamentos contábeis (Rubricas) *** **Lançamentos contábeis** (Rubricas) mapeiam uma ação de transação e uma direção de rota para um `code` e uma `description` contábeis. Você registra as rubricas uma vez, em vez de calcular as classificações contábeis à mão para cada movimentação. Quando `accounting.validateRoutes` está habilitado no ledger e uma rubrica correspondente está configurada, o Midaz anota cada operação com o `routeCode` e o `routeDescription` resultantes. As regras da Rota de Operação e as pernas da transação determinam as contas participantes. Você configura as rubricas **por ação** em cada Rota de Operação, dentro do bloco `accountingEntries`. 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. Quando você não as configura, o Midaz resolve a rubrica `direct` para essas ações. As ações `hold` e `cancel` do lado da origem exigem **as duas** rubricas, `overdraft` exige **as duas** em cada tipo de rota compatível, e rotas bidirecionais sempre exigem **as duas**. ### As cinco ações do ciclo de vida da transação | Ação | Código | O que faz | | - | - | - | | **Direct** | `direct` | Registro contábil 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 (`available` → `onHold` na origem). | | **Commit** | `commit` | Confirma um valor retido antes, liberando `onHold` para o destino. | | **Cancel** | `cancel` | Cancela um hold, devolvendo o valor em `onHold` para `available` na origem. | | **Revert** | `revert` | Reverte uma transação `APPROVED` por uma contratransação quando as Rotas de Operação dela são bidirecionais. | Cada ação pode apontar para rubricas de débito/crédito diferentes na mesma Rota de Operação. Cada etapa de uma operação então recebe a anotação contábil certa. Você registra esses mapeamentos 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). ```json theme={null} { "accountingEntries": { "direct": { "debit": { "code": "1.1.1.001", "description": "Customer cash-out" }, "credit": { "code": "2.1.1.001", "description": "External settlement" } } } } ``` Para o modelo completo, veja **[Lançamentos contábeis (Rubricas)](https://docs.lerian.studio/pt/products/midaz/accounting-entries.md)**. ## 5. Roteamento de transações *** O roteamento é um sistema de duas camadas que se resolve em tempo de execução: * **Rotas de Operação** definem as regras de cada perna de uma transação: o lado dela (origem, destino ou ambos) e uma regra de conta opcional. Elas carregam os **Lançamentos contábeis (rubricas)** acima. * **Rotas de Transação** definem o evento de negócio que dispara a contabilidade (`PIX_CASH_OUT`, `WALLET_TRANSFER`, `BANK_SLIP_SETTLEMENT`, …) e combinam Rotas de Operação em um evento financeiro balanceado. Quando você envia uma transação, você informa a Rota de Transação dela. Com a validação de rota habilitada, o Midaz verifica cada perna contra a Rota de Operação dela e resolve a rubrica para a ação atual. Para a estrutura da rota, os campos, a matriz de validação por tipo de operação e o comportamento da API, veja **[Roteamento de Transações](https://docs.lerian.studio/pt/products/midaz/transaction-routing-entities.md)**. ## 6. Exemplo de ponta a ponta: um pagamento Pix *** Este exemplo é um cash-out Pix simples. Um cliente envia BRL da carteira dele para uma conta externa. **1. Configuração das contas** Crie a conta do cliente no seu ledger. O Midaz cria `@external/BRL` automaticamente junto com o Ativo `BRL`. Não a crie por conta própria. * `customer_12345_brl`: Tipo de Conta `CASH`, ativo `BRL` * `@external/BRL`: a conta externa de liquidação criada automaticamente para os recursos que saem do ledger **2. Habilite a validação de rota e registre as rubricas** Habilite `accounting.validateRoutes` no ledger. Depois, na Rota de Operação da perna do cliente (origem), registre a rubrica de débito `direct`. Na perna externa (destino), registre a rubrica de crédito `direct`: ```json theme={null} { "accountingEntries": { "direct": { "debit": { "code": "1.1.1.001", "description": "Pix cash-out — customer" }, "credit": { "code": "2.1.1.001", "description": "Pix cash-out — external settlement" } } } } ``` Este bloco é uma ilustração combinada das duas rubricas. Registre apenas o campo `debit` na rota de Origem e apenas o campo `credit` na rota de Destino. **3. Transação** Envie uma transação contra a Rota de Transação `PIX_CASH_OUT`. Mova, digamos, `100.00 BRL` de `customer_12345_brl` para `@external/BRL`. **4. Operações resultantes** O Midaz registra duas operações balanceadas: * **Débito** `customer_12345_brl` `100.00 BRL`, `routeCode: 1.1.1.001` * **Crédito** `@external/BRL` `100.00 BRL`, `routeCode: 2.1.1.001` As duas compartilham o mesmo `transactionId`. Isso dá a você uma trilha completa de transação → operação → rubrica. Para um fluxo em duas fases (hold → commit/cancel), registre as rubricas `hold`, `commit` e `cancel` na rota de origem e a rubrica `commit` na rota de destino. Envie as ações correspondentes. Cada etapa resolve a própria rubrica. ## 7. Modos de validação *** O Midaz controla a validação de rota pela configuração `accounting.validateRoutes` de cada ledger. O padrão é `false`. Nesse modo graceful, o Midaz pula a validação de rota. Ele deixa os campos `routeCode` e `routeDescription` vazios em cada operação e não levanta erro. O modo graceful é conveniente enquanto você cadastra as rotas. Em produção, defina `accounting.validateRoutes` como `true` nas [Configurações do Ledger](https://docs.lerian.studio/pt/products/midaz/ledgers.md#ledger-settings). O modo estrito então valida as rotas em cada transação: ```json theme={null} { "accounting": { "validateRoutes": true } } ``` 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. Quando uma rota resolve, o Midaz carimba `routeCode` e `routeDescription` a partir da rubrica dela. > [!TIP] > > Use o **modo estrito** (`validateRoutes: true`) em ledgers de produção onde cada tipo de transação precisa de uma classificação contábil. Mantenha o padrão graceful apenas enquanto você cadastra as rotas. ## Próximos passos *** * Revise a visão geral de **[Contabilidade](https://docs.lerian.studio/pt/products/midaz/accounting-in-midaz)** e as páginas de referência para o detalhe completo de cada campo. * Assim que o seu ledger produzir registros contábeis estruturados, veja o **[Lerian Reporter](https://docs.lerian.studio/pt/products/reporter/what-is-reporter.md)** para transformar eventos do ledger em arquivos de conciliação, demonstrações financeiras e saídas regulatórias alinhadas ao COSIF. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.