# Consultar saldos de Banco de Chile (versión anterior)

> Antes de pedir datos nuevos, consulta atenciones en conexiones.estado.consultar.



{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}

|                     |                                                                    |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID**         | `bch_empresas.saldos.consultar`                                    |
| **Nombre MCP**      | `bch_empresas__saldos__consultar`                                  |
| **Conector**        | `bch_empresas`                                                     |
| **Plano**           | `action`                                                           |
| **Lee el alcance**  | `saldos` (debe estar habilitado en la conexión)                    |
| **Scope (permiso)** | `bch_empresas:read`                                                |
| **Auth**            | `none`                                                             |
| **Versión**         | `1`                                                                |
| **Sensible**        | sí                                                                 |
| **Deprecado**       | sí                                                                 |
| **Comportamiento**  | readOnly=true, destructive=false, idempotent=true, openWorld=false |

> **Requiere conexión.** Indica cuál en cada llamada: header `X-Connect-Connection` en REST y campo `connectionId` en el `execute` de MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de [`conexiones.estado.consultar`](/docs/referencia/conexiones/estado-consultar).

## Qué hace [#qué-hace]

Si sincronizarSirve es false, sigue hacer: las indicaciones para pedir datos nuevos que siguen no aplican hasta resolver esa atención. La consulta de datos ya guardados sigue disponible según el plan. Versión anterior: prefiere bch\_empresas.saldos.consultar\_v2. Se mantiene por compatibilidad y solo devuelve CLP; usa la [versión recomendada](/docs/referencia/bch_empresas/saldos-consultar_v2) para todas las monedas con currency en cada fila. Lee los saldos ya sincronizados de esta conexión, con el snapshot más reciente primero. Lectura pura: NO contacta al banco ni dispara una sincronización. Si nunca se sincronizó, devuelve una lista vacía. Para traer datos nuevos, usa 'bch\_empresas.conexion.sincronizar' primero. Los saldos son un snapshot POR DÍA, así que sin filtro de fecha la primera página ya son los saldos más recientes que hay guardados. Los tres saldos vienen como NÚMERO y conservan su signo. Un saldo no lleva 'type' (no es una operación). 'saldoContable' puede venir null en filas sincronizadas antes del 2026-08-11, que es cuando se empezó a leer; desde entonces trae el saldo contable real, que difiere del disponible por retenciones y cheques en canje. Pagina con 'cursor': cuando la respuesta trae 'cursor' distinto de null hay más filas; reenvía ese valor tal cual, nunca lo construyas a mano. Trae una fila por cuenta, moneda y día, y cada fila indica su número de cuenta y su moneda. El orden es siempre el mismo: del día más reciente al más antiguo y, dentro de cada día, por número de cuenta y luego por moneda. Para obtener el saldo más reciente de una cuenta, filtra por 'numeroCuenta' y toma la primera fila de la moneda que buscas. Sin ese filtro, la primera fila es la cuenta de menor número, que puede no ser la que necesitas.

## Entrada [#entrada]

| Campo          | Tipo                         | Requerido          | Descripción                                                                                                                                                                             |
| -------------- | ---------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `observedDay`  | string `^\d{4}-\d{2}-\d{2}$` | no                 | Filtra por el día del snapshot, en formato AAAA-MM-DD. Sin él, la primera página ya trae los saldos más recientes que hay guardados de cada cuenta.                                     |
| `numeroCuenta` | string                       | no                 | Filtra por una sola cuenta, escrita igual que el 'numeroCuenta' de las filas. Sin él vienen todas las cuentas de la conexión.                                                           |
| `cursor`       | string                       | no                 | Para pedir la página siguiente: el valor que la respuesta anterior devolvió en 'cursor', tal cual. Nunca lo construyas ni lo edites a mano. Omítelo para empezar por la primera página. |
| `limit`        | entero 1-500                 | no · default `100` | Cuántas filas trae una página, entre 1 y 500. Por defecto, 100.                                                                                                                         |

<details>
  <summary>
    JSON Schema de entrada
  </summary>

  ```json
  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "observedDay": {
        "description": "Filtra por el día del snapshot, en formato AAAA-MM-DD. Sin él, la primera página ya trae los saldos más recientes que hay guardados de cada cuenta.",
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
        "x-emisso-formato": "AAAA-MM-DD"
      },
      "numeroCuenta": {
        "description": "Filtra por una sola cuenta, escrita igual que el 'numeroCuenta' de las filas. Sin él vienen todas las cuentas de la conexión.",
        "type": "string"
      },
      "cursor": {
        "description": "Para pedir la página siguiente: el valor que la respuesta anterior devolvió en 'cursor', tal cual. Nunca lo construyas ni lo edites a mano. Omítelo para empezar por la primera página.",
        "type": "string"
      },
      "limit": {
        "default": 100,
        "description": "Cuántas filas trae una página, entre 1 y 500. Por defecto, 100.",
        "type": "integer",
        "minimum": 1,
        "maximum": 500
      }
    }
  }
  ```
