> ## 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. # Consultar histórico de saldo > Use este endpoint para obter o estado de um saldo específico em um momento determinado no passado (consulta point-in-time). ## OpenAPI ````yaml pt/openapi/v3-current/ledger.yaml get /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history openapi: 3.1.0 info: title: API Midaz Ledger description: >- Referência completa da API para serviços do Midaz Ledger incluindo gerenciamento de organizações, operações de ledger, ativos, segmentos, portfolios, contas, tipos de conta, transações, operações, saldos, rotas de operação, rotas de transação e índices de metadata. version: 3.7.8 servers: - url: https://ledger.sandbox.lerian.net security: [] tags: - name: API de Organizações - name: API de Ledgers - name: API de Ativos - name: API de Segmentos - name: API de Portfolios - name: API de Tipos de Conta - name: API de Contas - name: API de Saldos - name: API de Transações - name: API de Operações - name: API de Rotas de Operação - name: API de Rotas de Transação - name: API de Índices de Metadata - name: API de Titulares - name: API de Instrumentos - name: API de Pacotes de Cobrança - name: API de Pacotes - name: API de Cálculo de Cobrança - name: API de Estimativa - name: API de Criptografia - name: API de Proteção - name: API de Taxas de Ativos paths: /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history: get: tags: - API de Saldos summary: Consultar histórico de saldo description: >- Use este endpoint para obter o estado de um saldo específico em um momento determinado no passado (consulta point-in-time). parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LedgerId' - $ref: '#/components/parameters/BalanceId' - name: date in: query description: >- A data e hora para consultar o estado do saldo. Formato: yyyy-mm-dd hh:mm:ss (ex.: 2026-01-15 10:30:00). required: true example: '2026-01-15 10:30:00' schema: type: string pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/Authorization' responses: '200': description: >- Indica que a requisição foi bem-sucedida e a resposta contém o estado do saldo no momento especificado. content: application/json: schema: $ref: '#/components/schemas/BalanceHistoryResponse' example: id: 019c96a0-0c0d-7915-84b9-e497bfee9916 organizationId: 019c96a0-0a98-7287-9a31-786e0809c769 ledgerId: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a accountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 alias: '@conta_corrente' key: default assetCode: BRL available: '150000' onHold: '25000' version: 42 accountType: deposit direction: credit overdraftUsed: '0' settings: null position: available: '150000' onHold: '25000' overdraftLimitAvailable: '0' createdAt: '2025-06-01T10:00:00Z' updatedAt: '2026-01-15T10:30:00Z' headers: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0131: $ref: '#/components/examples/Error0131' Error0140: $ref: '#/components/examples/Error0140' Error0142: $ref: '#/components/examples/Error0142' '401': description: Não autorizado content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0041: $ref: '#/components/examples/Error0041' Error0042: $ref: '#/components/examples/Error0042' '403': description: Proibido content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0043: $ref: '#/components/examples/Error0043' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0141: $ref: '#/components/examples/Error0141' '500': description: Erro Interno do Servidor content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0046: $ref: '#/components/examples/Error0046' components: parameters: OrganizationId: name: organization_id in: path description: O identificador único da Organização associada ao Ledger. required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid LedgerId: name: ledger_id in: path description: O identificador único do Ledger associado. required: true example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a schema: type: string format: uuid BalanceId: name: balance_id in: path description: O identificador único do saldo que você deseja consultar. required: true example: 019c96a0-0c0d-7915-84b9-e497bfee9916 schema: type: string format: uuid ContentType: name: Content-Type in: header description: O tipo de mídia do recurso. O valor recomendado é `application/json`. required: false example: application/json schema: type: string XRequestId: name: X-Request-Id in: header description: >- Um identificador único utilizado para rastrear e acompanhar cada requisição. required: false example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid Authorization: name: Authorization in: header required: false schema: type: string description: > Token JWT bearer para autenticação. Obrigatório quando `PLUGIN_AUTH_ENABLED=true` (exigido em implantações multi-tenant). Opcional no modo OSS single-tenant padrão. Formato: `Bearer ` schemas: BalanceHistoryResponse: type: object description: >- O estado de um saldo em um momento específico no passado. Não inclui os campos allowSending e allowReceiving. properties: id: type: string format: uuid description: O identificador único do Saldo. organizationId: type: string format: uuid description: O identificador único da Organização. ledgerId: type: string description: O identificador único do Ledger. format: uuid accountId: type: string description: O identificador único da Conta. format: uuid alias: type: string description: O alias da conta (ex., @conta_corrente). key: type: string description: >- A chave única do saldo no contexto da conta (ex., default, asset-freeze). assetCode: type: string description: O código do ativo (ex., BRL, USD). available: type: string description: >- O saldo disponível no momento consultado. Representado como uma string decimal com precisão arbitrária (ex., "1500.75"). onHold: type: string description: >- O saldo retido (reservado) no momento consultado. Representado como uma string decimal com precisão arbitrária (ex., "1500.75"). version: type: integer description: A versão do saldo no momento consultado. accountType: type: string description: O tipo da conta (ex., deposit, creditCard). direction: type: string enum: - credit - debit description: A direção contábil do saldo no momento consultado. overdraftUsed: type: string description: >- O valor de overdraft consumido no momento consultado, como string decimal. Sempre não negativo. settings: allOf: - $ref: '#/components/schemas/BalanceSettings' description: >- Snapshot da configuração por saldo no momento consultado. `null` para saldos legados sem configurações personalizadas. position: type: object readOnly: true description: >- Visão computada do estado do saldo no momento consultado. Sempre presente; nunca persistida. Espelha o formato da posição do saldo ao vivo, então respostas históricas carregam a mesma estrutura de wire das leituras ao vivo. properties: available: type: string readOnly: true description: >- Valor líquido disponível para gastar no momento consultado. Igual a `available` menos `overdraftUsed`. Negativo quando o overdraft estava ativo. onHold: type: string readOnly: true description: Espelha `onHold` no momento consultado. overdraftLimitAvailable: type: string readOnly: true description: >- Margem restante de overdraft no momento consultado. `"0"` quando o overdraft estava desabilitado. Omitido completamente quando o overdraft era ilimitado. createdAt: type: string format: date-time description: Timestamp de criação do saldo (UTC). updatedAt: type: string format: date-time description: Timestamp da última atualização no momento consultado (UTC). ErrorFormat: type: object description: A mensagem de erro da resposta. required: - code - title - message properties: code: type: string description: Um identificador único e estável para o erro. title: type: string description: Um breve resumo do problema. message: type: string description: Orientação detalhada para resolver o erro. entityType: type: string description: >- O tipo de entidade ao qual o erro se refere (por exemplo, organization, ledger, account, transaction). Opcional. fields: type: object additionalProperties: true description: Informações adicionais sobre os campos que causaram o erro. BalanceSettings: type: object description: >- Configuração opcional por saldo que controla o comportamento do overdraft e o escopo do saldo. properties: allowOverdraft: type: boolean description: >- Quando `true`, o saldo pode ser debitado além dos fundos disponíveis. Padrão `false`. overdraftLimitEnabled: type: boolean description: >- Quando `true`, é obrigatório informar `overdraftLimit` — o saldo pode ficar negativo até esse valor. Quando `false` com `allowOverdraft` `true`, o overdraft é ilimitado. overdraftLimit: type: string description: >- Valor máximo de overdraft como string decimal (ex.: `"5000.00"`). Obrigatório quando `overdraftLimitEnabled` é `true` e deve ser maior que zero. Omita quando o overdraft for ilimitado. balanceScope: type: string enum: - transactional - internal description: >- Escopo gerenciado pelo sistema. `transactional` é o padrão; `internal` marca saldos companion gerenciados pelo sistema (como o companion de overdraft) e bloqueia operações diretas de usuários. examples: Error0131: summary: Invalid Datetime Format value: code: '0131' title: Invalid Datetime Format message: >- The provided datetime format is invalid. Please use the format yyyy-mm-dd hh:mm:ss. Error0140: summary: Invalid Timestamp value: code: '0140' title: Invalid Timestamp message: >- The provided timestamp is invalid. Please ensure the date and time values are correct. Error0142: summary: Missing Required Query Parameter value: code: '0142' title: Missing Required Query Parameter message: >- A required query parameter is missing from the request. Please include all required parameters and try again. Error0041: summary: Token Missing value: code: '0041' title: Token Missing message: >- A valid token must be provided in the request header. Please include a token and try again. Error0042: summary: Invalid Token value: code: '0042' title: Invalid Token message: >- The provided token is expired, invalid or malformed. Please provide a valid token and try again. Error0043: summary: Insufficient Privileges value: code: '0043' title: Insufficient Privileges message: >- You do not have the necessary permissions to perform this action. Please contact your administrator if you believe this is an error. Error0141: summary: No Balance Data at Timestamp value: code: '0141' title: No Balance Data at Timestamp message: >- No balance data exists for the specified point in time. The balance may not have existed at that date, or no operations had been recorded yet. Error0046: summary: Internal Server Error value: code: '0046' title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later or contact support. ````