# Consultar saldos BCI 360
> Consulta saldos de BCI 360 ya sincronizados, por cuenta y moneda.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID** | `bci_360.saldos.consultar` |
| **Nombre MCP** | `bci_360__saldos__consultar` |
| **Conector** | `bci_360` |
| **Plano** | `action` |
| **Lee el alcance** | `saldos` (debe estar habilitado en la conexión) |
| **Scope (permiso)** | `bci_360:read` |
| **Auth** | `none` |
| **Versión** | `1` |
| **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]
No abre una sesión bancaria.
## 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/bci_360.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_360.saldos.consultar({}, { connectionId: "conn_9tKfR2mQx4Vb" });
```
```json title="MCP · meta-tool execute"
{
"tool": "bci_360.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_360.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 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": "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 dos 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_360.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.