> ## 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 contexto contábil suficiente para modelar um produto real, não um livro-texto inteiro de contabilidade. 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](/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 as regras de rota configuradas para transações diretas. 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. 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. 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. Cada ativo tem precisão decimal e metadados regulatórios. * **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 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. Crie um Tipo de Conta por categoria conceitual, por exemplo `CASH`, `SETTLEMENT`, `FEE_REVENUE`, `FEE_EXPENSE`, `TREASURY`. Segmentos separam domínios de negócio (`CUSTOMER_FUNDS`). Portfólios gerenciam a titularidade e o 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 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](/pt/products/midaz/account-types)**. ### 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. O Midaz os tira de `available`, mas 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](/pt/products/midaz/amount) para o modelo de valor decimal. As ações em duas fases movem valor entre `available` e `onHold` no saldo de origem: | 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](/pt/products/midaz/balances)**. ## 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, com um débito e um ou mais créditos, ou um crédito e um ou mais débitos; 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 classificações contábeis de débito/crédito diferentes dentro da mesma rubrica. 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](/pt/reference/products/midaz/v2/create-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" } } } } ``` Para o modelo completo, veja **[Lançamentos contábeis (Rubricas)](/pt/products/midaz/accounting-entries)**. ## 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 a lógica contábil de cada perna de uma transação: quais contas debitar ou creditar, chaves de saldo e regras de validação. 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, o Midaz resolve a Rota de Transação correspondente. Depois ele resolve cada Rota de Operação e a rubrica dela para a ação atual. Antes de registrar qualquer coisa, o Midaz roda quatro verificações. Ele confirma que os saldos existem, que os débitos não passam do saldo disponível, que os ativos batem e que o ledger continua balanceado. 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](/pt/products/midaz/transaction-routing-entities)**. ## 6. Exemplo de ponta a ponta: um pagamento Pix *** Vamos juntar tudo com um cash-out Pix simples: um cliente envia BRL da carteira dele para uma conta externa. 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 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. 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`. 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`, o que 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. 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](/pt/products/midaz/ledgers#ledger-settings). O modo estrito então valida as rotas em cada transação: ```json theme={null} { "accounting": { "validateRoutes": true } } ``` 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. Quando uma rota resolve, o Midaz carimba `routeCode` e `routeDescription` a partir da rubrica dela. 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](/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](/pt/products/reporter/what-is-reporter)** para transformar eventos do ledger em arquivos de conciliação, demonstrações financeiras e saídas regulatórias alinhadas ao COSIF.