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.

Um Saldo representa o valor mantido por uma conta específica no Midaz. Ele reflete o resultado de todas as operações (débitos e créditos) executadas ao longo do tempo, e está sempre vinculado a um Ativo específico, como BRL, USD ou BTC.

​
Múltiplos saldos

Uma única conta pode manter vários saldos, cada um identificado por uma chave única. Isso permite que instituições segmentem fundos sem criar múltiplas contas para o mesmo cliente.
Contas externas não podem ter múltiplos saldos. Cada conta externa está limitada a um único saldo.
Casos de uso típicos incluem:
  • Reservas de investimento
  • Limites de crédito
  • Fundos de garantia (bloqueados)
  • Fundos operacionais do dia a dia
Essa abordagem (Figura 1) aumenta a flexibilidade enquanto mantém o modelo de partidas dobradas (débito e crédito) intacto, garantindo consistência contábil, rastreabilidade e transparência.
Account Multiple Balances Jp
Se nenhum balanceKey for fornecido em uma transação, o Midaz usa automaticamente o saldo padrão da conta.

​
Balance key

Cada saldo é identificado por um campo key que o identifica de forma única dentro da conta.
  • Comprimento máximo: 100 caracteres — espaços em branco não são permitidos.
  • Chave padrão: "default" — atribuída automaticamente quando uma conta é utilizada pela primeira vez em uma transação.
  • Unicidade: As chaves devem ser únicas por conta. Tentar criar um saldo com uma chave que já existe na mesma conta retorna um erro.
  • Em transações: Se nenhum balanceKey for especificado em uma transação, o Midaz usa automaticamente o saldo com a chave "default".
O campo key é definido no momento da criação e não pode ser alterado. Escolha chaves descritivas como "credit", "collateral" ou "savings" para tornar seu modelo de saldos autodocumentado.

​
Permission flags

Cada saldo possui dois permission flags independentes que controlam se ele pode participar em transações:
FlagTipoDescrição
allowSendingbooleanSe fundos podem ser enviados a partir deste saldo
allowReceivingbooleanSe fundos podem ser recebidos neste saldo
Estes são flags por saldo — aplicam-se a um saldo específico, não à conta como um todo. Ambos têm valor padrão true quando não especificados. Casos de uso comuns:
  • Congelar um saldo: Defina allowSending e allowReceiving como false para bloquear qualquer movimentação.
  • Saldo somente para recebimento: Defina allowSending como false para bloquear transferências de saída enquanto ainda aceita entradas.
  • Saldo somente para envio: Defina allowReceiving como false para impedir que novos fundos entrem neste saldo.
Ambos os flags podem ser definidos na criação do saldo e atualizados de forma independente pelo endpoint Atualizar um Saldo. Omitir um flag em uma solicitação de atualização mantém seu valor atual inalterado.
Os permission flags são avaliados no momento da transação. Alterar um flag afeta apenas as transações futuras — não tem efeito sobre operações já processadas.

​
Exemplos de uso

  • Carteira do Usuário (BRL): Uma carteira digital mostrando um saldo disponível de R$500.
    • Caso de uso: Exibir o saldo em um app de mobile banking e validar os fundos antes de autorizar um pagamento.
  • Conta de Liquidação (USD): Uma conta de provedor de liquidez com um saldo em USD de $120.000.
    • Caso de uso: Garantir que as operações diárias de tesouraria mantenham margem suficiente para liquidações de câmbio.
  • Saldo Bloqueado (BRL): Um saldo de conta reservado como garantia.
    • Caso de uso: Impedir o uso dos fundos até que um empréstimo seja encerrado ou condições sejam atendidas.

​
Estrutura do Saldo

  • Saldo > Conta: Cada Saldo pertence a uma Conta, que mantém e movimenta valor.
  • Saldo > Ativo: Cada Saldo está associado a um Ativo específico, como BRL ou BTC.
  • Saldo > Ledger: Os Saldos existem dentro de um Ledger, permitindo ambientes multi-livro.
  • Saldo > Chave: Cada Saldo possui uma chave única dentro da conta (ex.: default, credit, collateral).
Na Figura 2, você pode encontrar um exemplo da estrutura.
Balance Structure Relationships Jp
Um saldo é mais do que apenas um número. Ele inclui metadados sobre o estado dos fundos, como operações pendentes e disponibilidade efetiva.

​
Características principais

  • Rastreamento em tempo real: Os saldos são atualizados a cada operação confirmada.
  • Múltiplos saldos por conta: As contas podem manter vários saldos, cada um com suas próprias regras.
  • Fonte única da verdade: Os saldos refletem a soma líquida de todas as operações na conta.
  • Consulta por contexto: Os saldos podem ser listados por organização, ledger, ativo, conta ou chave de saldo.
  • Suporte a contas externas: Os saldos podem ser recuperados para contas internas ou externas, incluindo pools de liquidez ou parceiros.

