Passo a passo de contabilidade

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.

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

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.

Defina os tipos de conta

Crie um Tipo de Conta por categoria conceitual, por exemplo CASH, SETTLEMENT, FEE_REVENUE, FEE_EXPENSE, TREASURY.

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

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.

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

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.

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

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.

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.

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

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:

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

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.

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, 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. O modo estrito então valida as rotas em cada transação:

{
  "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 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 para transformar eventos do ledger em arquivos de conciliação, demonstrações financeiras e saídas regulatórias alinhadas ao COSIF.

Midaz Core

CRM

Fees

Passo a passo de contabilidade

1. Fundamentos de partidas dobradas

2. Plano de Contas no Midaz

Um processo recomendado

3. Configurar os Tipos de Conta

Entender os compartimentos de saldo

4. Definir os Lançamentos contábeis (Rubricas)

As cinco ações do ciclo de vida da transaçã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 de partidas dobradas

​2. Plano de Contas no Midaz

​Um processo recomendado

​3. Configurar os Tipos de Conta

​Entender os compartimentos de saldo

​4. Definir os Lançamentos contábeis (Rubricas)

​As cinco ações do ciclo de vida da transaçã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 de partidas dobradas

2. Plano de Contas no Midaz

Um processo recomendado

3. Configurar os Tipos de Conta

Entender os compartimentos de saldo

4. Definir os Lançamentos contábeis (Rubricas)

As cinco ações do ciclo de vida da transação

5. Roteamento de transações

6. Exemplo de ponta a ponta: um pagamento Pix

7. Modos de validação

Próximos passos