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.
- Reservas de investimento
- Limites de crédito
- Fundos de garantia (bloqueados)
- Fundos operacionais do dia a dia
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).
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
- Criar uma Transação de Entrada
- Criar uma Transação de Saída
- Criar uma Anotação de Transação
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) agora incluem o
balanceKey.
Formato anterior
Novo formato
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 — Crie um novo saldo para uma conta definindo uma chave única.
- Listar Saldos — Recupere todos os saldos por organização e ledger.
- Recuperar um Saldo — Obtenha o saldo de uma conta específica pelo seu ID único.
- Recuperar Saldos por Conta — Obtenha o saldo de uma conta específica.
- Recuperar um Saldo por Alias da Conta — Obtenha o saldo usando um alias legível da conta (ex.: @user123).
- Recuperar um Saldo de uma Conta Externa — Recupere o saldo de uma conta externa (ex.:
@external/BRL). - Atualizar um Saldo — Ajuste manualmente um saldo para fins operacionais ou de teste.
- Excluir um Saldo (descontinuado) — Exclua uma entrada de saldo do sistema.
Próximos passos
- Use a API de Operações para rastrear transações envolvendo múltiplos saldos.
- Combine múltiplos saldos com Roteamento de Transações para criar fluxos financeiros flexíveis e escaláveis.