ReferenciaBanco de Chile Empresas

Consultar cartolas emitidas de Banco de Chile (versión anterior)

Antes de pedir datos nuevos, consulta atenciones en conexiones.estado.consultar.

Tool IDbch_empresas.cartolas.consultar
Nombre MCPbch_empresas__cartolas__consultar
Conectorbch_empresas
Planoaction
Lee el alcancecartolas (debe estar habilitado en la conexión)
Scope (permiso)bch_empresas:read
Authnone
Versión1
Sensiblesí
Deprecadosí
ComportamientoreadOnly=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.

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

CampoTipoRequeridoDescripción
fechaEmisionDaystring ^\d{4}-\d{2}-\d{2}$noFiltra por el día en que el banco emitió el extracto, en formato AAAA-MM-DD.
periodostring ^\d{4}-\d{2}$noFiltra 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.
numeroCuentastringnoFiltra por una sola cuenta, escrita igual que el 'numeroCuenta' de las filas. Sin él vienen todas las cuentas de la conexión.
cursorstringnoPara 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.
limitentero 1-500no · default 100Cuá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
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"}}'
MCP · meta-tool execute
{
  "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

CampoTipoRequeridoDescripción
cartolaslista de objetosí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[].numeroCuentastringsí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[].tipoProductostringsí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[].currencystringsíSiempre CLP en la versión 1. Usa cartolas.consultar_v2 para todas las monedas guardadas.
cartolas[].fechaEmisionDaystringsí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[].periodostringsíEl mes (AAAA-MM) con el que se buscó esta cartola, que no es la fecha del extracto: esa es 'fechaEmisionDay'.
cartolas[].numeroCartolastringnullsí
cartolas[].saldoInicialnúmeronullsí
cartolas[].saldoFinalnúmeronullsí
cartolas[].ultimaLecturaEnstringsíInstante (ISO 8601) en que esta cartola se leyó del banco por última vez.
cursorstringnullsí
otrasMonedasobjetonoHay 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.consultarEnstringsí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ódigoHTTPReintentableQué hacer
connection_disabled403noReactívala en /connections o usa otra conexión del mismo sistema.
connection_not_found404noUsa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada.
alcance_not_enabled403noHabilita 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

En esta página