Skip to main content
Este guia mostra a você como configurar a contabilidade no Módulo Midaz da Lerian Console. Você usa apenas as telas e formulários da Console — sem código. É o complemento Console do Passo a Passo de Contabilidade voltado a desenvolvedores. Você chega ao mesmo resultado, mas por meio do que você clica e configura, não do que você envia a uma API. Ele é voltado a product managers, times de implementação e desenvolvedores que preferem modelar sua contabilidade na UI. Mantemos os termos técnicos onde importam. Sempre explicamos o que significam quando você os vê na tela.
Você não verá nenhum JSON ou chamada de API aqui. Você faz tudo abaixo por meio dos formulários da Console. Para automatizar a mesma configuração mais tarde, siga a referência técnica que cada seção traz em link.

​
O que você está construindo

Configure suas rotas contábeis de forma deliberada. Uma rota define as Rotas de Operação de origem e destino para uma transação direta, ou uma Rota de Operação Bidirecional que cobre os dois lados. Com Validar Rotas habilitado, o Midaz valida as regras de rota configuradas para transações diretas. A validação de rotas vem desabilitada por padrão. Habilite-a somente depois de configurar as rotas necessárias para seu Ledger. O cancelamento é uma ação do ciclo de vida que usa apenas a origem: ele libera os fundos retidos na Conta de origem e não envolve uma Conta de destino. A configuração segue uma ordem lógica. Cada camada se apoia na anterior:
1

Planeje seu plano de contas

Decida quais saldos seu produto precisa (fundos de clientes, fees, settlement, treasury, revenues).
2

Crie os Tipos de Conta

Defina as categorias que classificam suas Contas.
3

Crie as Contas

Abra os contêineres de saldo reais, cada um com um campo Tipo obrigatório e um Asset. Quando Validate Account Type está habilitado, o Tipo de cada Conta não externa deve corresponder a um Tipo de Conta registrado.
4

Crie as Rotas Contábeis

Defina as regras para quais Contas podem participar de cada transação e como o ledger registra os lançamentos.
Trabalhe de cima para baixo. As rotas são muito mais fáceis de construir quando você já sabe quais Contas representam clientes, treasury, fees e settlement.

​
Passo 1 — Planeje seu plano de contas

Na contabilidade tradicional, um Plano de Contas (Chart of Accounts, CoA) é a lista mestra de cada categoria de conta que seu negócio usa: ativos, passivos, receitas e despesas. Ele também define como você classifica cada movimento contra essas categorias. No Midaz não há uma única tela de “Plano de Contas” para preencher. Em vez disso, seu CoA emerge dos blocos que você cria na Console: Assets, Tipos de Conta e Contas. Você o planeja de antemão, principalmente como um exercício de papel (ou quadro branco). Antes de abrir a Console, liste os saldos que seu produto precisa. Para um produto de pagamentos típico, pode ser: Esta lista é seu projeto. Os próximos passos transformam cada linha em algo concreto na Console.
Antes de qualquer Conta poder existir, ela precisa de um Asset — a unidade de valor que mantém (por exemplo BRL). Se você ainda não criou seus assets, comece por Criar um Asset.

​
Passo 2 — Crie seus Tipos de Conta

Os Tipos de Conta são as categorias que classificam suas Contas. Pense neles como rótulos como customer, treasury ou fee que agrupam Contas pelo seu papel. Mais tarde, as Rotas Contábeis usam esses rótulos para decidir quais Contas uma transação pode usar. Na Console você cria um Tipo de Conta por categoria do seu projeto — não um por cliente individual.

Criar um Tipo de Conta

Abra o formulário Novo Tipo de Conta e defina uma categoria com um nome claro e um key value estável.
Uma configuração de pagamentos típica usa estes Tipos de Conta:
O Key Value de um Tipo de Conta (por exemplo customer) é aquilo de que as rotas e Contas dependem. Mantenha-o curto, em minúsculas e estável — alterá-lo mais tarde significa recriar as Contas e rotas que dependem dele.
O menu de Tipos de Conta aparece somente depois que você habilita Validate Account Type nas configurações do seu Ledger. Para ativá-lo, veja Gerenciar Ledgers.

​
Passo 3 — Crie suas Contas

As Contas são os contêineres de saldo — as coisas que mantêm valor e entre as quais o dinheiro se move. Cada Conta tem um campo Tipo obrigatório e um Asset (sua moeda). Quando Validate Account Type está habilitado, o Tipo de uma Conta não externa deve corresponder a um Tipo de Conta registrado (Contas externas ignoram essa verificação). Um alias legível a identifica (por exemplo customer_123_brl). Para cada linha do seu projeto, crie uma Conta na Console.

Criar uma Conta

Abra o formulário Nova Conta, escolha seu Tipo e Asset, e dê a ela um alias claro.
Ao preencher o formulário, algumas escolhas são permanentes e vale a pena acertar de primeira:
A Console bloqueia Apelido da Conta, Tipo e Asset quando você salva a Conta. Para alterar algum deles, crie uma nova Conta. Confira duas vezes antes de salvar.

​
Entendendo o que um saldo realmente mostra

Quando você abre uma Conta na Console, seu saldo não é um único número. O Midaz divide cada saldo em dois buckets. Você sempre sabe o que pode gastar e o que o ledger retém. Em linguagem simples: Ambos os valores aparecem como decimais exatos (por exemplo, 12.50). Não há nenhum fator de escala a aplicar na leitura.
On hold viabiliza os pagamentos em duas etapas. Quando você autoriza um pagamento mas ainda não o captura, o valor passa de Available para On hold. Confirmar o pagamento o libera ao destino. Cancelar o devolve ao Available. Você vê cada um desses movimentos na Conta em cada etapa.

