> ## 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. # Saldos > Rastreie múltiplos Saldos por Conta para segmentar fundos — reservas, limites de crédito e fundos operacionais sem Contas adicionais. 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: | Flag | Tipo | Descrição | | ---------------- | ------- | ----------------------------------------------------- | | `allowSending` | boolean | Se fundos podem ser enviados **a partir** deste saldo | | `allowReceiving` | boolean | Se 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](/pt/reference/midaz/update-a-balance). 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. Um saldo bloqueado (de garantia) restringe fundos no **nível do saldo** — o valor é mantido em um saldo separado e, combinado com as `permission flags`, é impedido de ser gasto. Isso é diferente de uma [transação de bloqueio](/pt/midaz/transactions#bloqueando-e-desbloqueando-fundos), que registra uma movimentação no ledger com operações do tipo `BLOCK` para marcar 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 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: * [Criar uma Transação usando JSON](/pt/reference/midaz/create-a-transaction-using-json) * [Criar uma Transação de Entrada](/pt/reference/midaz/create-an-inflow-transaction) * [Criar uma Transação de Saída](/pt/reference/midaz/create-an-outflow-transaction) * [Criar uma Anotação de Transação](/pt/reference/midaz/create-a-transaction-annotation) 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 ```json theme={null} :: ``` ### Novo formato ```json theme={null} ::: ``` 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](/pt/midaz/balance-overdraft). ## 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: * [Recuperar histórico de saldo](/pt/reference/midaz/retrieve-balance-history) — Obtenha o estado de um saldo específico em um determinado momento. * [Recuperar histórico de saldo por conta](/pt/reference/midaz/retrieve-balance-history-by-account) — Obtenha o estado de todos os saldos de uma conta em um determinado momento. ## 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. * [Criar um Saldo](/pt/reference/midaz/create-a-balance) — Crie um novo saldo para uma conta definindo uma chave única. * [Listar Saldos](/pt/reference/midaz/list-balances) — Recupere todos os saldos por organização e ledger. * [Recuperar um Saldo](/pt/reference/midaz/retrieve-a-balance) — Obtenha o saldo de uma conta específica pelo seu ID único. * [Recuperar Saldos por Conta](/pt/reference/midaz/retrieve-balances-by-account) — Obtenha o saldo de uma conta específica. * [Recuperar um Saldo por Alias da Conta](/pt/reference/midaz/retrieve-a-balance-by-account-alias) — Obtenha o saldo usando um alias legível da conta (ex.: @user123). * [Recuperar um Saldo de uma Conta Externa](/pt/reference/midaz/retrieve-a-balance-of-an-external-account) — Recupere o saldo de uma conta externa (ex.: `@external/BRL`). * [Atualizar um Saldo](/pt/reference/midaz/update-a-balance) — Ajuste manualmente um saldo para fins operacionais ou de teste. * [Excluir um Saldo](/pt/reference/midaz/delete-a-balance) — Exclua uma entrada de saldo do sistema. 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 *** * Use a [API de Operações](/pt/midaz/operations) para rastrear transações envolvendo múltiplos saldos. * Combine múltiplos saldos com [Rotas Contábeis](/pt/midaz/transaction-routing-entities) para criar fluxos financeiros flexíveis e escaláveis.