# Consultar líneas de una cartola histórica de Banco de Chile > Lee un extracto ya sincronizado y pagina sus líneas XLS por cuenta y fecha de emisión. {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **Tool ID** | `bch_empresas.cartolas.detalle` | | **Nombre MCP** | `bch_empresas__cartolas__detalle` | | **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** | 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 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`](/docs/referencia/conexiones/estado-consultar). ## Qué hace [#qué-hace] No contacta al banco: primero sincroniza el alcance cartolas. La descarga alternativa XLS se usa solo cuando MT940 no está habilitado. Conserva repeticiones y documentos textuales; no ofrece contraparte estructurada ni IDs equivalentes al feed de movimientos. Una cartola MT940 puede existir con lineas null: su ruta actual no obtiene estas líneas. ## Entrada [#entrada] | Campo | Tipo | Requerido | Descripción | | ----------------- | ---------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `numeroCuenta` | string | sí | Cuenta canónica tal como la devuelve cartolas.consultar, incluido el código de producto. | | `fechaEmisionDay` | string `^\d{4}-\d{2}-\d{2}$` | sí | Día de emisión del extracto en AAAA-MM-DD, sin zona horaria; no es el período pedido al sincronizar. | | `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-200 | no · default `100` | Máximo de líneas por página, entre 1 y 200; por omisión 100. |
JSON Schema de entrada ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "numeroCuenta": { "type": "string", "minLength": 1, "description": "Cuenta canónica tal como la devuelve cartolas.consultar, incluido el código de producto." }, "fechaEmisionDay": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "x-emisso-formato": "AAAA-MM-DD", "description": "Día de emisión del extracto en AAAA-MM-DD, sin zona horaria; no es el período pedido al sincronizar." }, "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": "Máximo de líneas por página, entre 1 y 200; por omisión 100.", "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "numeroCuenta", "fechaEmisionDay" ] } ```
## Ejemplo [#ejemplo] ```bash title="curl" curl -X POST https://connect.emisso.ai/api/v1/tools/bch_empresas.cartolas.detalle/execute \ -H "Authorization: Bearer connect_sk_…" \ -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \ -H "Content-Type: application/json" \ -d '{"input":{"numeroCuenta":"CTD12345678","fechaEmisionDay":"2026-07-31","limit":100}}' ``` ```json title="MCP · meta-tool execute" { "tool": "bch_empresas.cartolas.detalle", "params": { "numeroCuenta": "CTD12345678", "fechaEmisionDay": "2026-07-31", "limit": 100 }, "connectionId": "conn_9tKfR2mQx4Vb" } ``` **Salida esperada (200):** ```json { "data": { "cartola": { "numeroCuenta": "CTD12345678", "tipoProducto": "CTD", "currency": "CLP", "fechaEmisionDay": "2026-07-31", "periodo": "2026-07", "numeroCartola": null, "saldoInicial": null, "saldoFinal": null, "ultimaLecturaEn": "2026-08-10T14:05:00Z" }, "formatoLineas": "xls_texto", "lineas": [ { "fecha": "2026-07-15", "glosa": "Abono sintético", "cargo": 0, "abono": 1234, "saldo": 5234, "numeroDocumento": "00000123", "transaccion": "0000", "caja": "0000", "sucursal": "OFICINA" } ], "totalLineas": 1, "lineasLeidasEn": "2026-08-10T14:05:00Z", "cursor": null }, "meta": { "request_id": "req_…", "tool_id": "bch_empresas.cartolas.detalle", "plane": "action", "latency_ms": 24, "audit_status": "recorded" } } ``` > Datos sintéticos. Las líneas pertenecen al extracto; no se deduplican ni se mezclan con movimientos. ## Salida [#salida] | Campo | Tipo | Requerido | Descripción | | | -------------------------- | --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cartola` | objeto | null | sí | Resumen del extracto persistido; null si todavía no está guardado. | | `cartola.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'. | | | `cartola.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. | | | `cartola.currency` | string | sí | La moneda de la cuenta, en código de tres letras (por ejemplo 'CLP'). Sale de la cuenta y nunca se asume: este alcance solo persiste cuentas en pesos chilenos y saltea las demás, avisándolo en el 'detalle' de la sincronización. | | | `cartola.fechaEmisionDay` | string | sí | El día (AAAA-MM-DD) en que el banco emitió este extracto. Junto con la cuenta es lo que identifica a la cartola, y es lo que filtra el 'fechaEmisionDay' de la entrada. | | | `cartola.periodo` | string | sí | El mes (AAAA-MM) con el que se buscó esta cartola, que no es la fecha del extracto: esa es 'fechaEmisionDay'. | | | `cartola.numeroCartola` | string | null | sí | El número correlativo del extracto (tag 28C del MT940), SIEMPRE como texto: convertirlo a número le come los ceros a la izquierda. 'null' cuando el extracto descargado no trae el tag. | | `cartola.saldoInicial` | número | null | sí | El saldo de apertura del extracto (tag 60 del MT940), con su propio signo: en MT940 la marca 'D' es un sobregiro y sale negativa. 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. | | `cartola.saldoFinal` | número | null | sí | El saldo de cierre del extracto (tag 62 del MT940), con el mismo criterio de signo y la misma advertencia de cuadratura que 'saldoInicial'. | | `cartola.ultimaLecturaEn` | string | sí | Instante (ISO 8601) en que esta cartola se leyó del banco por última vez. | | | `formatoLineas` | string | null | sí | Formato del que se obtuvieron las líneas. null si no se descargó un XLS válido. | | `lineas` | lista de objeto | null | sí | Página de líneas del extracto, en su orden original y con repeticiones. No son IDs ni filas del feed de movimientos. null cuando no hay líneas XLS persistidas, incluso si existe un resumen MT940. No implica ausencia de operaciones. | | `lineas[].fecha` | string | null | sí | La fecha de la línea del extracto, sin equipararla a la fecha contable del feed en formato AAAA-MM-DD, o null si no se pudo parsear. Es un día calendario sin zona horaria: compáralo como texto o con Date.UTC, porque new Date('2026-09-07') es medianoche UTC y en Chile se muestra como el 6. Es el campo que conviene usar para ordenar y filtrar. | | `lineas[].glosa` | string | null | sí | Detalle del movimiento impreso en el extracto; null si la celda está vacía. No acredita una contraparte estructurada. | | `lineas[].cargo` | número | sí | Cheque o cargo, en pesos CLP, con el signo declarado en el archivo. | | | `lineas[].abono` | número | sí | Depósito o abono, en pesos CLP, con el signo declarado en el archivo. | | | `lineas[].saldo` | número | sí | Saldo de esta línea del extracto en pesos CLP; puede diferir del saldo del feed de movimientos. | | | `lineas[].numeroDocumento` | string | null | sí | Número de documento como texto, conservando ceros a la izquierda. null si la celda está vacía; no es un ID único. | | `lineas[].transaccion` | string | null | sí | Campo Trn del archivo, como texto. Puede venir en ceros; null si está vacío. | | `lineas[].caja` | string | null | sí | Código de caja como texto, incluidos sus ceros. null si está vacío. | | `lineas[].sucursal` | string | null | sí | Sucursal declarada en el archivo. null si la celda está vacía. | | `totalLineas` | entero | null | sí | Cantidad total de líneas del XLS persistido; null si no se ha obtenido. | | `lineasLeidasEn` | string | null | sí | Instante ISO 8601 con zona UTC (Z) de captura de estas líneas, independiente de una lectura posterior de MT940. null si no se han leído. | | `cursor` | string | null | sí | Puntero opaco a la siguiente página de este mismo extracto. null al terminar. Si se vuelve a sincronizar el XLS, reinicia la lectura sin cursor. |
JSON Schema de salida ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cartola": { "anyOf": [ { "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": "La moneda de la cuenta, en código de tres letras (por ejemplo 'CLP'). Sale de la cuenta y nunca se asume: este alcance solo persiste cuentas en pesos chilenos y saltea las demás, avisándolo en el 'detalle' de la sincronización." }, "fechaEmisionDay": { "type": "string", "description": "El día (AAAA-MM-DD) en que el banco emitió este extracto. Junto con la cuenta 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 (tag 28C del MT940), SIEMPRE como texto: convertirlo a número le come los ceros a la izquierda. 'null' cuando el extracto descargado no trae el tag." }, "saldoInicial": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "El saldo de apertura del extracto (tag 60 del MT940), con su propio signo: en MT940 la marca 'D' es un sobregiro y sale negativa. 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 (tag 62 del MT940), 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 }, { "type": "null" } ], "description": "Resumen del extracto persistido; null si todavía no está guardado." }, "formatoLineas": { "anyOf": [ { "type": "string", "const": "xls_texto" }, { "type": "null" } ], "description": "Formato del que se obtuvieron las líneas. null si no se descargó un XLS válido." }, "lineas": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "fecha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "x-emisso-formato": "AAAA-MM-DD", "description": "La fecha de la línea del extracto, sin equipararla a la fecha contable del feed en formato AAAA-MM-DD, o null si no se pudo parsear. Es un día calendario sin zona horaria: compáralo como texto o con Date.UTC, porque new Date('2026-09-07') es medianoche UTC y en Chile se muestra como el 6. Es el campo que conviene usar para ordenar y filtrar." }, "glosa": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Detalle del movimiento impreso en el extracto; null si la celda está vacía. No acredita una contraparte estructurada." }, "cargo": { "type": "number", "description": "Cheque o cargo, en pesos CLP, con el signo declarado en el archivo." }, "abono": { "type": "number", "description": "Depósito o abono, en pesos CLP, con el signo declarado en el archivo." }, "saldo": { "type": "number", "description": "Saldo de esta línea del extracto en pesos CLP; puede diferir del saldo del feed de movimientos." }, "numeroDocumento": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Número de documento como texto, conservando ceros a la izquierda. null si la celda está vacía; no es un ID único." }, "transaccion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Campo Trn del archivo, como texto. Puede venir en ceros; null si está vacío." }, "caja": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código de caja como texto, incluidos sus ceros. null si está vacío." }, "sucursal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sucursal declarada en el archivo. null si la celda está vacía." } }, "required": [ "fecha", "glosa", "cargo", "abono", "saldo", "numeroDocumento", "transaccion", "caja", "sucursal" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Página de líneas del extracto, en su orden original y con repeticiones. No son IDs ni filas del feed de movimientos. null cuando no hay líneas XLS persistidas, incluso si existe un resumen MT940. No implica ausencia de operaciones." }, "totalLineas": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Cantidad total de líneas del XLS persistido; null si no se ha obtenido." }, "lineasLeidasEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Instante ISO 8601 con zona UTC (Z) de captura de estas líneas, independiente de una lectura posterior de MT940. null si no se han leído." }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Puntero opaco a la siguiente página de este mismo extracto. null al terminar. Si se vuelve a sincronizar el XLS, reinicia la lectura sin cursor." } }, "required": [ "cartola", "formatoLineas", "lineas", "totalLineas", "lineasLeidasEn", "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. | | `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](/docs/referencia/errores). ## Próximos pasos [#próximos-pasos] * [`bch_empresas.conexion.sincronizar`](/docs/referencia/bch_empresas/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.