> ## 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 > Acompanhe múltiplos Saldos por Conta para segmentar fundos em reservas de investimento, limites de crédito e fundos operacionais sem Contas extras. 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 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: | Flag | Tipo | Descrição | | ---------------- | ------- | ----------------------------------------------------- | | `allowSending` | boolean | Se fundos podem ser enviados **a partir** deste saldo | | `allowReceiving` | boolean | Se fundos podem ser recebidos **neste** saldo | 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](/pt/reference/products/midaz/v2/update-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](/pt/products/midaz/transactions#blocking-and-unblocking-funds), 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 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: * [Create a Transaction using JSON](/pt/reference/products/midaz/v1/create-transaction-json) * [Create an Inflow Transaction](/pt/reference/products/midaz/v1/create-transaction-inflow) * [Create an Outflow Transaction](/pt/reference/products/midaz/v1/create-transaction-outflow) * [Create a Transaction Annotation](/pt/reference/products/midaz/v1/create-transaction-annotation) 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 ```json theme={null} :: ``` ### Novo formato ```json theme={null} balance:{transactions}:::# ``` 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}:::#`, 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](/pt/products/midaz/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: * [Retrieve Balance History](/pt/reference/products/midaz/v2/get-balance-at-timestamp) - Obtenha o estado de um saldo específico em um determinado ponto no tempo. * [Retrieve Balance History by Account](/pt/reference/products/midaz/v2/get-account-balances-at-timestamp) - Obtenha o estado de todos os saldos de uma conta em um determinado ponto no tempo. ## 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. * [Create a Balance](/pt/reference/products/midaz/v2/create-additional-balance) - Crie um novo saldo para uma conta definindo uma chave exclusiva. * [List Balances](/pt/reference/products/midaz/v2/get-all-balances) - Recupere todos os saldos por organização e ledger. * [Retrieve a Balance](/pt/reference/products/midaz/v2/get-balance-by-id) - Obtenha o saldo de uma conta específica pelo ID exclusivo dela. * [Retrieve Balances by Account](/pt/reference/products/midaz/v2/get-all-balances-by-account-id) - Obtenha o saldo de uma conta específica. * [Retrieve a Balance by Account Alias](/pt/reference/products/midaz/v2/get-balances-by-alias) - Obtenha o saldo com um alias de conta legível por humanos (por exemplo, @user123). * [Retrieve a Balance of an External Account](/pt/reference/products/midaz/v2/get-balances-external-by-code) - Recupere o saldo de uma conta externa (por exemplo, `@external/BRL`). * [Update a Balance](/pt/reference/products/midaz/v2/update-balance) - Atualize as flags de permissão e as configurações de um saldo. * [Delete a Balance](/pt/reference/products/midaz/v2/delete-balance) - Exclua um registro de saldo do sistema. 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](/pt/products/midaz/operations) para rastrear transações que envolvem múltiplos saldos. * Combine múltiplos saldos com [Rotas Contábeis](/pt/products/midaz/transaction-routing-entities) para criar fluxos financeiros flexíveis e escaláveis.