Pular para o conteúdo principal
Este guia conduz você passo a passo pela configuração da contabilidade no Módulo Midaz da Lerian Console, usando apenas as telas e formulários da Console. É o complemento Console do Passo a Passo de Contabilidade voltado a desenvolvedores: o mesmo destino, mas expresso como o que você clica e configura, não o que você envia a uma API. Foi escrito para product managers, times de implementação e desenvolvedores que preferem modelar sua contabilidade na UI em vez de montar payloads de API crus. Mantemos os termos técnicos onde importam, mas sempre explicamos o que significam quando você os vê na tela.
Você não verá nenhum JSON ou chamada de API aqui. Tudo abaixo é feito por meio dos formulários da Console. Se mais tarde quiser automatizar a mesma configuração, cada seção tem link para a referência técnica correspondente.

​
O que você está construindo

A contabilidade no Midaz é baseada nas partidas dobradas. Você não precisa fazer a contabilidade manualmente — a Console e o ledger garantem isso para você. A única regra a ter em mente:
Toda transação move valor de um lugar para outro. Um lado dá (débito), um lado recebe (crédito), e os dois sempre se equilibram.
Você configura isso uma vez modelando suas Contas e seu roteamento, e a partir daí toda transação fica automaticamente balanceada e auditável. 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 ligado a um Tipo de Conta e a um Asset.
4

Crie as Rotas Contábeis

Defina as regras que dizem quais Contas podem participar de cada transação e como os lançamentos são registrados.
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, despesas — e como os movimentos são classificados contra elas. No Midaz não há uma única tela de “Plano de Contas” para preencher. Em vez disso, seu CoA emerge de como você combina os blocos que cria na Console: Assets, Tipos de Conta e Contas. Planejá-lo de antemão é principalmente 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:
Saldo que você precisaO que representa
Fundos de clientesDinheiro que seus usuários finais mantêm
SettlementFundos aguardando compensação
Fee revenueFees que você cobra
Fee expenseFees que você paga a provedores
TreasurySeus próprios fundos operacionais internos
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 são permitidas em uma transação. 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:
Tipo de ContaUse para
customerSaldos líquidos de clientes
settlementFundos aguardando compensação
feeFees cobradas como revenue
treasuryOperações internas
expenseFees pagas a provedores
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 só aparece quando Validate Account Type está habilitado nas configurações do seu Ledger. Veja Gerenciar Ledgers para ativá-lo.

​
Passo 3 — Crie suas Contas

As Contas são os contêineres de saldo reais — as coisas que mantêm valor e entre as quais o dinheiro se move. Cada Conta está ligada a um Tipo de Conta (sua categoria) e a um Asset (sua moeda), e é identificada por um alias legível que começa com @ (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:
CampoPor que importa
Alias da ContaO nome que rotas e transações usam para encontrar a Conta. Não pode ser alterado após a criação.
TipoO Tipo de Conta que a classifica. Não pode ser alterado após a criação.
AssetA moeda ou unidade que ela mantém. Não pode ser alterado após a criação.
Alias, Tipo e Asset ficam bloqueados assim que a Conta é salva. Se precisar alterar algum deles, você terá que criar 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 alguns buckets para que você sempre saiba o que é genuinamente gastável versus o que está reservado. Em linguagem simples:
BucketO que significa quando você olha uma Conta
AvailableDinheiro livre para gastar ou enviar agora mesmo. É o número que sobe e desce com os pagamentos normais.
On holdDinheiro que foi reservado por uma operação pendente mas ainda não finalizada. Ainda pertence à Conta, mas está separado e não pode ser gasto até que o hold seja confirmado ou cancelado.
ScaleNão é um pool de dinheiro — diz à Console quantas casas decimais ler. Com um scale de 2, um valor armazenado de 100 significa 1.00. Controla a precisão, não o valor.
“On hold” é o que viabiliza os pagamentos em duas etapas. Quando um pagamento é autorizado mas ainda não capturado, o valor passa de Available para On hold. Confirmar o pagamento o libera ao destino; cancelar o devolve ao Available. Você verá esses movimentos refletidos na Conta em cada etapa.

​
Passo 4 — Crie suas Rotas Contábeis

As Rotas Contábeis são as regras que governam toda transação antes de ela impactar o ledger. Uma rota é uma regra reutilizável para um tipo de transação (por exemplo, Pix transfer ou fee charge) que responde a três perguntas:
  • Quais Contas são permitidas no lado source (envio)?
  • Quais Contas são permitidas no lado destination (recebimento)?
  • Quais lançamentos de débito e crédito devem ser registrados 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.
Se você ainda está decidindo como modelar uma rota, Regras contábeis 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 — qualquer Conta de uma categoria é permitida (por exemplo, qualquer Conta customer pode enviar). Use para fluxos flexíveis e escaláveis.
  • @Alias — apenas uma Conta exata é permitida (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, com lançamentos separados para reservar, confirmar e cancelar fundos (é isso que usa o bucket On hold).
  • Reversal — lançamentos registrados quando uma transação concluída precisa ser desfeita.
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 externa. 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.
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 externa 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. Se quiser ir mais fundo — automatizar a mesma configuração, entender as entidades subjacentes ou transformar a atividade do ledger em relatórios — estas referências técnicas continuam de onde este guia para:

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, on-hold e scale.