Consultar cartolas emitidas de Banco de Chile (versión anterior)
Antes de pedir datos nuevos, consulta atenciones en conexiones.estado.consultar.
| Tool ID | bch_empresas.cartolas.consultar |
| Nombre MCP | bch_empresas__cartolas__consultar |
| Conector | bch_empresas |
| Plano | action |
| Lee el alcance | cartolas (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-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
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.cartolas.consultar_v2. Se mantiene por compatibilidad y solo devuelve CLP; usa la versión recomendada para todas las monedas con currency en cada fila. Lee las cartolas (extractos mensuales) ya sincronizadas de esta conexión, la más reciente primero, filtrables por período de búsqueda (AAAA-MM) y por cuenta. Lectura pura: NO contacta al banco ni dispara una sincronización. Para traer datos nuevos, usa 'bch_empresas.conexion.sincronizar' primero. Una cartola es un OBJETO propio, no una vista de 'movimientos': sus saldos de apertura y cierre pueden no cuadrar exactamente con la suma de movimientos del mismo mes porque el extracto encadena por fecha contable y el feed vivo por fecha del movimiento. 'numeroCartola' es TEXTO siempre (convertirlo a número pierde ceros a la izquierda). 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
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
fechaEmisionDay | string ^\d{4}-\d{2}-\d{2}$ | no | Filtra por el día en que el banco emitió el extracto, en formato AAAA-MM-DD. |
periodo | string ^\d{4}-\d{2}$ | no | Filtra por el mes (AAAA-MM) con el que se BUSCÓ la cartola, que no es su fecha de emisión: para esa usa 'fechaEmisionDay'. Sin él, la respuesta cruza todos los períodos guardados. |
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": {
"fechaEmisionDay": {
"description": "Filtra por el día en que el banco emitió el extracto, en formato AAAA-MM-DD.",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"x-emisso-formato": "AAAA-MM-DD"
},
"periodo": {
"description": "Filtra por el mes (AAAA-MM) con el que se BUSCÓ la cartola, que no es su fecha de emisión: para esa usa 'fechaEmisionDay'. Sin él, la respuesta cruza todos los períodos guardados.",
"type": "string",
"pattern": "^\\d{4}-\\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
curl -X POST https://connect.emisso.ai/api/v1/tools/bch_empresas.cartolas.consultar/execute \
-H "Authorization: Bearer connect_sk_…" \
-H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
-H "Content-Type: application/json" \
-d '{"input":{"periodo":"2026-07"}}'{
"tool": "bch_empresas.cartolas.consultar",
"params": {
"periodo": "2026-07"
},
"connectionId": "conn_9tKfR2mQx4Vb"
}Salida esperada (200):
{
"data": {
"cartolas": [
{
"numeroCuenta": "CTD12345678",
"tipoProducto": "CTD",
"currency": "CLP",
"fechaEmisionDay": "2026-07-31",
"periodo": "2026-07",
"numeroCartola": "00042",
"saldoInicial": 8462150,
"saldoFinal": 4370480,
"ultimaLecturaEn": "2026-08-10T14:02:11.000Z"
}
],
"cursor": null
},
"meta": {
"request_id": "req_…",
"tool_id": "bch_empresas.cartolas.consultar",
"plane": "action",
"latency_ms": 24,
"audit_status": "recorded"
}
}'numeroCartola' preserva los ceros a la izquierda: nunca se convierte a número.
Salida
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
cartolas | lista de objeto | sí | Cartolas CLP guardadas para estos filtros, la más reciente primero. Una lista vacía no acredita ausencia de extractos en el banco; revisa el resultado de la sincronización. |
cartolas[].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'. |
cartolas[].tipoProducto | string | sí | El tipo de producto de la cuenta según el índice de cartolas del banco (por ejemplo 'CTD'). Cuando el índice no lo trae, cae al código de producto de la cuenta. |
cartolas[].currency | string | sí | Siempre CLP en la versión 1. Usa cartolas.consultar_v2 para todas las monedas guardadas. |
cartolas[].fechaEmisionDay | string | sí | El día (AAAA-MM-DD) en que el banco emitió este extracto. Junto con la cuenta y la moneda es lo que identifica a la cartola, y es lo que filtra el 'fechaEmisionDay' de la entrada. |
cartolas[].periodo | string | sí | El mes (AAAA-MM) con el que se buscó esta cartola, que no es la fecha del extracto: esa es 'fechaEmisionDay'. |
cartolas[].numeroCartola | string | null | sí |
cartolas[].saldoInicial | número | null | sí |
cartolas[].saldoFinal | número | null | sí |
cartolas[].ultimaLecturaEn | string | sí | Instante (ISO 8601) en que esta cartola se leyó del banco por última vez. |
cursor | string | null | sí |
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. |
JSON Schema de salida
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"cartolas": {
"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'."
},
"tipoProducto": {
"type": "string",
"description": "El tipo de producto de la cuenta según el índice de cartolas del banco (por ejemplo 'CTD'). Cuando el índice no lo trae, cae al código de producto de la cuenta."
},
"currency": {
"type": "string",
"description": "Siempre CLP en la versión 1. Usa cartolas.consultar_v2 para todas las monedas guardadas."
},
"fechaEmisionDay": {
"type": "string",
"description": "El día (AAAA-MM-DD) en que el banco emitió este extracto. Junto con la cuenta y la moneda es lo que identifica a la cartola, y es lo que filtra el 'fechaEmisionDay' de la entrada."
},
"periodo": {
"type": "string",
"description": "El mes (AAAA-MM) con el que se buscó esta cartola, que no es la fecha del extracto: esa es 'fechaEmisionDay'."
},
"numeroCartola": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El número correlativo del extracto, SIEMPRE como texto: convertirlo a número le come los ceros a la izquierda. 'null' cuando el extracto no lo declara."
},
"saldoInicial": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "El saldo de apertura del extracto, en la moneda de la cuenta y con su propio signo: un sobregiro sale negativo. No cuadra necesariamente con la suma de 'movimientos' del mismo mes, porque el extracto encadena por fecha contable y el feed vivo por fecha del movimiento. 'null' cuando el extracto no lo declara."
},
"saldoFinal": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "El saldo de cierre del extracto, en la moneda de la cuenta, con el mismo criterio de signo y la misma advertencia de cuadratura que 'saldoInicial'."
},
"ultimaLecturaEn": {
"type": "string",
"description": "Instante (ISO 8601) en que esta cartola se leyó del banco por última vez."
}
},
"required": [
"numeroCuenta",
"tipoProducto",
"currency",
"fechaEmisionDay",
"periodo",
"numeroCartola",
"saldoInicial",
"saldoFinal",
"ultimaLecturaEn"
],
"additionalProperties": false
},
"description": "Cartolas CLP guardadas para estos filtros, la más reciente primero. Una lista vacía no acredita ausencia de extractos en el banco; 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.cartolas.consultar_v2",
"description": "Consulta sucesora para todas las monedas guardadas."
}
},
"required": [
"consultarEn"
],
"additionalProperties": false
}
},
"required": [
"cartolas",
"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.