Skip to main content
Uma Conta é a unidade financeira principal de um Ledger do 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 > Portfólio: Você pode agrupar Contas em Portfólios para representar grupos de clientes, linhas de produto ou unidades de negócio.
  • Conta > Ativo: Cada Conta se vincula a um único Ativo. O Ativo define o tipo de valor que a Conta guarda, 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 Tipos de Conta para 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.
  • Toda 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 em uma conta compartilhada. Crie uma conta separada sempre que um saldo precisar de sua própria verdade. O mesmo cliente pode ter saldos que se comportam de forma diferente:
  • Natureza diferente: um saldo principal, um saldo de benefício ou um saldo promocional.
  • Regras operacionais diferentes: uma conta bloqueada ou por ordem judicial que aceita entradas mas restringe saídas.
  • Extrato e conciliação separados: uma subconta de produto ou compartimento que você acompanha de forma independente.
Quando o saldo, o ledger, o extrato ou a regra são diferentes, cada um se torna sua própria Conta. Você a classifica por um Tipo de Conta, a agrupa sob o cliente com um Portfólio e a vincula à identidade pelo CRM. Uma conta com rótulos funciona até os saldos divergirem. Contas separadas mantêm cada saldo correto 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, geralmente de e para usuários, parceiros ou provedores financeiros. Contas externas têm estas características:
  • Guardam o saldo da contraparte do dinheiro que entra ou sai do seu ledger.
  • Podem representar uma posição externa negativa. Quando uma conta externa usa overdraft, a posição derivada dela pode ficar negativa. O saldo Available persistido permanece em zero e o Midaz rastreia 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.
Essas contas registram entradas e saídas na fronteira do ledger.
Não tente excluir ou 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 funciona como chave de busca. Você pode buscar essa Conta canônica e os saldos dela com endpoints de conveniência que aceitam apenas o código do ativo:
  • GET .../accounts/external/{code}: Busca a conta externa de um código de ativo (por exemplo, BRL resolve para @external/BRL).
  • GET .../accounts/external/{code}/balances: Busca os saldos dessa conta externa.
Esses endpoints são atalhos para a Conta externa canônica. Eles adicionam @external/ antes do código que você informa e então fazem uma busca baseada no alias. O resultado é idêntico a uma consulta por esse alias completo.

​
Entity ID (referência de sistema externo)

O campo entityId existe em qualquer conta, não apenas em contas externas. Ele vincula a conta a um registro em um sistema externo, como uma plataforma de core banking, um CRM ou um sistema parceiro.
  • Não é o mesmo que o alias: Você usa o alias nas 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 movimentar valor.
  • Opcional: Defina-o quando criar a conta ou quando atualizá-la. O tamanho máximo é 256 caracteres.
  • Caso de uso: Quando o seu sistema já tem um identificador de conta, como EXT-ACC-12345, armazene-o em entityId. Assim você consegue 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 tradicional de pai e filho ou para outro relacionamento que o seu negócio precisar.

​
Aliases de conta

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

​
Use o Alias da Conta nas Transações

Quando você cria uma transação, sempre use 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 informar um, o Midaz usa o ID da conta como alias. Uma Conta externa criada pelo usuário exige um alias. Assim, toda conta tem um alias único.

​
Gerenciando Contas

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

​
Pela API

Transfira qualquer saldo restante para outra conta antes de excluir uma conta. O Midaz não exclui uma conta ou subconta que ainda tenha saldo.

​
Pelo Lerian Console

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