Pular para o conteúdo principal
Um Ledger mantém um registro preciso de todas as Transações e Operações de uma Organização. Um Ledger rastreia cada evento financeiro: depósitos, saques, transferências e tarifas. As Organizações podem usar vários Ledgers para segregar operações financeiras. Por exemplo, um banco mantém Ledgers separados para diferentes linhas de negócio, regiões ou exigências regulatórias. Um único Ledger também pode lidar com todas as operações, para uma configuração mais simples.

​
Estrutura do Ledger

  • Ledger > Organização: Cada Organização pode ter vários Ledgers, mas cada Ledger pertence a apenas uma Organização.
    • Use vários Ledgers apenas quando você precisar segregar dados ou operações, por exemplo operações internas de tesouraria versus contas de clientes.
Por padrão, uma transação não pode mover fundos entre Ledgers. Uma transação pode abranger vários Ledgers apenas quando cada Ledger envolvido habilita a configuração crossLedger.enabled.

​
Como orquestrar transações entre Ledgers

Quando cada Ledger envolvido habilita crossLedger.enabled, envie uma transação direct ou hold pela API v2. Cada perna informa o organizationId e o ledgerId da sua conta. O Midaz divide a transferência em uma transação balanceada por Ledger:
  1. Débito do Ledger de origem: A conta no Ledger 1 envia o valor para a Conta Externa do Ledger 1 (@external/<asset>).
  2. Crédito no Ledger de destino: A Conta Externa do Ledger 2 envia o valor para a conta de destino.
As transações compartilham um único groupId. Em uma transação direct, elas são concluídas ou falham juntas.

​
Características principais

  • Todas as Contas e Transações existem dentro de um Ledger.
  • Cada Ledger mantém um conjunto equilibrado de Contas.
  • Você pode usar vários Ledgers para segmentação, mas transações entre ledgers precisam de tratamento explícito.

​
Vários Ledgers

O Midaz permite criar vários Ledgers para cada organização. Por exemplo, uma empresa pode separar os registros financeiros por país, departamento ou função de negócio.

​
Exemplo de caso de uso

Considere uma empresa global com negócios em várias regiões:
  • Ledger 1: negócios nos EUA
  • Ledger 2: negócios na UE
  • Ledger 3: negócios na APAC
Com Ledgers separados, a empresa mantém registros de transação, regras fiscais e configurações de moeda específicos de cada região. Ainda assim, ela tem uma supervisão unificada de todas as operações.

​
Quando criar um novo Ledger

Um Ledger é um limite rígido. Todo movimento entre Ledgers passa pela Conta Externa de cada Ledger (veja Como orquestrar transações entre Ledgers). Esse custo orienta a decisão. Crie um novo Ledger apenas quando os segmentos raramente movimentam dinheiro entre si. Use esta heurística para escolher o nível certo de separação: Se dois conjuntos de saldos transacionam entre si com frequência, mantenha-os no mesmo Ledger. Separe-os com Portfólios ou Contas. Divida em vários Ledgers apenas quando o isolamento valer a sobrecarga de orquestração.

​
Personalizando Ledgers

No Midaz, você pode adaptar a configuração de cada Ledger às suas necessidades. Os Ativos são vinculados a um Ledger, então o mesmo código é um registro independente em cada Ledger, com seu próprio nome, tipo, status e metadados. Exemplo Para representar o Bitcoin (BTC) em vários Ledgers, crie o ativo BTC de forma independente em cada Ledger e defina o nome, o status e os metadados que cada Ledger precisa.
Os valores no Midaz são decimais de precisão arbitrária. Não existe uma configuração de casas decimais por ativo ou por Ledger. Você não configura uma escala ao criar um ativo.

​
Benefícios de usar Ledgers no Midaz

  • Organização clara: mantenha registros financeiros claros e distintos para cada parte do seu negócio.
  • Configurações personalizadas: ajuste as configurações de ativos, moedas ou outros parâmetros por Ledger, para necessidades locais ou departamentais.
  • Escalabilidade: adicione ou altere Ledgers conforme sua organização cresce ou se diversifica.
  • Transparência: tenha uma visão completa de todas as atividades financeiras. Cada Ledger contribui para uma única visão operacional.

​
Configurações do Ledger

Cada Ledger tem configurações ajustáveis que controlam como ele valida transações. Por exemplo, você pode exigir que toda transação siga uma rota predefinida. Você também pode exigir que os tipos de conta correspondam às regras do seu negócio. O Ledger então rejeita movimentos inválidos antes de registrá-los. Você pode alterar essas configurações a qualquer momento pela API. Você não precisa reiniciar o serviço nem alterar código.

​
Configurações disponíveis

Comece com validateAccountType e validateRoutes desabilitadas enquanto você configura suas rotas de operação e rotas de transação. Depois que a configuração de rotas estiver completa, habilite a validação para impor as regras do seu negócio.

​
Como as configurações afetam as transações

Quando você habilita validateRoutes para um Ledger:
  1. Toda transação para esse Ledger deve referenciar uma rota de transação válida.
  2. O Ledger valida cada operação de acordo com as regras da rota de operação correspondente.
  3. O Ledger rejeita qualquer transação não conforme antes de registrar o movimento.
Quando você habilita validateAccountType:
  1. O Ledger verifica cada nova conta de acordo com seus tipos de conta registrados.
  2. Se o tipo de conta não estiver registrado, o Ledger rejeita a criação da conta.
Se você habilitar a validação em um Ledger que já processa transações, os registros existentes não mudam. A validação se aplica às requisições que você enviar depois de habilitar a configuração. Isso inclui um commit, cancelamento ou estorno de uma transação anterior.

​
Gerenciando configurações pela API

Use os endpoints de Configurações do Ledger para buscar e atualizar essas configurações:
O Midaz aplica as mudanças com um deep merge e modifica apenas os campos que você incluir na requisição.

​
Gerenciando Ledgers

Você pode gerenciar seus Ledgers pela API ou pelo Lerian Console.

​
Ver API

Quando você exclui um Ledger, o Midaz não o remove permanentemente.Em vez disso, o Midaz define um timestamp deletedAt. O Midaz então exclui o Ledger de toda leitura, e você não pode mais usá-lo. Seu status.code não muda. Isso preserva os dados históricos para trilhas de auditoria. O Midaz rejeita a exclusão de Ledger em um ambiente de produção.

​
Via Lerian Console

Você pode ver, criar, editar e excluir Ledgers na página Ledgers do Módulo Midaz do Lerian Console. Saiba mais no guia Gerenciando Ledgers.
Se você criar seu primeiro Ledger no Lerian Console, você faz isso como parte do fluxo de onboarding. Para saber mais, veja o guia Onboarding do Módulo Midaz.