Skip to main content
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.

​
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

1

Mapeie seu modelo financeiro

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.
2

Defina os tipos de conta

Crie um Tipo de Conta por categoria conceitual — ex.: 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 propriedade e agrupamento (customer_12345_wallet).
4

Crie contas

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.

​
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 para o modelo de valores decimais. As ações de duas fases movem valor entre available e onHold no saldo de origem: Para o modelo completo de saldos — múltiplos saldos por conta, flags de permissão, overdraft e histórico — veja Saldos.

​
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

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.
Para o modelo completo, veja Lançamentos Contábeis (Rubricas).

​
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.

​
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.
1

Configuração das contas

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
2

Registro da rubrica

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:
3

Transação

Submeta uma transação contra a Transaction Route PIX_CASH_OUT. Movimente, digamos, 100.00 BRL de customer_12345_brl para @external/BRL.
4

Operations resultantes

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. O modo estrito valida então as rotas em cada transação:
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 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 para transformar eventos do ledger em arquivos de reconciliação, demonstrações financeiras e saídas regulatórias alinhadas ao COSIF.