</details>

## Ejemplo [#ejemplo]

```bash title="curl"
curl -X POST https://connect.emisso.ai/api/v1/tools/bch_empresas.saldos.consultar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{}}'
```

```json title="MCP · meta-tool execute"
{
  "tool": "bch_empresas.saldos.consultar",
  "params": {},
  "connectionId": "conn_9tKfR2mQx4Vb"
}
```

**Salida esperada (200):**

```json
{
  "data": {
    "saldos": [
      {
        "numeroCuenta": "12345678",
        "codigoProducto": "CTD",
        "currency": "CLP",
        "observedDay": "2026-08-10",
        "saldoDisponible": 8462150,
        "saldoContable": 8501200,
        "lineaCredito": 0,
        "ultimaLecturaEn": "2026-08-10T14:02:11.000Z"
      }
    ],
    "cursor": null
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "bch_empresas.saldos.consultar",
    "plane": "action",
    "latency_ms": 24,
    "audit_status": "recorded"
  }
}
```

> 'saldoContable' difiere del disponible por retenciones y cheques en canje. Puede venir null en filas sincronizadas antes del 2026-08-11: hasta esa fecha no se leía.

## Salida [#salida]

| Campo                      | Tipo            | Requerido | Descripción                                                                                                                                                                                                                                                            |                                                                                                                                                                                                                                                 |
| -------------------------- | --------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `saldos`                   | lista de objeto | sí        | Saldos CLP guardados para estos filtros, el más reciente primero. Una lista vacía no acredita ausencia de cuentas; revisa el resultado de la sincronización.                                                                                                           |                                                                                                                                                                                                                                                 |
| `saldos[].numeroCuenta`    | string          | sí        | La cuenta a la que pertenece esta fila, con el código de producto adelante y sin el relleno de ceros del banco (por ejemplo 'CTD12345678'). Es el mismo valor en saldos, movimientos y cartolas, y el que espera el filtro 'numeroCuenta'.                             |                                                                                                                                                                                                                                                 |
| `saldos[].codigoProducto`  | string          | sí        | Las tres letras con que Banco de Chile identifica el tipo de producto de la cuenta (por ejemplo 'CTD'). Es el prefijo de 'numeroCuenta' y viene del propio banco.                                                                                                      |                                                                                                                                                                                                                                                 |
| `saldos[].currency`        | string          | sí        | Siempre CLP en la versión 1. Usa saldos.consultar\_v2 para todas las monedas guardadas.                                                                                                                                                                                |                                                                                                                                                                                                                                                 |
| `saldos[].observedDay`     | string          | sí        | El día (AAAA-MM-DD) de esta foto de saldos. Los saldos se guardan como un snapshot por día, así que sin filtro de fecha la primera página ya trae el más reciente de cada cuenta.                                                                                      |                                                                                                                                                                                                                                                 |
| `saldos[].saldoDisponible` | número          | null      | sí                                                                                                                                                                                                                                                                     | El saldo disponible de la cuenta ese día, como número y con su propio signo (un sobregiro es negativo). 'null' significa que el banco no trajo la celda, nunca 0: un 0 es un saldo real.                                                        |
| `saldos[].saldoContable`   | número          | null      | sí                                                                                                                                                                                                                                                                     | El saldo contable de la cuenta ese día. Difiere del disponible por retenciones y cheques en canje. Viene 'null' en las filas sincronizadas antes del 2026-08-11, que es cuando se empezó a leer; ese 'null' significa «no se leyó», nunca cero. |
| `saldos[].lineaCredito`    | número          | null      | sí                                                                                                                                                                                                                                                                     | El monto disponible de la línea de crédito de la cuenta, tal como lo informa el banco. 'null' significa que el banco no trajo la celda, nunca 0.                                                                                                |
| `saldos[].ultimaLecturaEn` | string          | sí        | Instante (ISO 8601) en que esta fila se leyó del banco por última vez. La caché puede quedarse quieta sin que la consulta falle (una conexión se auto-pausa tras dos fallos de credencial), así que este campo es lo que distingue un saldo recién leído de uno viejo. |                                                                                                                                                                                                                                                 |
| `cursor`                   | string          | null      | sí                                                                                                                                                                                                                                                                     | El cursor de la página siguiente. Distinto de null significa que quedan más filas: reenvíalo tal cual en 'cursor'. 'null' significa que esta es la última página.                                                                               |
| `otrasMonedas`             | objeto          | no        | Hay datos guardados en otras monedas dentro de los filtros pedidos. Este aviso sólo indica la consulta sucesora; no contiene sus filas ni importes.                                                                                                                    |                                                                                                                                                                                                                                                 |
| `otrasMonedas.consultarEn` | string          | sí        | Consulta sucesora para todas las monedas guardadas.                                                                                                                                                                                                                    |                                                                                                                                                                                                                                                 |

