# Consultar saldos de Banco de Chile en todas las monedas > Lee los saldos ya sincronizados en todas las monedas guardadas, con currency en cada fila. {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **Tool ID** | `bch_empresas.saldos.consultar_v2` | | **Nombre MCP** | `bch_empresas__saldos__consultar_v2` | | **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** | `2` | | **Sensible** | sí | | **Deprecado** | no | | **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] Conserva importes, decimales y signos en su moneda original; no los sumes entre monedas sin una conversión explícita. Los saldos son fotos por día, el más reciente primero; null significa dato no informado, nunca cero. No contacta al banco. Pagina con cursor y mantén los mismos filtros al continuar. Sustituye saldos.consultar, que conserva sólo CLP. ## 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. |
JSON Schema de entrada ```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 } } } ```
## Ejemplo [#ejemplo] ```bash title="curl" curl -X POST https://connect.emisso.ai/api/v1/tools/bch_empresas.saldos.consultar_v2/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_v2", "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_v2", "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í | Los snapshots de saldo guardados, el más reciente primero. Una lista vacía significa que esta conexión todavía no se sincronizó, no que la empresa no tenga cuentas. | | | `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í | Código de tres letras de la moneda declarada por la cuenta, por ejemplo CLP o USD. Los importes se conservan en esa moneda, sin conversión a pesos. Las consultas v2 incluyen todas las monedas guardadas: agrupa los totales por currency, sin sumar monedas distintas. | | | `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. |
JSON Schema de salida ```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": "Código de tres letras de la moneda declarada por la cuenta, por ejemplo CLP o USD. Los importes se conservan en esa moneda, sin conversión a pesos. Las consultas v2 incluyen todas las monedas guardadas: agrupa los totales por currency, sin sumar monedas distintas." }, "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": "Los snapshots de saldo guardados, el más reciente primero. Una lista vacía significa que esta conexión todavía no se sincronizó, no que la empresa no tenga cuentas." }, "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." } }, "required": [ "saldos", "cursor" ], "additionalProperties": false } ```
## 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.