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.
| 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-Connectionen REST y campoconnectionIden elexecutede MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale deconexiones.estado.consultar.
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
| 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
{
"$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
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":{}}'{
"tool": "bch_empresas.saldos.consultar_v2",
"params": {},
"connectionId": "conn_9tKfR2mQx4Vb"
}Salida esperada (200):
{
"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
| 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í |
saldos[].saldoContable | número | null | sí |
saldos[].lineaCredito | número | null | sí |
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í |
JSON Schema de salida
{
"$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
| 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.
Próximos pasos
bch_empresas.conexion.sincronizar: la tool que escribe los datos que esta lectura devuelve.- Sincronizar y consultar: por qué leer datos reales son dos pasos.