Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt

Use this file to discover all available pages before exploring further.

Em termos bancários, uma Conta representa um produto financeiro, como uma conta corrente, conta poupança ou conta de empréstimo.
O Midaz permite criar quantas contas sua estrutura exigir. Sem limites, sem restrições; apenas a flexibilidade que você precisa.

​
Estrutura da Conta

  • Conta > Ledger: As Contas são criadas dentro de um Ledger, que rastreia e consolida todos os saldos e operações.
  • Conta > Portfolio: As Contas podem ser agrupadas em Portfólios para representar grupos de clientes, linhas de produtos ou unidades de negócios.
  • Conta > Ativo: Cada Conta está vinculada a um único Ativo, definindo o tipo de valor que ela mantém — como BRL, USD, BTC ou pontos de fidelidade.
  • Conta > Tipo de Conta: Com a validação de Tipo de Conta habilitada, cada Conta deve ser categorizada por um Tipo de Conta que pode ser criado de acordo com necessidades específicas do usuário ou classificação do negócio.

​
Características principais

  • Cada Conta está vinculada a exatamente um tipo de Ativo.
  • As Contas são identificadas de forma única dentro de um Ledger.
  • Todas as transações envolvem débitos e créditos entre Contas.

​
Conta Externa

Contas Externas no Midaz representam contas fora da estrutura da sua organização. Elas são usadas para rastrear dinheiro que está entrando ou saindo, normalmente vinculadas a usuários, parceiros ou provedores financeiros fora do seu ledger interno. Mas elas são mais do que simples marcadores. Contas externas:
  • Gerenciam saldos temporários durante operações envolvendo partes externas.
  • São as únicas contas que podem ficar negativas, o que sinaliza que os fundos estão em trânsito.
  • São criadas automaticamente pelo Ledger sempre que você cria um Ativo.
  • Seguem um padrão de nomenclatura claro: @external/<asset-code>, como @external/BRL.
Na prática, essas contas funcionam como pontes entre o seu sistema e o mundo externo, lidando com entradas, saídas e tudo entre eles com clareza e controle.
Para manter o Ledger preciso e confiável, contas externas não podem ser excluídas ou alteradas.

​
Códigos de conta externa

Toda conta externa segue o padrão de nomenclatura @external/<asset-code>. O asset code no alias atua como chave de lookup da conta externa — você pode recuperar a conta e seus saldos usando endpoints de conveniência que aceitam apenas o asset code:
  • GET .../accounts/external/{code} — Recupera a conta externa para um asset code (por exemplo, BRL resolve para @external/BRL).
  • GET .../accounts/external/{code}/balances — Recupera os saldos dessa conta externa.
Esses endpoints são atalhos — eles prefixam @external/ ao código que você fornece e realizam um lookup baseado em alias. O resultado é idêntico ao de consultar pelo alias completo.

​
Entity ID (referência de sistema externo)

O campo entityId em qualquer conta (não apenas em contas externas) permite vinculá-la 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: aliases são usados em transações e precisam ser únicos dentro de um ledger. entityId é puramente informativo — uma referência para sua integração, não usado internamente pelo Midaz.
  • Opcional: defina na criação ou via atualização. Máximo 256 caracteres.
  • Caso de uso: quando seu sistema já possui um identificador de conta (por exemplo, EXT-ACC-12345), guarde-o em entityId para conseguir mapear entre o Midaz e a sua source of truth.
{
  "name": "User Checking Account",
  "assetCode": "BRL",
  "alias": "@user/checking_123",
  "entityId": "EXT-ACC-12345",
  "type": "checking"
}

​
ID da Conta Pai

O ID da Conta Pai vincula duas contas dentro do Midaz, dando a você a flexibilidade de definir o relacionamento com base na sua lógica de negócio. Seja para representar uma estrutura pai-filho tradicional ou algo completamente diferente, a escolha é sua. O Midaz fornece a base — você decide como construir sobre ela.

​
Aliases de Conta

Aliases facilitam a identificação de contas substituindo IDs complexos por rótulos legíveis e amigáveis.
  • Por exemplo: Em vez de referenciar uma conta como 3172933b-50d2-4b17-96aa-9b378d6a6eac, você pode simplesmente usar @username_1.

​
Use o Alias da Conta em Transações

Ao criar uma transação, sempre use o alias da conta no campo account — não o ID da conta. Atribuir um alias ao criar uma conta é opcional. Se você não fizer isso, sem problemas — o sistema usará automaticamente o ID da conta como alias. De qualquer forma, toda conta acaba com um alias único. Então, quando for referenciar uma conta em uma transação, basta usar o alias. Limpo, consistente e pronto para uso.

​
Gerenciando Contas

Você pode gerenciar suas Contas via API ou através do Lerian Console.

​
Via API

Você não pode desativar uma conta com saldo remanescente. Primeiro, transfira o valor para outra conta antes de desativá-la.

​
Via Lerian Console

Todas as ações de gerenciamento de Contas, incluindo visualização, criação, edição e exclusão, podem ser feitas através da página de Contas no Módulo Midaz do Lerian Console. Saiba mais no guia de Gerenciamento de Contas.