# Consultar saldos de BCI
> Lee la caché ya sincronizada; NO contacta al banco.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID** | `bci_pyme.saldos.consultar` |
| **Nombre MCP** | `bci_pyme__saldos__consultar` |
| **Conector** | `bci_pyme` |
| **Plano** | `action` |
| **Lee el alcance** | `saldos` (debe estar habilitado en la conexión) |
| **Scope (permiso)** | `bci_pyme:read` |
| **Auth** | `none` |
| **Versión** | `3` |
| **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, campo `connectionId` en el `execute` de MCP y en las opciones del SDK. 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`](../conexiones/estado-consultar).
## Qué hace [#qué-hace]
Devuelve los saldos guardados de esta conexión (contable, disponible, 9AM y retención), con el snapshot más reciente primero. Exige el alcance 'saldos' habilitado. Si nunca se sincronizó, devuelve una lista vacía: eso NO significa que la empresa no tenga cuentas. Para traer datos nuevos usa 'bci\_pyme.conexion.sincronizar' primero. Los saldos son un snapshot POR DÍA, así que sin filtro de fecha la primera página ya son los más recientes que hay guardados. Los cuatro saldos vienen como NÚMERO ya normalizado y conservan su signo: un sobregiro es negativo. Un saldo no lleva 'type' (no es una operación). 'ultimaLecturaEn' dice cuándo se leyó esa fila del banco: si es vieja, la conexión puede estar pausada. 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.
## 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}$"
},
"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/bci_pyme.saldos.consultar/execute \
-H "Authorization: Bearer connect_sk_…" \
-H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
-H "Content-Type: application/json" \
-d '{"input":{}}'
```
```ts title="SDK TypeScript"
const data = await connect.tools.bci_pyme.saldos.consultar({}, { connectionId: "conn_9tKfR2mQx4Vb" });
```
```json title="MCP · meta-tool execute"
{
"tool": "bci_pyme.saldos.consultar",
"params": {},
"connectionId": "conn_9tKfR2mQx4Vb"
}
```
**Salida esperada (200):**
```json
{
"data": {
"saldos": [
{
"numeroCuenta": "78012345",
"currency": "CLP",
"observedDay": "2026-08-07",
"observedAt": "2026-08-07T11:02:19.412Z",
"saldoContable": 4820500,
"saldoDisponible": 4715300,
"saldoContable9am": 4820500,
"retencion": 105200,
"ultimaLecturaEn": "2026-08-07T11:02:23.958Z"
}
],
"cursor": null
},
"meta": {
"request_id": "req_…",
"tool_id": "bci_pyme.saldos.consultar",
"plane": "action",
"latency_ms": 24,
"audit_status": "recorded"
}
}
```
> Sin filtros, la primera página ya es el snapshot más reciente de cada cuenta; 'cursor' null significa que no hay más páginas. Un saldo en 0 es un cero real; null significaría que el banco no trajo la celda.
## 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í | El número de la cuenta a la que pertenece esta fila, tal como lo entrega el portal de BCI. Es el mismo valor en saldos y movimientos, y el que espera el filtro 'numeroCuenta'. | |
| `saldos[].currency` | string | sí | La moneda de la cuenta, en código de tres letras (por ejemplo 'CLP'). Sale de la cuenta. | |
| `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[].observedAt` | string | sí | El instante exacto (ISO 8601) en que se tomó la foto, dentro del día de 'observedDay'. Todas las cuentas de una misma sincronización comparten este valor. | |
| `saldos[].saldoContable` | número | null | sí | El saldo contable de la cuenta, 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[].saldoDisponible` | número | null | sí | El saldo disponible de la cuenta, con el mismo criterio de signo y de 'null' que 'saldoContable'. |
| `saldos[].saldoContable9am` | número | null | sí | El saldo contable de las 9 de la mañana, que BCI publica como un campo aparte de los otros tres. Mismo criterio de signo y de 'null' que 'saldoContable'. |
| `saldos[].retencion` | número | null | sí | El monto retenido que BCI informa junto a los saldos. '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 tres 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": "El número de la cuenta a la que pertenece esta fila, tal como lo entrega el portal de BCI. Es el mismo valor en saldos y movimientos, y el que espera el filtro 'numeroCuenta'."
},
"currency": {
"type": "string",
"description": "La moneda de la cuenta, en código de tres letras (por ejemplo 'CLP'). Sale de la cuenta."
},
"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."
},
"observedAt": {
"type": "string",
"description": "El instante exacto (ISO 8601) en que se tomó la foto, dentro del día de 'observedDay'. Todas las cuentas de una misma sincronización comparten este valor."
},
"saldoContable": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "El saldo contable de la cuenta, 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."
},
"saldoDisponible": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "El saldo disponible de la cuenta, con el mismo criterio de signo y de 'null' que 'saldoContable'."
},
"saldoContable9am": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "El saldo contable de las 9 de la mañana, que BCI publica como un campo aparte de los otros tres. Mismo criterio de signo y de 'null' que 'saldoContable'."
},
"retencion": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "El monto retenido que BCI informa junto a los saldos. '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 tres fallos de credencial), así que este campo es lo que distingue un saldo recién leído de uno viejo."
}
},
"required": [
"numeroCuenta",
"currency",
"observedDay",
"observedAt",
"saldoContable",
"saldoDisponible",
"saldoContable9am",
"retencion",
"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. |
| `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](../errores).
## Próximos pasos [#próximos-pasos]
* [`bci_pyme.conexion.sincronizar`](./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.