Skip to main content
Este guia mostra como configurar a contabilidade no módulo Midaz do Console da Lerian. Você usa apenas as telas e os formulários do Console, sem escrever código. É o complemento, no Console, do Passo a passo de contabilidade, voltado a desenvolvedores. Você chega ao mesmo resultado pelos formulários do Console, em vez de chamadas de API. Destina-se a gerentes de produto, equipes de implementação e desenvolvedores que preferem modelar a contabilidade pela interface.
Você não vai ver nenhum JSON ou chamada de API aqui. Você faz tudo abaixo pelos formulários do Console. Para automatizar essa mesma configuração depois, siga a referência técnica de cada seção.

​
O que você vai construir

Configure suas rotas contábeis com cuidado. 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 apenas depois de configurar as rotas que seu Ledger precisa. O cancelamento é uma ação de ciclo de vida apenas de origem: ele libera fundos retidos na Conta de origem e não envolve uma Conta de destino. Cada camada se apoia na anterior:
1

Planeje seu plano de contas

Decida quais saldos seu produto precisa (fundos de clientes, tarifas, liquidação, tesouraria, receita).
2

Crie Tipos de Conta

Defina as categorias que classificam suas contas.
3

Crie Contas

Abra os containers de saldo propriamente ditos, cada um com um Tipo e um Ativo. Você seleciona o Tipo para Contas não externas. Quando você habilita Conta externa, o Tipo passa a ser external automaticamente. Quando Validar Tipo de Conta está habilitado, o Tipo de cada Conta não externa deve corresponder a um Tipo de Conta registrado.
4

Crie Rotas Contábeis

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

​
Etapa 1: Planeje seu plano de contas

Na contabilidade tradicional, um Plano de Contas (Chart of Accounts, CoA) é a lista mestra de todas as categorias de conta que sua empresa usa: ativos, passivos, receita e despesas. Ele também define como você classifica cada movimentação dentro dessas categorias. No Midaz não existe uma única tela de “Plano de Contas” para preencher. Em vez disso, seu plano de contas surge dos blocos de construção que você cria no Console: Ativos, Tipos de Conta e Contas. Você o planeja antecipadamente, principalmente como um exercício em papel (ou quadro branco). Antes de abrir o Console, liste os saldos que seu produto precisa. Para um produto de pagamentos típico, isso pode ser: Essa lista é seu esboço. As próximas etapas transformam cada linha em algo concreto no Console.
Antes que uma conta possa existir, ela precisa de um Ativo, a unidade de valor que ela mantém (por exemplo, BRL). Se você ainda não criou seus ativos, comece por Criando um Ativo.

​
Etapa 2: Crie seus Tipos de Conta

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 papel que elas exercem. Depois, as Rotas Contábeis usam esses rótulos para decidir quais contas uma transação pode usar. No Console, você cria um Tipo de Conta por categoria do seu esboço, 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 valor de chave estável.
Uma configuração de pagamentos típica usa estes Tipos de Conta:
O Valor de Chave de um Tipo de Conta (por exemplo, customer) é o que rotas e contas usam como referência. Mantenha-o curto, em minúsculas e estável. Se você mudá-lo depois, deve recriar as contas e as rotas que dependem dele.
O menu Tipos de Conta aparece apenas depois que você habilita Validar Tipo de Conta nas configurações do seu Ledger. Para habilitá-la, veja Gerenciando Ledgers.

​
Etapa 3: Crie suas Contas

Contas são os containers de saldo que guardam valor e entre os quais o dinheiro se movimenta. Cada conta tem um Tipo e um Ativo (sua moeda). Você seleciona o Tipo para Contas não externas. Quando você habilita Conta externa, o Tipo passa a ser external automaticamente. Quando Validar Tipo de Conta está habilitado, o Tipo de uma Conta não externa deve corresponder a um Tipo de Conta registrado (Contas externas não passam por essa verificação). Um alias legível por humanos a identifica. @customer_123_brl é uma convenção comum. Para cada linha do seu esboço, crie uma Conta no Console.

Criar uma Conta

Abra o formulário Nova Conta, escolha o Tipo e o Ativo dela, e dê a ela um alias claro.
Ao preencher o formulário, algumas escolhas são permanentes e vale a pena acertar já na primeira vez:
O Console trava o Alias, o Tipo e o Ativo quando você salva a conta. Para alterar qualquer um deles, crie uma nova conta. Confira tudo antes de salvar.

​
Entendendo o que um saldo realmente mostra

Quando você abre uma conta no Console, o Midaz divide o saldo dela em dois grupos. Você sempre sabe o que pode gastar e o que o ledger retém: Os dois valores aparecem como valores decimais exatos (por exemplo, 12.50). Não há fator de escala para aplicar quando você os lê.
Retido viabiliza pagamentos em duas etapas. Quando você autoriza um pagamento, mas ainda não o captura, o valor se move de Disponível para Retido. Confirmar o pagamento o libera para o destino. Cancelar o devolve para Disponível. Você vê cada uma dessas movimentações na conta em cada etapa.