​
Usando saldos em transações

O campo balanceKey foi adicionado aos seguintes endpoints de transação para especificar qual saldo usar: Se nenhum balanceKey for fornecido, o sistema usa o saldo principal da conta por padrão.

​
Novos campos nas respostas

  • balanceKey — Retornado em Transações e Operações, indicando qual saldo foi utilizado.
  • key — Retornado em Saldos, identificando cada saldo de forma única.
Sempre use o balanceKey de forma consistente entre requisições e respostas para evitar incompatibilidades quando contas possuem múltiplos saldos.

​
Alterações na chave de cache (Valkey)

Os saldos armazenados em cache (Valkey) incluem o balanceKey.

​
Formato anterior

<org_id>:<ledger_id>:<account_alias>

​
Novo formato

<org_id>:<ledger_id>:<account_alias>:<balance_key>
Qualquer integração que leia saldos diretamente do Valkey deve ser atualizada para incluir o balanceKey. Caso contrário, apenas o saldo padrão estará disponível.

​
Overdraft

Os saldos suportam overdraft — a capacidade de ser debitado além dos fundos disponíveis. Quando o overdraft está habilitado, o déficit é rastreado como OverdraftUsed e o Midaz trata automaticamente o split da operação e o reembolso. Dois campos suportam essa funcionalidade:
  • direction — Define se um saldo se comporta como ativo (credit, padrão) ou passivo (debit). Definido na criação, imutável.
  • settings — Controla o comportamento de overdraft: allowOverdraft, overdraftLimitEnabled e overdraftLimit.
A chave "overdraft" é reservada para o saldo companion gerenciado pelo sistema que registra o lado do passivo. Tentar criar um saldo com esta chave retorna um erro.
Os saldos também são distinguidos por escopo via settings.balanceScope. Saldos transactional (padrão) são gerenciados pelo usuário e participam de transações regulares. Saldos internal são operados exclusivamente pelo sistema — como o companion de overdraft — e não podem ser alvo de transações de usuário, nem modificados ou excluídos pela API pública. Para detalhes completos sobre modos de configuração, splits de operação, reembolso automático, eventos e casos de uso, veja Overdraft de Saldo.

​
Histórico de saldo

O Midaz fornece consultas point-in-time para saldos, permitindo que você recupere o estado exato de um saldo em qualquer momento no passado. Isso é essencial para auditoria, conciliação e relatórios históricos.

​
Como funciona

Quando você consulta o histórico de saldo, o Midaz reconstrói o estado do saldo como existia na data e hora especificadas. A resposta inclui todos os mesmos campos de um saldo regular — exceto allowSending e allowReceiving. Esses campos refletem permissões operacionais atuais em vez do estado histórico, por isso não são incluídos nas consultas point-in-time.
Por que os permission flags são excluídos do histórico?allowSending e allowReceiving são configurações operacionais mutáveis — podem ser alteradas a qualquer momento sem criar uma entrada no ledger. Ao contrário dos valores de saldo (available, onHold), que mudam apenas como resultado de transações registradas, os permission flags representam o estado operacional atual de um saldo, não um fato sobre seu passado.Auditorias e conciliações históricas se preocupam com valores em um determinado momento. Se o envio ou recebimento estava habilitado em um dado instante não é relevante para fins de auditoria ou conciliação, e incluir o estado mutável de permissões em snapshots imutáveis introduziria ambiguidade sem nenhum valor.

​
Casos de uso

  • Auditoria regulatória: Comprove o saldo exato de uma conta em um ponto de verificação de conformidade específico.
  • Conciliação: Compare snapshots de saldos entre sistemas em timestamps correspondentes.
  • Resolução de disputas: Recupere o estado preciso da conta no momento de uma transação contestada.
  • Relatórios de fim de dia: Capture posições de saldo no fechamento do mercado para operações de tesouraria.
O parâmetro date é obrigatório e deve seguir o formato yyyy-mm-dd hh:mm:ss (ex.: 2026-01-15 10:30:00). Se não existirem dados de saldo para o timestamp especificado, um erro 404 é retornado.

​
Consultando histórico de saldo

Você pode consultar o histórico de um saldo individual ou de todos os saldos de uma conta:

​
Gerenciando Saldos

Você pode recuperar seus Saldos usando a API. Os Saldos são somente leitura e gerenciados automaticamente pelo motor de ledger do Midaz.
Quer rastrear como um saldo foi formado? Use a API de Operações para inspecionar o histórico do ledger que impactou aquela conta.

​
Próximos passos