​
Passo 4 — Crie suas Rotas Contábeis

Com Validate Routes habilitado, cada transação deve especificar uma Rota Contábil válida no ledger. Uma rota é uma regra reutilizável para um tipo de transação, como um Pix transfer ou um fee charge. Ela responde a três perguntas:
  • Quais Contas podem enviar no lado source?
  • Quais Contas podem receber no lado destination?
  • Quais lançamentos de débito e crédito o ledger deve registrar quando ela é executada?
A Console as constrói por meio de um assistente guiado de 3 passos, então você não precisa montar nada manualmente.

Gerenciar Rotas Contábeis

Veja como a página de Rotas Contábeis funciona e o que cada parte do assistente faz.

Criar uma Rota Contábil

Percorra o assistente de 3 passos para definir uma rota, suas operation rules e seus lançamentos.
Para decidir como modelar uma rota, veja Regras contábeis — ela explica as escolhas em termos simples. O essencial:
Cada regra dentro de uma rota se aplica a um lado da transação:
  • Source — o lado de envio (de onde o valor vem).
  • Destination — o lado de recebimento (onde o valor chega).
  • Bidirectional — a mesma regra se aplica a ambos os lados, para casos em que um tipo de Conta pode tanto enviar quanto receber.
Uma rota válida precisa de pelo menos um Source e um Destination, ou uma única regra Bidirectional.
Cada regra verifica as Contas de uma de duas formas:
  • Account Type — a regra aceita qualquer Conta de uma categoria (por exemplo, qualquer Conta customer pode enviar). Use para fluxos flexíveis e escaláveis.
  • @Alias — a regra aceita apenas uma Conta exata (por exemplo, apenas @fee_revenue pode receber). Use para Contas operacionais fixas como treasury, fees ou settlement.
Os scenarios decidem como os lançamentos de débito e crédito são registrados:
  • Direct — um movimento em uma etapa, registrado de imediato.
  • Two-Step — um fluxo de hold e depois commit. Usa lançamentos separados para reservar, confirmar e cancelar fundos, e impulsiona o bucket On hold.
  • Reversal — lançamentos que o ledger registra para desfazer uma transação concluída.
  • Overdraft — lançamentos que o ledger registra quando um débito excede os fundos disponíveis da conta e utiliza uma linha de cheque especial.
  • Bloqueio — lançamentos que o ledger registra quando valores de uma conta são bloqueados ou desbloqueados.
Ative Validate Routes nas configurações do Ledger somente depois de que as rotas que você precisa já existam. Se a validação estiver ativa mas faltar uma rota correspondente, essas transações vão falhar.

​
Juntando tudo — um pagamento Pix simples

Vamos executar o fluxo completo na Console para um Pix cash-out básico: um cliente envia BRL da sua wallet para uma conta de liquidação. Assuma que seu asset BRL já existe.
1

Crie os Tipos de Conta

Na página Tipos de Conta, crie:
  • customer — para saldos de usuários finais.
  • settlement — para fundos saindo para o mundo externo.
Veja Criar um Tipo de Conta.
2

Crie as Contas

Na página Contas, crie:
  • @customer_123_brl — Tipo customer, Asset BRL. A wallet do cliente.
  • @external_brl — Tipo settlement, Asset BRL. Onde os fundos se assentam ao sair do ledger.
Veja Criar uma Conta.
@external_brl é uma Conta de liquidação normal, de propriedade do ledger. Este exemplo a usa para que a rota possa validar o Tipo de Conta settlement. Ela não é a Conta externa canônica @external/BRL, que o Midaz cria automaticamente junto com o Asset BRL; o prefixo de alias @external/ é reservado, então você não pode criar essa Conta por conta própria. Para o dinheiro que realmente entra ou sai do Midaz, use @external/BRL. Veja Erros comuns a evitar.
3

Crie a Rota Contábil

Na página Rotas Contábeis, inicie o assistente e construa uma rota Pix cash-out:
  • Uma operation rule Source validando o Tipo de Conta customer (a wallet envia).
  • Uma operation rule Destination validando o Tipo de Conta settlement (a conta de liquidação recebe).
  • Um accounting scenario Direct, com um lançamento de débito no source e um de crédito no destination.
Veja Criar uma Rota Contábil.
4

Execute uma transação

Crie uma transação que mova, por exemplo, 100.00 BRL de @customer_123_brl para @external_brl usando sua rota Pix cash-out. Veja Criar uma Transação.
5

Confira o resultado

Abra cada Conta e olhe o saldo:
  • @customer_123_brl — Available cai 100.00.
  • @external_brl — Available sobe 100.00.
Ambos os movimentos compartilham a mesma transação, dando a você uma trilha de auditoria limpa e balanceada.
Precisa de um fluxo de autorizar e depois capturar em vez de um instantâneo? Use um scenario Two-Step na rota. Você verá o valor se mover para On hold ao reservá-lo, e sair de lá quando confirmar ou cancelar.

​
Próximos passos

Agora você tem um modelo contábil funcionando, construído inteiramente na Console. Para ir mais fundo, use estas referências técnicas. Elas cobrem como automatizar a configuração, entender as entidades e transformar a atividade do ledger em relatórios:

Passo a Passo de Contabilidade (desenvolvedor)

A versão de desenvolvedor de ponta a ponta deste guia, incluindo o modelo de dados e o detalhe de partidas dobradas.

Visão geral de Contabilidade

Como os primitivos contábeis centrais se relacionam entre si.

Entidades de Transaction Routing

O modelo técnico por trás das Rotas Contábeis, operation routes e lançamentos.

Saldos

O modelo de saldo completo por trás de available e on-hold.