<details>
  <summary>
    JSON Schema de salida
  </summary>

  ```json
  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "saldos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "numeroCuenta": {
              "type": "string",
              "description": "La cuenta a la que pertenece esta fila, con el código de producto adelante y sin el relleno de ceros del banco (por ejemplo 'CTD12345678'). Es el mismo valor en saldos, movimientos y cartolas, y el que espera el filtro 'numeroCuenta'."
            },
            "codigoProducto": {
              "type": "string",
              "description": "Las tres letras con que Banco de Chile identifica el tipo de producto de la cuenta (por ejemplo 'CTD'). Es el prefijo de 'numeroCuenta' y viene del propio banco."
            },
            "currency": {
              "type": "string",
              "description": "Siempre CLP en la versión 1. Usa saldos.consultar_v2 para todas las monedas guardadas."
            },
            "observedDay": {
              "type": "string",
              "description": "El día (AAAA-MM-DD) de esta foto de saldos. Los saldos se guardan como un snapshot por día, así que sin filtro de fecha la primera página ya trae el más reciente de cada cuenta."
            },
            "saldoDisponible": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "description": "El saldo disponible de la cuenta ese día, como número y con su propio signo (un sobregiro es negativo). 'null' significa que el banco no trajo la celda, nunca 0: un 0 es un saldo real."
            },
            "saldoContable": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "description": "El saldo contable de la cuenta ese día. Difiere del disponible por retenciones y cheques en canje. Viene 'null' en las filas sincronizadas antes del 2026-08-11, que es cuando se empezó a leer; ese 'null' significa «no se leyó», nunca cero."
            },
            "lineaCredito": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "description": "El monto disponible de la línea de crédito de la cuenta, tal como lo informa el banco. 'null' significa que el banco no trajo la celda, nunca 0."
            },
            "ultimaLecturaEn": {
              "type": "string",
              "description": "Instante (ISO 8601) en que esta fila se leyó del banco por última vez. La caché puede quedarse quieta sin que la consulta falle (una conexión se auto-pausa tras dos fallos de credencial), así que este campo es lo que distingue un saldo recién leído de uno viejo."
            }
          },
          "required": [
            "numeroCuenta",
            "codigoProducto",
            "currency",
            "observedDay",
            "saldoDisponible",
            "saldoContable",
            "lineaCredito",
            "ultimaLecturaEn"
          ],
          "additionalProperties": false
        },
        "description": "Saldos CLP guardados para estos filtros, el más reciente primero. Una lista vacía no acredita ausencia de cuentas; revisa el resultado de la sincronización."
      },
      "cursor": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "El cursor de la página siguiente. Distinto de null significa que quedan más filas: reenvíalo tal cual en 'cursor'. 'null' significa que esta es la última página."
      },
      "otrasMonedas": {
        "description": "Hay datos guardados en otras monedas dentro de los filtros pedidos. Este aviso sólo indica la consulta sucesora; no contiene sus filas ni importes.",
        "type": "object",
        "properties": {
          "consultarEn": {
            "type": "string",
            "const": "bch_empresas.saldos.consultar_v2",
            "description": "Consulta sucesora para todas las monedas guardadas."
          }
        },
        "required": [
          "consultarEn"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "saldos",
      "cursor"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Errores de esta tool [#errores-de-esta-tool]

| Código                 | HTTP | Reintentable | Qué hacer                                                                                                           |
| ---------------------- | ---- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `connection_disabled`  | 403  | no           | Reactívala en /connections o usa otra conexión del mismo sistema.                                                   |
| `connection_not_found` | 404  | no           | Usa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada. |
| `alcance_not_enabled`  | 403  | no           | Habilita el alcance en /connections o quítalo del input de la sincronización.                                       |

Toda llamada puede devolver además los códigos transversales (`validation_error`, `unauthorized`, `scope_not_granted`, `rate_limited`, entre otros): el detalle vive en el [catálogo de errores](/docs/referencia/errores).

## Próximos pasos [#próximos-pasos]

* [`bch_empresas.conexion.sincronizar`](/docs/referencia/bch_empresas/conexion-sincronizar): la tool que escribe los datos que esta lectura devuelve.
* [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar): por qué leer datos reales son dos pasos.


---

Esta página es parte de la documentación de Emisso. El índice completo, con cada página y su descripción, está en https://connect.emisso.ai/llms.txt. Esta misma página en HTML: https://connect.emisso.ai/docs/referencia/bch_empresas/saldos-consultar.