​
Etapa 4: Crie suas Rotas Contábeis

Com Validar Rotas habilitado, cada transação deve especificar uma Rota Contábil válida no ledger. Uma Rota Contábil é uma regra reutilizável para um tipo de transação, como uma transferência Pix ou uma cobrança de tarifa. Ela responde a três perguntas:
  • Quais contas podem enviar no lado de origem?
  • Quais contas podem receber no lado de destino?
  • Quais lançamentos de débito e crédito o ledger deve registrar quando ela roda?
O Console constrói isso por meio de um assistente guiado de 3 etapas, então você não precisa montar nada manualmente.

Gerenciar Rotas Contábeis

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

Criar uma Rota Contábil

Percorra o assistente de 3 etapas para definir uma rota, suas regras de operação e seus lançamentos.
Para decidir como moldar uma rota, veja Regras contábeis. Ele explica as escolhas em termos simples.
Cada regra dentro de uma rota se aplica a um lado de uma transação:
  • Origem: o lado que envia (de onde o valor vem).
  • Destino: o lado que recebe (onde o valor chega).
  • Bidirecional: a mesma regra se aplica aos dois lados, para os casos em que um tipo de conta pode tanto enviar quanto receber.
Uma rota válida precisa de pelo menos uma regra de Origem e uma de Destino, ou de uma única regra Bidirecional.
Cada regra verifica contas de uma das duas formas:
  • Tipo de Conta: a regra aceita qualquer conta de uma dada categoria (por exemplo, qualquer conta customer pode enviar). Use isso para fluxos flexíveis e escaláveis.
  • @Alias: a regra aceita apenas uma conta exata (por exemplo, apenas @fee_revenue pode receber). Use isso para contas operacionais fixas, como tesouraria, tarifas ou liquidação.
Os cenários decidem como os lançamentos de débito e crédito são registrados:
  • Direto: um movimento de uma única etapa, registrado imediatamente.
  • Duas Etapas: um fluxo de retenção e depois confirmação. Ele usa lançamentos separados para reservar, confirmar e cancelar fundos, e movimenta o grupo Retido.
  • Estorno: 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 recorre a uma linha de overdraft.
  • Bloqueio: lançamentos que o ledger registra quando fundos em uma conta são bloqueados ou desbloqueados.
Habilite Validar Rotas nas configurações do Ledger apenas depois que as rotas necessárias já existirem. Se a validação estiver ativa e faltar uma rota correspondente, essas transações vão falhar.

​
Exemplo: um pagamento Pix simples

Vamos rodar o fluxo completo no Console para um cash-out Pix básico: um cliente envia BRL da carteira dele para uma conta de liquidação. Suponha que seu ativo BRL já exista.
1

Crie os Tipos de Conta

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

Crie as Contas

Na página Contas, crie:
  • @customer_123_brl: Tipo customer, Ativo BRL. A carteira do cliente.
  • @external_brl: Tipo settlement, Ativo BRL. Onde os fundos se liquidam quando saem do ledger.
Veja Criando uma Conta.
@external_brl é uma Conta de liquidação comum, pertencente ao ledger. Este exemplo a usa para que a rota consiga validar o Tipo de Conta settlement. Ela não é a Conta externa canônica @external/BRL, que o Midaz cria automaticamente junto com o Ativo BRL. O prefixo de alias @external/ é reservado, então você não pode criar essa Conta você mesmo. Para 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 regra de operação de Origem validando o Tipo de Conta customer (a carteira envia).
  • Uma regra de operação de Destino validando o Tipo de Conta settlement (a conta de liquidação recebe).
  • Um cenário contábil Direto, com um lançamento de débito na origem e um lançamento de crédito no destino.
Veja Criando uma Rota Contábil.
4

Rode uma transação

Crie uma transação que move, digamos, 100.00 BRL de @customer_123_brl para @external_brl usando sua rota Pix cash-out. Veja Criando uma Transação.
5

Confira o resultado

Abra cada conta e observe o saldo:
  • @customer_123_brl: Disponível cai 100.00.
  • @external_brl: Disponível sobe 100.00.
As duas movimentações pertencem à mesma transação, então a trilha de auditoria permanece equilibrada.
Para um fluxo de autorização seguida de captura, use um cenário Duas Etapas na rota. Você vê o valor se mover para Retido quando reservado, e sair dele quando você confirma ou cancela.

​
O que fazer a seguir

Para se aprofundar, 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 completa, de ponta a ponta e voltada a desenvolvedores, deste guia, incluindo o modelo de dados e o detalhe de partidas dobradas.

Contabilidade

Como as primitivas contábeis centrais se relacionam entre si.

Rotas Contábeis

O modelo técnico por trás das Rotas Contábeis, das rotas de operação e dos lançamentos.

Saldos

O modelo completo de saldo por trás dos valores disponíveis e retidos.