> ## 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. # Walkthrough de contabilidade > Um guia prático de ponta a ponta para projetar e implementar contabilidade no Midaz — do plano de contas até um exemplo funcional de pagamento Pix. Este guia mostra como implementar a contabilidade no Midaz do início ao fim. Ele pressupõe que você é uma pessoa desenvolvedora. Você quer contexto contábil suficiente para modelar um produto real, e não um manual completo de contabilidade. Ao final, você entende como as primitivas se encaixam. Você também consegue montar um pagamento Pix completo com lançamentos de partidas dobradas corretos. Para a visão conceitual e os links para cada página de referência, veja **[Contabilidade](/pt/midaz/accounting-in-midaz)**. ## 1. Fundamentos da contabilidade por partidas dobradas *** O Midaz usa escrituração rigorosa por partidas dobradas. As regras são simples, mas inegociáveis: * Toda transação **deve** ter pelo menos um débito e um crédito. * O total de débitos **deve ser igual** ao total de créditos. * Cada movimentação impacta o ledger de forma balanceada. Isso garante que não haja divergência nos saldos, trilhas de auditoria precisas e demonstrações financeiras prontas para regulamentação. Na prática, você raramente faz partidas dobradas manualmente no Midaz. Você modela suas contas e o roteamento uma única vez. O motor aplica o balanceamento em cada transação. Pense em termos de *de onde o valor vem* (o lado do débito / origem) e *para onde ele vai* (o lado do crédito / destino). Toda operation 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 contas (Ativos, Passivos, Patrimônio Líquido, Receitas, Despesas), sua hierarquia e como classificar as movimentações. O Midaz não possui uma API dedicada de Plano de Contas. O CoA não é um recurso que você cria ou recupera. Ele é o resultado de como você combina ativos, contas, segmentos, portfólios e tipos de conta. O campo `code` nos Lançamentos Contábeis (ex.: `1.1.1.001`) é onde a numeração de conta tradicional aparece na prática. Cada `code` anota um lançamento com sua classificação. O Midaz permite que você espelhe ou adapte um CoA digitalmente usando um pequeno conjunto de primitivas: * **Ativos** definem *o que* se movimenta — moedas (BRL, USD), pontos/milhas, tokens crypto ou unidades internas de valor — com precisão decimal e metadata regulatória. * **Contas** são contêineres de saldo. Cada uma pertence a um portfólio, um segmento, um tipo de conta e um código de ativo. Um **alias** (ex.: `@external/BRL`) identifica cada conta e mantém o roteamento intuitivo. * **Segmentos** categorizam e isolam contas (fundos de clientes vs. internos, unidades de negócio, separação multi-tenant). * **Portfólios** agrupam contas que compartilham um propósito ou pertencem à mesma entidade. Para mapear um CoA no Midaz, você decide quais saldos precisa e os classifica com Tipos de Conta. Em seguida, você os organiza com segmentos e portfólios em um ledger e atribui valores de `code` aos seus Lançamentos Contábeis para corresponder ao seu esquema de numeração. ### Um processo recomendado Liste os saldos necessários: saldos de clientes, contas internas, contas de reserva/liquidação, contas de taxas e receitas. Este é o blueprint do seu CoA. Crie um Tipo de Conta por categoria conceitual — ex.: `CASH`, `SETTLEMENT`, `FEE_REVENUE`, `FEE_EXPENSE`, `TREASURY`. Segmentos separam domínios de negócio (`CUSTOMER_FUNDS`). Portfólios gerenciam propriedade e agrupamento (`customer_12345_wallet`). Para cada saldo lógico, crie uma conta no ledger (conta BRL do cliente, conta de tesouraria, conta de despesa com taxas de provedor, conta de liquidação do merchant). ## 3. Configurando Tipos de Conta *** Tipos de Conta são **templates** para as contas no seu ledger. Eles definem como as contas se comportam: operações permitidas, classificação interna vs. externa e regras de reconciliação. Eles também permitem que você classifique contas de acordo com sua estrutura financeira. Uma configuração típica para um produto de pagamentos: * **CASH** → fundos líquidos do cliente * **SETTLEMENT** → fundos aguardando compensação * **FEE\_REVENUE** → taxas cobradas * **FEE\_EXPENSE** → taxas de provedores * **TREASURY** → operações internas Para saber como habilitar a validação de Tipo de Conta, entender o campo `type` e gerenciar Tipos de Conta via API, veja **[Tipos de Conta](/pt/midaz/account-types)**. ### Entendendo os buckets de saldo Antes de montar fluxos em duas fases, entenda que cada saldo rastreia fundos em buckets distintos. Um saldo expõe dois campos de valor: * **`available`** — fundos que você pode gastar ou enviar imediatamente. Débitos e créditos a um saldo movem esse número. * **`onHold`** — fundos que um `hold` pendente reserva e ainda não confirma. O Midaz os remove de `available`, mas eles ainda pertencem à conta até que você confirme ou cancele a reserva. Ambos os campos carregam strings decimais com precisão exata (por exemplo, `"12.50"`). Não existe um campo `scale` separado para interpretá-los. Veja [Valor da transação](/pt/midaz/amount) para o modelo de valores decimais. As ações de duas fases movem valor entre `available` e `onHold` no saldo de origem: | Ação | `available` | `onHold` | | ---------- | ------------------------------------------------ | ------------------------------------ | | **Direct** | Debitado (origem) / creditado (destino) | inalterado | | **Hold** | ↓ diminui na origem | ↑ aumenta na origem | | **Commit** | creditado no destino | ↓ liberado da origem | | **Cancel** | ↑ retorna à origem | ↓ liberado de volta para `available` | | **Revert** | restaurado em ambos os lados via contratransação | inalterado | Para o modelo completo de saldos — múltiplos saldos por conta, flags de permissão, overdraft e histórico — veja **[Saldos](/pt/midaz/balances)**. ## 4. Definindo Lançamentos Contábeis (Rubricas) *** Os **Lançamentos Contábeis** (Rubricas) mapeiam uma ação de transação para as contas do ledger que ela debita e credita. Você registra as rubricas uma vez em vez de calcular as classificações contábeis manualmente para cada movimentação. Em seguida, o Midaz as resolve automaticamente e registra o `routeCode` e o `routeDescription` resultantes em cada operation. Você configura as rubricas **por ação** em cada Operation Route, dentro do bloco `accountingEntries`. Rotas de origem exigem a rubrica de **débito**, rotas de destino exigem a rubrica de **crédito** e rotas bidirecionais exigem **ambas**. ### As cinco ações do ciclo de vida da transação | Ação | Código | O que faz | | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | **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 (`available` → `onHold` na origem). | | **Commit** | `commit` | Confirma um valor previamente reservado, liberando o `onHold` para o destino. | | **Cancel** | `cancel` | Cancela uma reserva, retornando o valor `onHold` para `available` na origem. | | **Revert** | `revert` | Reverte uma transação `direct` concluída via uma contratransação. | Cada ação pode apontar para mapeamentos de débito/crédito diferentes dentro da mesma rubrica. Assim, cada etapa de uma operação cai no lançamento correto do ledger. Você registra esses mapeamentos por meio dos endpoints de Operation Route — veja [Criar uma Operation Route](/pt/reference/midaz/create-an-operation-route). ```json theme={null} { "accountingEntries": { "direct": { "debit": { "code": "1.1.1.001", "description": "Customer cash-out" }, "credit": { "code": "2.1.1.001", "description": "External settlement" } }, "hold": { "debit": { "code": "1.1.2.001", "description": "Pending settlement — hold" } } } } ``` Para o modelo completo, veja **[Lançamentos Contábeis (Rubricas)](/pt/midaz/accounting-entries)**. ## 5. Roteamento de transações *** O roteamento é um sistema de duas camadas que resolve em tempo de execução: * **Operation Routes** definem a lógica contábil de cada perna de uma transação: quais contas debitar ou creditar, balance keys e regras de validação. Elas carregam os **Lançamentos Contábeis (rubricas)** acima. * **Transaction Routes** definem o evento de negócio que dispara a contabilidade (`PIX_CASH_OUT`, `WALLET_TRANSFER`, `BANK_SLIP_SETTLEMENT`, …) e combinam Operation Routes em um evento financeiro balanceado. Quando você submete uma transação, o Midaz resolve a Transaction Route correspondente. Em seguida, ele resolve cada Operation Route e sua rubrica para a ação atual. Antes de registrar qualquer coisa, o Midaz executa quatro verificações. Ele confirma que os saldos existem, que os débitos não excedem o saldo disponível, que os ativos correspondem e que o ledger permanece balanceado. Para a estrutura das rotas, os campos, a matriz de validação por tipo de operação e o comportamento da API, veja **[Roteamento de Transações](/pt/midaz/transaction-routing-entities)**. ## 6. Exemplo de ponta a ponta — um pagamento Pix *** Vamos juntar tudo com um Pix cash-out simples: um cliente envia BRL da sua carteira para uma conta externa. Crie as contas no seu ledger: * `customer_12345_brl` — Tipo de Conta `CASH`, ativo `BRL` * `@external/BRL` — a conta de liquidação externa para fundos que saem do ledger Na Operation Route 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" } } } } ``` Submeta uma transação contra a Transaction Route `PIX_CASH_OUT`. Movimente, digamos, `100.00 BRL` de `customer_12345_brl` para `@external/BRL`. O Midaz registra duas operations 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` Ambas compartilham o mesmo `transactionId`, dando a você uma trilha completa de transação → operation → rubrica. Para um fluxo em duas fases (hold → commit/cancel), registre as rubricas `hold`, `commit` e `cancel` na rota. Submeta as ações correspondentes. Cada etapa resolve sua própria rubrica. ## 7. Modos de validação *** O Midaz controla a validação de rotas com a configuração `accounting.validateRoutes` em cada ledger. O padrão é `false`. Nesse modo graceful, o Midaz pula a validação de rotas. Ele deixa os campos `routeCode` e `routeDescription` vazios em cada operation e não gera nenhum erro. O modo graceful é conveniente enquanto você configura rotas. Em produção, defina `accounting.validateRoutes` como `true` nas [Configurações do Ledger](/pt/midaz/ledgers#ledger-settings). O modo estrito valida então as rotas em cada transação: ```json theme={null} { "accounting": { "validateRoutes": true } } ``` No modo estrito, cada operation deve referenciar uma operation route válida para sua ação e direção. Se uma operation não tem rota, ou referencia uma rota que não existe para a ação, o Midaz rejeita a transação com `0117 ErrAccountingRouteNotFound`. Quando a rota resolve, o Midaz grava o `routeCode` e o `routeDescription` a partir de sua rubrica. Isso impede que movimentações fiquem sem classificação contábil. 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 configura rotas. ## Próximos passos *** * Revise a visão geral de **[Contabilidade](/pt/midaz/accounting-in-midaz)** e as páginas de referência para o detalhamento completo a nível de campo. * Quando seu ledger produzir lançamentos estruturados, veja o **[Lerian Reporter](/pt/reporter/what-is-reporter)** para transformar eventos do ledger em arquivos de reconciliação, demonstrações financeiras e saídas regulatórias alinhadas ao COSIF.