Skip to main content
Um Saldo representa o valor que uma conta específica mantém no Midaz. Ele reflete o resultado de todas as operações — débitos e créditos — ao longo do tempo. Cada saldo pertence a um ativo, como BRL, USD ou BTC.

​
Múltiplos saldos

Uma única conta pode manter vários saldos. Uma chave única identifica cada um deles. 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 mantém exatamente um 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. Ela mantém o modelo de partidas dobradas — débito e crédito — intacto para consistência contábil, rastreabilidade e transparência.
Conta com múltiplos saldos

Figura 1. Diagrama de múltiplos saldos por conta.

Se uma transação não fornecer um balanceKey, o Midaz usa o saldo padrão da conta.

​
Balance key

Um campo key identifica cada saldo de forma única dentro da conta.
  • Comprimento máximo: 100 caracteres, sem espaços em branco.
  • Chave padrão: "default". O Midaz cria o saldo padrão automaticamente quando a conta é criada.
  • Unicidade: Cada chave deve ser única por conta. Uma solicitação para criar um saldo com uma chave que já existe na conta retorna um erro.
  • Em transações: Se uma transação não especificar um balanceKey, o Midaz usa o saldo com a chave "default".
Você define a key no momento da criação e não pode alterá-la depois. 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: Estes flags são por saldo — aplicam-se a um saldo, não à conta como um todo. Ambos têm o valor true por padrão quando você não os define. Casos de uso comuns:
  • Congelar um saldo: Defina allowSending e allowReceiving como false para impedir qualquer movimentação.
  • Saldo somente para recebimento: Defina allowSending como false para bloquear transferências de saída e continuar aceitando entradas.
  • Saldo somente para envio: Defina allowReceiving como false para impedir que novos fundos entrem neste saldo.
Você pode definir ambos os flags quando cria um saldo. Você também pode atualizá-los de forma independente pelo endpoint Atualizar um Saldo. Se uma solicitação de atualização omitir um flag, seu valor atual permanece inalterado.
O Midaz lê os permission flags durante a validação da transação. Um PATCH que altera apenas allowSending ou allowReceiving não regrava uma entrada existente no Valkey; portanto, não presuma que a próxima transação atendida pelo cache verá a alteração. As alterações nunca mudam Operations já processadas.

​
Exemplos de uso

  • Carteira do Usuário (BRL): Uma carteira digital que mostra um saldo disponível de R$500.
    • Caso de uso: Mostre o saldo em um app de mobile banking e valide os fundos antes de um pagamento.
  • Conta de Liquidação (USD): Uma conta de provedor de liquidez com um saldo em USD de $120.000.
    • Caso de uso: Garanta 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: Impeça o uso dos fundos até que um empréstimo seja encerrado ou o tomador cumpra as condições.
Um saldo bloqueado (de garantia) restringe fundos no nível do saldo. O Midaz mantém o valor em um saldo separado e o combina com os permission flags para manter os fundos indisponíveis. Isso é diferente de uma transação de bloqueio, que registra uma movimentação no ledger com operações do tipo BLOCK. Uma transação de bloqueio marca fundos por motivos como uma retenção por conformidade. Use um saldo de garantia para uma restrição operacional permanente. Use uma transação de bloqueio quando precisar de uma entrada auditável no ledger.

​
Estrutura do Saldo

  • Saldo > Conta: Cada Saldo pertence a uma Conta, que mantém e movimenta valor.
  • Saldo > Ativo: Cada Saldo usa um Ativo específico, como BRL ou BTC.
  • Saldo > Ledger: Os Saldos existem dentro de um Ledger, o que permite ambientes multi-livro.
  • Saldo > Chave: Cada Saldo possui uma chave única dentro da conta (ex.: default, credit, collateral).
A Figura 2 mostra um exemplo da estrutura.
Relações da estrutura de saldos

Figura 2. Diagrama de relacionamentos da estrutura de saldos.

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: O Midaz atualiza os saldos 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: Você pode listar saldos dentro de uma organização e de um Ledger, recuperá-los por ID ou alias da conta e recuperar o saldo de uma Conta Externa por código de ativo. Os endpoints de listagem de saldos não filtram por código de ativo genérico nem por balanceKey.
  • Suporte a contas externas: Você pode recuperar saldos para contas internas ou externas, como pools de liquidez ou parceiros.

