> ## 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 um Saldo > Use este endpoint para consultar um saldo específico pelo seu identificador. ## OpenAPI ````yaml pt/openapi/v3-current/ledger.yaml get /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id} 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}: get: tags: - API de Saldos summary: Consultar um Saldo description: >- Use este endpoint para consultar um saldo específico pelo seu identificador. parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LedgerId' - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/BalanceId' responses: '200': description: >- Indica que a requisição foi bem-sucedida e a resposta contém os dados esperados. content: application/json: schema: $ref: '#/components/schemas/GetBalanceResponse' 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: customer-brl-1 key: default assetCode: BRL available: '1000' onHold: '0' version: 1 accountType: deposit allowSending: true allowReceiving: true direction: credit overdraftUsed: '0' settings: null position: available: '1000' onHold: '0' overdraftLimitAvailable: '0' createdAt: '2026-02-25T21:06:37.197596Z' updatedAt: '2026-02-25T21:06:38.420934Z' deletedAt: null '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0065: $ref: '#/components/examples/Error0065' headers: {} '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: Error0007: $ref: '#/components/examples/Error0007' headers: {} '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 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 ` 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 schemas: GetBalanceResponse: type: object properties: id: type: string 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 utilizada na operação. key: type: string description: O identificador único do saldo no contexto da conta. assetCode: type: string description: O nome do ativo utilizado na operação. available: type: string description: Saldo disponível anterior. onHold: type: string description: Valor retido/reservado. version: type: integer description: Versão do saldo, que é atualizada a cada transação. accountType: type: string description: O tipo da conta. allowSending: type: boolean description: >- Se verdadeiro, indica que o saldo pode ser usado para enviar transações. allowReceiving: type: boolean description: >- Se verdadeiro, indica que o saldo pode ser usado para receber transações. direction: type: string enum: - credit - debit description: >- A direção contábil do saldo. Saldos `credit` crescem em crédito e diminuem em débito; saldos `debit` crescem em débito e diminuem em crédito. Definida na criação e imutável. overdraftUsed: type: string description: >- O valor de overdraft atualmente consumido por este saldo, como string decimal. Sempre não negativo; `"0"` quando o saldo não tem overdraft ativo. settings: allOf: - $ref: '#/components/schemas/BalanceSettings' description: >- Configuração opcional por saldo (overdraft, escopo). `null` para saldos legados sem configurações personalizadas. position: type: object readOnly: true description: >- Visão computada do estado do saldo no momento da resposta. Sempre presente; nunca persistida. Recalculada a partir de `available`, `onHold`, `overdraftUsed` e `settings` em cada leitura. properties: available: type: string readOnly: true description: >- Valor líquido disponível para gastar como string decimal. Igual a `balance.available` menos `overdraftUsed`. Negativo quando o overdraft está ativo. onHold: type: string readOnly: true description: >- Espelha `balance.onHold`. Fundos reservados por operações pendentes. overdraftLimitAvailable: type: string readOnly: true description: >- Margem restante de overdraft como string decimal. `"0"` quando o overdraft está desabilitado. Omitido completamente quando o overdraft é ilimitado (`allowOverdraft: true` e `overdraftLimitEnabled: false`). Caso contrário, igual a `overdraftLimit` menos `overdraftUsed`. createdAt: type: string format: date-time description: Data e hora de criação (UTC). updatedAt: type: string format: date-time description: Data e hora da última atualização (UTC). deletedAt: type: - string - 'null' format: date-time description: Data e hora da exclusão lógica, se aplicável (UTC). metadata: $ref: '#/components/schemas/Metadata' 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. Metadata: type: object additionalProperties: oneOf: - type: string maxLength: 2000 - type: number - type: boolean description: >- Um objeto contendo pares de chave-valor para adicionar como metadata, onde o campo `name` é a chave e o campo `value` é o valor. Por exemplo, para adicionar um Centro de Custo, use `'costCenter': 'BR_11101997'`. **Restrições:** as chaves devem ter no máximo 100 caracteres; valores de string no máximo 2000 caracteres. Objetos aninhados não são permitidos (os valores devem ser string, número ou booleano), a estrutura não pode exceder uma profundidade máxima de 10, e é permitido um máximo de 100 chaves. examples: Error0065: value: code: '0065' title: Invalid Path Parameter message: >- The provided path parameter {{parameter_name}} is not in the expected format. Please ensure the parameter adheres to the required format and try again. summary: Invalid Path Parameter 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. Error0007: value: code: '0007' title: Entity Not Found message: >- No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage. summary: Entity Not Found 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. ````