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 exclusiva identifica cada um. Isso permite que as 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 garantir consistência contábil, rastreabilidade e transparência.
Conta com múltiplos saldos

Figura 1. Diagrama de múltiplos saldos.

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

​
Chave do saldo

Um campo key identifica cada saldo de forma exclusiva 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.
  • Exclusividade: Cada chave deve ser exclusiva 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 uma 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 saldo autoexplicativo.

​
Flags de permissão

Cada saldo tem duas flags de permissão independentes que controlam se ele pode participar de transações: Essas flags são por saldo. Elas se aplicam a um saldo, não à conta inteira. Ambas assumem true por padrão quando você não as define. Casos de uso comuns:
  • Congelar um saldo: Defina allowSending e allowReceiving como false para impedir qualquer movimentação.
  • Saldo apenas para recebimento: Defina allowSending como false para bloquear transferências de saída e continuar aceitando entradas.
  • Saldo apenas para envio: Defina allowReceiving como false para impedir a entrada de novos fundos neste saldo.
Você pode definir ambas as flags ao criar um saldo. Também pode atualizá-las de forma independente pelo endpoint Update a Balance. Se uma solicitação de atualização omitir uma flag, o valor atual dela permanece inalterado.
O Midaz lê as flags de permissão durante a validação da transação. Um PATCH que altera apenas allowSending ou allowReceiving não reescreve uma entrada existente no Valkey, então não presuma que a transação com cache-hit imediatamente seguinte já vai refletir a mudança. As alterações nunca modificam operações 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: Mostrar o saldo em um aplicativo de banco móvel e validar 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: Garantir que as operações diárias de tesouraria mantenham buffer suficiente para liquidações de câmbio.
  • Saldo bloqueado (BRL): Um saldo de conta reservado como garantia.
    • Caso de uso: Impedir o uso de fundos até que um empréstimo se encerre ou o tomador cumpra as condições.
Um saldo bloqueado (garantia) restringe fundos no nível do saldo. O Midaz mantém o valor em um saldo separado e o combina com flags de permissão para manter os fundos indisponíveis. Isso difere de uma transação de Bloqueio, que registra uma movimentação no ledger com operações do tipo BLOCK. Uma transação de Bloqueio sinaliza fundos por motivos como uma retenção de compliance. Use um saldo de garantia para uma restrição operacional permanente. Use uma transação de Bloqueio quando precisar de um lançamento 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 viabiliza ambientes multi-book.
  • Saldo > Chave: Cada Saldo tem uma chave exclusiva dentro da conta (por exemplo, default, credit, collateral).
A Figura 2 mostra um exemplo da estrutura.
Relacionamentos da estrutura do saldo

Figura 2. Diagrama de relacionamentos da estrutura do saldo.

Um saldo inclui metadados sobre o estado dos fundos, como operações pendentes e disponibilidade efetiva.

​
Características principais

  • Acompanhamento 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 de 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 ledger, recuperá-los pelo ID ou alias da conta, e recuperar o saldo de uma Conta Externa pelo código do ativo. Os endpoints de listagem de saldo não filtram por um código de ativo genérico ou por balanceKey.
  • Suporte a contas externas: Você pode recuperar saldos de 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 uma 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 exclusiva.
Sempre use a balanceKey de forma consistente entre solicitações e respostas. Isso evita incompatibilidades quando as contas mantêm múltiplos saldos.

​
Mudanças na chave de cache (Valkey)

Os saldos no cache (Valkey) incluem a balanceKey.

​
Formato anterior

​
Novo formato

A chave carrega o prefixo balance:{transactions}:, e o balance_key é anexado ao alias da conta com um separador #. Um namespace de tenant pode prefixar a chave ainda mais em deploys 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 de cache atual.

​
Overdraft

Os saldos aceitam 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 a divisão da operação e o pagamento automaticamente. Dois campos oferecem suporte a esse recurso:
  • 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 do overdraft com allowOverdraft, overdraftLimitEnabled e overdraftLimit.
O Midaz reserva a chave "overdraft" para o saldo companheiro gerenciado pelo sistema que registra o lado do passivo. Uma solicitação para criar um saldo com essa chave retorna um erro.
O settings.balanceScope também distingue saldos por escopo. Os saldos transacionais (o padrão) são gerenciados pelo usuário e participam de transações normais. O sistema opera exclusivamente os saldos internos, como o companheiro de overdraft. As transações do usuário não podem direcionar, modificar ou excluir esses saldos pela API pública. Para detalhes completos sobre modos de configuração, divisão de operações, pagamento automático, eventos e casos de uso, veja Balance Overdraft.

​
Histórico do saldo

O Midaz oferece consultas pontuais no tempo para saldos. Você pode recuperar o estado de um saldo em um timestamp passado, em ou após a criação do saldo. Se não existir nenhuma operação antes desse timestamp, o Midaz retorna o estado inicial zerado. Ele retorna 404 quando o timestamp solicitado é anterior à criação do saldo. Isso oferece suporte a auditoria, conciliação e relatórios históricos.

​
Como funciona

Quando você consulta o histórico do saldo, o Midaz retorna campos históricos de identidade e valor. Ele omite allowSending, allowReceiving, deletedAt e metadata. A implementação atual também não reconstrói direction ou settings históricos, e retorna overdraftUsed como zero. Não trate isso como uma resposta completa de saldo normal menos as flags de permissão.
Por que o histórico exclui as flags de permissão?allowSending e allowReceiving são configurações operacionais mutáveis. Você pode alterná-las a qualquer momento sem um lançamento no ledger. Os valores do saldo (available, onHold) mudam apenas a partir de transações registradas. As flags de permissão representam o estado operacional atual de um saldo, não um fato sobre seu passado.Auditorias históricas e conciliação se preocupam com valores em um ponto no tempo. Se o envio ou o recebimento funcionava em um determinado momento não importa para fins de auditoria ou conciliação. Estado de permissão mutável em snapshots imutáveis adicionaria ambiguidade sem valor.

​
Casos de uso

  • Auditoria regulatória: Comprove o saldo exato de uma conta em um ponto de verificação de compliance específico.
  • Conciliação: Compare snapshots de saldo entre sistemas em timestamps correspondentes.
  • Resolução de disputas: Recupere o estado exato da conta no momento de uma transação contestada.
  • Relatório 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 (por exemplo, 2026-01-15 10:30:00). O Midaz retorna 404 quando o timestamp solicitado é anterior à criação do saldo.

​
Consultando o histórico do saldo

Você pode consultar o histórico de um único saldo 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, flags de permissão e configurações) pelos endpoints abaixo.
Para rastrear como um saldo se formou, 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.