Walkthrough de contabilidade

Este guia conduz você pela implementação da contabilidade no Midaz do início ao fim. Ele pressupõe que você é uma pessoa desenvolvedora que quer contexto contábil suficiente para modelar um produto real corretamente — e não um manual completo de contabilidade. Ao final, você entenderá como as primitivas se encaixam e como montar um pagamento Pix completo com lançamentos de partidas dobradas adequados. 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 é construído sobre 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, e 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 as movimentações são classificadas.

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, anotando cada 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 é movimentado — moedas (BRL, USD), pontos/milhas, tokens crypto ou unidades internas de valor — junto com a precisão decimal e a 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, e é identificada por um alias (ex.: @external/BRL) para tornar 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.

Mapear um CoA no Midaz significa decidir quais saldos você precisa, classificá-los com Tipos de Conta, organizá-los com segmentos e portfólios em um ledger e atribuir valores de code aos seus Lançamentos Contábeis para refletir seu esquema de numeração de contas.

Um processo recomendado

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.

Defina os tipos de conta

Crie um Tipo de Conta por categoria conceitual — ex.: CASH, SETTLEMENT, FEE_REVENUE, FEE_EXPENSE, TREASURY.

Crie segmentos e portfólios

Segmentos separam domínios de negócio (CUSTOMER_FUNDS); portfólios gerenciam propriedade e agrupamento (customer_12345_wallet).

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 — e 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, o comportamento do campo type e como gerenciar Tipos de Conta via API, veja Tipos de Conta.

Entendendo os buckets de saldo

Antes de montar fluxos em duas fases, ajuda saber que cada saldo rastreia fundos em buckets distintos. O valor de um saldo é exposto por meio de três campos:

available — fundos livres para serem gastos ou enviados imediatamente. Débitos e créditos a um saldo movem esse número.
onHold — fundos reservados por um hold pendente e ainda não confirmados. Eles são removidos de available, mas ainda pertencem à conta até que a reserva seja confirmada ou cancelada.
scale — o número de casas decimais usado para interpretar os valores inteiros (ex.: scale: 2 significa que available: 100 é 1.00). Ele define a precisão, não um pool de fundos separado.

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.

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. Em vez de calcular as classificações contábeis manualmente para cada movimentação, você registra as rubricas uma única vez e deixa o Midaz resolvê-las automaticamente — registrando o routeCode e o routeDescription resultantes em cada operation. As rubricas são configuradas 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.

Os cinco tipos de açã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` → `on_hold` na origem).
Commit	`commit`	Confirma um valor previamente reservado, liberando o `on_hold` para o destino.
Cancel	`cancel`	Cancela uma reserva, retornando o valor `on_hold` 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, de modo que cada etapa de uma operação caia no lançamento correto do ledger. Você registra esses lançamentos por meio dos endpoints de Operation Route — veja Criar uma Operation Route.

{
  "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).

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 são debitadas/creditadas, balance keys, regras de validação — e 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 uma transação é submetida, o Midaz resolve a Transaction Route correspondente e, em seguida, resolve cada Operation Route e sua rubrica para a ação que está sendo executada. Ele valida 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 — antes de registrar qualquer coisa. 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.

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

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:

{
  "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" }
    }
  }
}

Transação

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

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 e submeta as ações correspondentes; cada etapa resolve sua própria rubrica.

7. Modos de validação

Por padrão, se nenhuma rubrica estiver registrada para uma ação, a transação prossegue normalmente e os campos routeCode/routeDescription simplesmente ficam vazios para aquela operation — nenhum erro é gerado. Esse modo graceful é conveniente enquanto você ainda está configurando rotas. Em produção, defina accounting.validateRoutes como true nas Configurações do Ledger para exigir que toda ação tenha uma rubrica registrada:

{
  "accounting": {
    "validateRoutes": true
  }
}

Com o modo estrito habilitado, qualquer operation cuja ação e direção não tenha um mapeamento registrado é rejeitada com 0117 ErrAccountingRouteNotFound. Isso evita que movimentações fiquem silenciosamente sem classificação contábil.

Use o modo estrito (validateRoutes: true) em ledgers de produção, onde cada tipo de transação precisa ser contabilizado. Mantenha o padrão graceful apenas enquanto estiver configurando 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.

​1. Fundamentos da contabilidade por partidas dobradas

​2. Plano de Contas no Midaz

​Um processo recomendado

​3. Configurando Tipos de Conta

​Entendendo os buckets de saldo

​4. Definindo Lançamentos Contábeis (Rubricas)

​Os cinco tipos de ação

​5. Roteamento de transações

​6. Exemplo de ponta a ponta — um pagamento Pix

​7. Modos de validação

​Próximos passos

1. Fundamentos da contabilidade por partidas dobradas

2. Plano de Contas no Midaz

Um processo recomendado

3. Configurando Tipos de Conta

Entendendo os buckets de saldo

4. Definindo Lançamentos Contábeis (Rubricas)

Os cinco tipos de ação

5. Roteamento de transações

6. Exemplo de ponta a ponta — um pagamento Pix

7. Modos de validação

Próximos passos