​
Usando saldos em transações

Os seguintes endpoints de transação aceitam um campo balanceKey para especificar qual saldo usar: Se uma solicitação não fornecer um balanceKey, o Midaz usa o saldo padrão da conta.

​
Novos campos nas respostas

  • balanceKey — Aparece em transações e operações para mostrar qual saldo a transação usou.
  • key — Aparece nos saldos para identificar cada saldo de forma única.
Sempre use o balanceKey de forma consistente entre requisições e respostas. Isso evita incompatibilidades quando contas possuem múltiplos saldos.

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

Os saldos na cache (Valkey) incluem o balanceKey.

​
Formato anterior

​
Novo formato

A chave carrega o prefixo balance:{transactions}:, e a balance_key é anexada ao alias da conta com um separador #. Um namespace de tenant pode prefixar a chave adicionalmente em implantações multi-tenant.
Atualize os leitores diretos do Valkey para construir balance:{transactions}:<org_id>:<ledger_id>:<account_alias>#<balance_key>, incluindo #default para o saldo padrão. Leituras que usam o formato de chave anterior não encontram a entrada atual do cache.

​
Overdraft

Os saldos suportam overdraft — a capacidade de debitar um saldo além dos fundos disponíveis. Quando você habilita o overdraft, o Midaz rastreia o déficit como overdraftUsed. O Midaz também trata o split da Operation e o reembolso automaticamente. Dois campos suportam essa funcionalidade:
  • direction — Para um saldo padrão criado automaticamente, a direção é credit para contas não externas e debit para Contas Externas. Saldos adicionais podem definir a direção na criação; ela não pode mudar depois.
  • settings — Controla o comportamento de overdraft: allowOverdraft, overdraftLimitEnabled e overdraftLimit.
O Midaz reserva a chave "overdraft" para o saldo companion gerenciado pelo sistema que registra o lado do passivo. Uma solicitação para criar um saldo com esta chave retorna um erro.
settings.balanceScope também distingue os saldos por escopo. Os saldos transactional (o padrão) são gerenciados pelo usuário e participam de transações regulares. O sistema opera os saldos internal de forma exclusiva — como o companion de overdraft. As transações de usuário não podem ter como alvo, modificar nem excluir esses saldos 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. Você pode recuperar o estado de um saldo em um timestamp passado igual ou posterior à criação do saldo. Se não houver Operation anterior a esse timestamp, o Midaz retorna o estado inicial zerado; retorna 404 quando o timestamp solicitado é anterior à criação do saldo. Isso serve para auditoria, conciliação e relatórios históricos.

​
Como funciona

O endpoint de histórico retorna campos históricos de identidade e valores. Ele omite allowSending, allowReceiving, deletedAt e metadata; a implementação atual também não reconstrói direction nem settings históricos e retorna overdraftUsed como zero. Não o descreva como uma resposta completa de saldo regular sem os permission flags.
Por que o histórico exclui os permission flags?allowSending e allowReceiving são configurações operacionais mutáveis. Você pode alterá-las a qualquer momento sem uma entrada no ledger. Os valores de saldo (available, onHold) mudam apenas a partir 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 os valores em um determinado momento. Se o envio ou o recebimento funcionava em um dado instante não importa para a auditoria ou a conciliação. O estado mutável de permissões em snapshots imutáveis adicionaria 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. Ele deve seguir o formato yyyy-mm-dd hh:mm:ss (ex.: 2026-01-15 10:30:00). O Midaz retorna 404 quando o timestamp solicitado é anterior à criação do saldo.

​
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 pela API. O motor de ledger do Midaz calcula os valores de saldo a partir das transações — você não pode definir available ou onHold diretamente. Você gerencia os registros de saldo — chave, permission flags e settings — pelos endpoints abaixo.
Quer rastrear como um saldo foi formado? Use a API de Operações para inspecionar o histórico do ledger que afetou aquela conta.

​
Próximos passos

  • Use a API de Operações para rastrear transações que envolvem múltiplos saldos.
  • Combine múltiplos saldos com Rotas Contábeis para criar fluxos financeiros flexíveis e escaláveis.