Skip to main content
Uma Conta é a unidade financeira central de um Ledger Midaz. Cada Conta se vincula a um Ativo e registra cada débito, crédito e saldo desse Ativo. Em termos bancários, uma Conta é um produto financeiro, como uma conta corrente, uma conta poupança ou uma conta de empréstimo.
O Midaz não limita quantas contas você cria. Crie quantas a sua estrutura precisar.

​
Estrutura da Conta

  • Conta > Ledger: Você cria uma Conta dentro de um Ledger. O Ledger rastreia e consolida todos os saldos e operações.
  • Conta > Portfolio: Você pode agrupar Contas em Portfólios para representar grupos de clientes, linhas de produtos ou unidades de negócios.
  • Conta > Ativo: Cada Conta se vincula a um único Ativo. O Ativo define o tipo de valor que a Conta mantém, como BRL, USD, BTC ou pontos de fidelidade.
  • Conta > Tipo de Conta: Quando você habilita a validação de Tipo de Conta, cada Conta não externa deve usar um Tipo de Conta registrado. Você registra os Tipos de Conta conforme a sua classificação de negócio.

​
Características principais

  • Cada Conta se vincula a exatamente um tipo de Ativo.
  • Cada Conta tem um identificador único dentro de um Ledger.
  • Cada transação registra débitos e créditos entre Contas.

​
Várias contas por cliente

Um único cliente costuma ter mais de um saldo. O Midaz modela cada saldo como sua própria Conta, não como rótulos sobre um saldo compartilhado. A regra que orienta: crie uma conta separada sempre que um saldo precisar ter sua própria verdade. O mesmo cliente pode manter saldos que se comportam de forma diferente:
  • Natureza diferente — um saldo principal, um saldo benefício ou um saldo promocional.
  • Regras operacionais diferentes — uma conta judicial ou bloqueada que aceita entradas mas restringe saídas.
  • Extrato e conciliação separados — uma subconta de produto ou pocket que você acompanha por conta própria.
Quando o saldo, o ledger, o extrato ou a regra difere, cada um vira sua própria Conta. Você a classifica por um Tipo de Conta, a agrupa sob o cliente com um Portfolio e a vincula à identidade pelo CRM. Uma conta com rótulos funciona até os saldos divergirem. Contas separadas mantêm cada saldo preciso desde o início.
Para a arquitetura de referência completa — um cliente, várias contas, com exemplos passo a passo — veja Midaz para clientes com várias contas.

​
Conta Externa

Contas Externas no Midaz representam contas fora da estrutura da sua organização. Elas rastreiam dinheiro que entra ou sai do seu ledger, normalmente de e para usuários, parceiros ou provedores financeiros. As contas externas têm estas características:
  • Mantêm o saldo de contraparte do dinheiro que entra ou sai do seu ledger.
  • Podem representar uma posição externa negativa. Quando uma conta externa usa overdraft, sua posição derivada pode ser negativa; o saldo persistido Available permanece em zero e o Midaz registra o uso em OverdraftUsed.
  • O Ledger cria uma Conta externa canônica automaticamente quando você cria um Ativo.
  • A Conta externa canônica segue um padrão de nomenclatura claro: @external/<asset-code>, como @external/BRL.
Na prática, essas contas funcionam como a ponte entre o seu sistema e o mundo externo. Elas registram entradas e saídas no limite do ledger.
Não tente excluir nem alterar uma conta externa. O Midaz bloqueia essas operações para manter o Ledger preciso e rastreável.

​
Códigos de conta externa

A Conta externa canônica criada com um Ativo segue o padrão de nomenclatura @external/<asset-code>. O código do ativo nesse alias atua como chave de busca. Você pode recuperar essa Conta canônica e seus saldos com endpoints de conveniência que aceitam apenas o código do ativo:
  • GET .../accounts/external/{code} — Recupera a conta externa para um código de ativo (por exemplo, BRL resolve para @external/BRL).
  • GET .../accounts/external/{code}/balances — Recupera os saldos dessa conta externa.
Esses endpoints são atalhos para a Conta externa canônica. Eles prefixam @external/ ao código que você fornece e então realizam uma busca baseada em alias. O resultado é idêntico ao de uma consulta por esse alias completo.

​
Entity ID (referência de sistema externo)

O campo entityId existe em qualquer conta, não apenas nas contas externas. Ele vincula a conta a um registro em um sistema externo, como uma plataforma de core banking, um CRM ou um sistema de parceiro.
  • Não é o mesmo que alias: você usa o alias em transações, e ele deve ser único dentro de um ledger. O entityId é apenas uma referência para a sua integração, e o Midaz não o usa para mover valor.
  • Opcional: defina quando você cria a conta ou quando a atualiza. O comprimento máximo é de 256 caracteres.
  • Caso de uso: quando o seu sistema já tem um identificador de conta, como EXT-ACC-12345, guarde-o em entityId. Assim você pode mapear entre o Midaz e a sua fonte de verdade.

​
ID da Conta Pai

O ID da Conta Pai vincula duas contas dentro do Midaz. Você define o relacionamento com base na sua lógica de negócio. Você pode usá-lo para uma estrutura pai-filho tradicional ou para outro relacionamento que o seu negócio precise.

​
Aliases de Conta

Um alias substitui um ID de conta complexo por um rótulo legível. Isso torna as contas mais fáceis de identificar.
  • Por exemplo: em vez do ID 3172933b-50d2-4b17-96aa-9b378d6a6eac, você pode usar @username_1.

​
Use o Alias da Conta em Transações

Quando você cria uma transação, use sempre o alias da conta no campo account. Não use o ID da conta. Um alias é opcional quando você cria uma Conta não externa. Se você não o definir, o Midaz usa o ID da conta como alias. Uma Conta externa criada pelo usuário exige um alias. Cada conta então tem um alias único.

​
Gerenciando Contas

Você pode gerenciar suas Contas via API ou pelo Lerian Console.

​
Via API

Transfira qualquer saldo remanescente para outra conta antes de excluir uma conta. O Midaz não exclui uma conta nem uma subconta que ainda mantém um saldo.

​
Via Lerian Console

Você pode visualizar, criar, editar e excluir Contas na página de Contas. Essa página fica no módulo Midaz do Lerian Console. Saiba mais no guia de Gerenciamento de Contas.