> ## 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 historial de saldo > Utilice este endpoint para obtener el estado de un saldo específico en un momento determinado del pasado (consulta point-in-time). ## OpenAPI ````yaml es/openapi/v3-current/ledger.yaml get /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history openapi: 3.1.0 info: title: API de Midaz Ledger description: >- Referencia completa de la API para los servicios de Midaz Ledger, incluyendo gestión de organizaciones, operaciones de ledger, activos, segmentos, portafolios, cuentas, tipos de cuenta, transacciones, operaciones, saldos, rutas de operación, rutas de transacción e índices de metadatos. version: 3.7.8 servers: - url: https://ledger.sandbox.lerian.net security: [] tags: - name: Organizations API - name: Ledgers API - name: Assets API - name: Segments API - name: Portfolios API - name: Account Types API - name: Accounts API - name: Balances API - name: Transactions API - name: Operations API - name: Operation Routes API - name: Transaction Routes API - name: Metadata Indexes API - name: Holders API - name: Instruments API - name: Billing Packages API - name: Packages API - name: Billing Calculation API - name: Estimation API - name: Encryption API - name: Protection API - name: Asset Rates API paths: /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history: get: tags: - Balances API summary: Consultar historial de saldo description: >- Utilice este endpoint para obtener el estado de un saldo específico en un momento determinado del pasado (consulta point-in-time). parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LedgerId' - $ref: '#/components/parameters/BalanceId' - name: date in: query description: >- La fecha y hora para consultar el estado del saldo. Formato: yyyy-mm-dd hh:mm:ss (ej.: 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 la solicitud fue exitosa y la respuesta contiene el estado del saldo en el 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: No autorizado content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0041: $ref: '#/components/examples/Error0041' Error0042: $ref: '#/components/examples/Error0042' '403': description: Prohibido 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: Error Interno del Servidor content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0046: $ref: '#/components/examples/Error0046' components: parameters: OrganizationId: name: organization_id in: path description: El identificador único de la Organización asociada al Ledger. required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid LedgerId: name: ledger_id in: path description: El identificador único del Ledger asociado. required: true example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a schema: type: string format: uuid BalanceId: name: balance_id in: path description: El identificador único del saldo que desea recuperar. required: true example: 019c96a0-0c0d-7915-84b9-e497bfee9916 schema: type: string format: uuid ContentType: name: Content-Type in: header description: >- El tipo de medio del recurso. El valor recomendado es `application/json`. required: false example: application/json schema: type: string XRequestId: name: X-Request-Id in: header description: Un identificador único utilizado para rastrear y seguir cada solicitud. 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 autenticación. Requerido cuando `PLUGIN_AUTH_ENABLED=true` (obligatorio en despliegues multiinquilino). Opcional en el modo OSS de inquilino único predeterminado. Formato: `Bearer ` schemas: BalanceHistoryResponse: type: object description: >- El estado de un saldo en un momento específico del pasado. No incluye los campos allowSending y allowReceiving. properties: id: type: string format: uuid description: El identificador único del Saldo. organizationId: type: string format: uuid description: El identificador único de la Organización. ledgerId: type: string description: El identificador único del Ledger. format: uuid accountId: type: string description: El identificador único de la Cuenta. format: uuid alias: type: string description: El alias de la cuenta (ej., @conta_corrente). key: type: string description: >- La clave única del saldo en el contexto de la cuenta (ej., default, asset-freeze). assetCode: type: string description: El código del activo (ej., BRL, USD). available: type: string description: >- El saldo disponible en el momento consultado. Representado como una cadena decimal con precisión arbitraria (ej., "1500.75"). onHold: type: string description: >- El saldo retenido (reservado) en el momento consultado. Representado como una cadena decimal con precisión arbitraria (ej., "1500.75"). version: type: integer description: La versión del saldo en el momento consultado. accountType: type: string description: El tipo de la cuenta (ej., deposit, creditCard). direction: type: string enum: - credit - debit description: La dirección contable del saldo en el momento consultado. overdraftUsed: type: string description: >- La cantidad de overdraft consumida en el momento consultado, como string decimal. Siempre no negativa. settings: allOf: - $ref: '#/components/schemas/BalanceSettings' description: >- Snapshot de la configuración por saldo en el momento consultado. `null` para saldos legados sin configuraciones personalizadas. position: type: object readOnly: true description: >- Vista computada del estado del saldo en el momento consultado. Siempre presente; nunca persistida. Refleja la misma forma que la posición del saldo en vivo, así que las respuestas históricas llevan la misma estructura de wire que las lecturas en vivo. properties: available: type: string readOnly: true description: >- Monto neto disponible para gastar en el momento consultado. Igual a `available` menos `overdraftUsed`. Negativo cuando el overdraft estaba activo. onHold: type: string readOnly: true description: Refleja `onHold` en el momento consultado. overdraftLimitAvailable: type: string readOnly: true description: >- Margen restante de overdraft en el momento consultado. `"0"` cuando el overdraft estaba deshabilitado. Omitido completamente cuando el overdraft era ilimitado. createdAt: type: string format: date-time description: Timestamp de creación del saldo (UTC). updatedAt: type: string format: date-time description: Timestamp de última actualización en el momento consultado (UTC). ErrorFormat: type: object description: El mensaje de error de respuesta. required: - code - title - message properties: code: type: string description: Un identificador único y estable para el error. title: type: string description: Un breve resumen del problema. message: type: string description: Orientación detallada para resolver el error. entityType: type: string description: >- El tipo de entidad a la que se refiere el error (p. ej. organization, ledger, account, transaction). Opcional. fields: type: object additionalProperties: true description: Información adicional sobre los campos que causaron el error. BalanceSettings: type: object description: >- Configuración opcional por saldo que controla el comportamiento de overdraft y el alcance del saldo. properties: allowOverdraft: type: boolean description: >- Cuando `true`, el saldo puede ser debitado más allá de los fondos disponibles. Por defecto `false`. overdraftLimitEnabled: type: boolean description: >- Cuando `true`, debe informarse `overdraftLimit` — el saldo puede quedar negativo hasta ese valor. Cuando `false` con `allowOverdraft` `true`, el overdraft es ilimitado. overdraftLimit: type: string description: >- Monto máximo de overdraft como string decimal (ej., `"5000.00"`). Obligatorio cuando `overdraftLimitEnabled` es `true` y debe ser mayor que cero. Omita cuando el overdraft es ilimitado. balanceScope: type: string enum: - transactional - internal description: >- Alcance gestionado por el sistema. `transactional` es el predeterminado; `internal` marca saldos companion gestionados por el sistema (como el companion de overdraft) y bloquea operaciones directas de usuarios. 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. ````