# Consultar movimientos de BCI > Lee la caché ya sincronizada; NO contacta al banco. {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **Tool ID** | `bci_pyme.movimientos.consultar` | | **Nombre MCP** | `bci_pyme__movimientos__consultar` | | **Conector** | `bci_pyme` | | **Plano** | `action` | | **Lee el alcance** | `movimientos` (debe estar habilitado en la conexión) | | **Scope (permiso)** | `bci_pyme:read` | | **Auth** | `none` | | **Versión** | `3` | | **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] Devuelve los movimientos guardados de esta conexión, del más reciente al más antiguo, filtrables por período (AAAA-MM) y por cuenta. Exige el alcance 'movimientos' habilitado. Si el período nunca se sincronizó, devuelve una lista vacía, que NO significa que no haya movimientos; usa 'bci\_pyme.conexion.sincronizar' primero. 'completo' dice si el último sync de ESE período trajo todo: BCI corta en 1000 movimientos por cuenta y mes, y 'completo: false' significa que faltan filas. Sin filtro de 'periodo' vale null, o sea «no se sabe». Ojo con las correcciones del banco: un movimiento corregido entra como fila NUEVA en vez de reemplazar a la anterior, así que ante dos filas del mismo movimiento vale la de 'ultimaLecturaEn' mayor. Los montos vienen como NÚMERO: 'monto' es la magnitud sin signo, 'type' dice si entra ('debit') o sale ('credit') plata según el libro del banco (al revés de como se lee una cartola) y 'display' es ese monto ya formateado a la chilena con su signo. 'saldoContable' es un balance: no lleva 'type' y conserva su propio signo. 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 [#entrada] | Campo | Tipo | Requerido | Descripción | | -------------- | ---------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `periodo` | string `^\d{4}-\d{2}$` | no | Filtra por el mes (AAAA-MM) con el que se sincronizó la fila. Sin él, la respuesta cruza todos los períodos guardados y 'completo' llega en null. | | `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": { "periodo": { "description": "Filtra por el mes (AAAA-MM) con el que se sincronizó la fila. Sin él, la respuesta cruza todos los períodos guardados y 'completo' llega en null.", "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 [#ejemplo] ```bash title="curl" curl -X POST https://connect.emisso.ai/api/v1/tools/bci_pyme.movimientos.consultar/execute \ -H "Authorization: Bearer connect_sk_…" \ -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \ -H "Content-Type: application/json" \ -d '{"input":{"periodo":"2026-07"}}' ``` ```ts title="SDK TypeScript" const data = await connect.tools.bci_pyme.movimientos.consultar({ periodo: "2026-07" }, { connectionId: "conn_9tKfR2mQx4Vb" }); ``` ```json title="MCP · meta-tool execute" { "tool": "bci_pyme.movimientos.consultar", "params": { "periodo": "2026-07" }, "connectionId": "conn_9tKfR2mQx4Vb" } ``` **Salida esperada (200):** ```json { "data": { "movimientos": [ { "numeroCuenta": "78012345", "periodo": "2026-07", "fechaMovimiento": "2026-07-28T00:00:00.000Z", "fechaContable": "2026-07-28T00:00:00.000Z", "descripcion": "Pago a proveedor", "monto": 890750, "type": "credit", "display": "-890.750", "saldoContable": 4370480, "category": "Transferencias", "mnemonico": "TRF", "counterparty": { "name": "Proveedora del Maule SpA", "rut": "77123456-9", "bank": "Banco de Chile", "account": null }, "ultimaLecturaEn": "2026-08-01T07:12:45.310Z" }, { "numeroCuenta": "78012345", "periodo": "2026-07", "fechaMovimiento": "2026-07-15T00:00:00.000Z", "fechaContable": "2026-07-15T00:00:00.000Z", "descripcion": "Abono cliente", "monto": 1450000, "type": "debit", "display": "1.450.000", "saldoContable": 5261230, "category": "Depositos", "mnemonico": "DEP", "counterparty": { "name": "Distribuidora Andina Ltda", "rut": "76543210-3", "bank": null, "account": null }, "ultimaLecturaEn": "2026-08-01T07:12:45.310Z" } ], "cursor": null, "completo": true }, "meta": { "request_id": "req_…", "tool_id": "bci_pyme.movimientos.consultar", "plane": "action", "latency_ms": 24, "audit_status": "recorded" } } ``` > El abono del cliente entra como 'debit' y el pago al proveedor como 'credit': es la convención del libro del banco, al revés de la cartola, y 'display' ya trae el signo aplicado. 'completo' en true porque la llamada filtró por período y el último sync de ese mes trajo todo. ## Salida [#salida] | Campo | Tipo | Requerido | Descripción | | | ------------------------------------ | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `movimientos` | lista de objeto | sí | Los movimientos guardados, del más reciente al más antiguo. Una lista vacía significa que ese período todavía no se sincronizó, no que no haya movimientos. | | | `movimientos[].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'. | | | `movimientos[].periodo` | string | sí | El mes (AAAA-MM) con el que se sincronizó esta fila. Es la ventana con que se pidió, no una propiedad del movimiento: la fecha vive en 'fechaMovimiento'. Es el valor con el que filtra el 'periodo' de la entrada. | | | `movimientos[].fechaMovimiento` | string | null | sí | La fecha del movimiento (ISO 8601), tal como la entrega el banco. 'null' cuando no la trajo. | | `movimientos[].fechaContable` | string | null | sí | La fecha contable del movimiento (ISO 8601), que puede diferir de 'fechaMovimiento'. 'null' cuando el banco no la trajo. | | `movimientos[].descripcion` | string | null | sí | La glosa del movimiento, tal como la escribe el banco. 'null' cuando llega vacía. | | `movimientos[].monto` | número | null | sí | La magnitud del movimiento SIN signo. El sentido lo da 'type' y el signo visible, 'display'. 'null' significa que el banco no trajo la celda, nunca 0. | | `movimientos[].type` | `"credit"` · `"debit"` | null | sí | Eje crédito/débito del LIBRO DEL BANCO, no el de la cartola: 'debit' es plata que ENTRA a la cuenta (un abono) y 'credit' es plata que SALE (un cargo). Es al revés de la lectura intuitiva y está así a propósito. El campo 'monto' es la magnitud SIN signo; el signo lo lleva 'display' ('credit' → negativo). 'null' significa que el banco no informó el tipo: no asumas ninguno de los dos. | | `movimientos[].display` | string | null | sí | El monto ya formateado a la chilena y CON signo, derivado de 'type' ('credit', plata que sale, se muestra negativo). Es una comodidad de presentación: se calcula en la lectura y no se persiste. Para operar con el número usa 'monto' (magnitud sin signo) junto con 'type'. | | `movimientos[].saldoContable` | número | null | sí | El saldo de la cuenta después de este movimiento. Es un balance: no lleva 'type' y conserva su propio signo, así que un sobregiro es negativo. | | `movimientos[].category` | string | null | sí | La categoría con que el propio BCI clasifica el movimiento (por ejemplo 'Transferencias'). Es una etiqueta del banco, no un vocabulario de Connect: puede cambiar sin aviso. 'null' cuando el banco no la trae. | | `movimientos[].mnemonico` | string | null | sí | El código corto de transacción del propio BCI (por ejemplo 'TRF'). Es una etiqueta del banco sin catálogo publicado: sirve para agrupar movimientos del mismo tipo, no para deducir qué fue la operación. 'null' cuando el banco no lo trae. | | `movimientos[].counterparty` | objeto | sí | La contraparte del movimiento, extraída del detalle que adjunta el banco. Los cuatro campos vienen en 'null' cuando el movimiento no trae detalle, que es lo normal fuera de las transferencias. Son datos personales de terceros: trátalos como tales. | | | `movimientos[].counterparty.name` | string | null | sí | El nombre o razón social de la contraparte. 'null' cuando el detalle no lo trae. | | `movimientos[].counterparty.rut` | string | null | sí | El RUT de la contraparte, tal cual. 'null' cuando el detalle no lo trae. | | `movimientos[].counterparty.bank` | string | null | sí | El banco de la contraparte. 'null' cuando el detalle no lo trae. | | `movimientos[].counterparty.account` | string | null | sí | El número de cuenta de la contraparte. 'null' cuando el detalle no lo trae. | | `movimientos[].ultimaLecturaEn` | string | sí | Instante (ISO 8601) en que esta fila se leyó del banco por última vez. Una corrección del banco entra como fila NUEVA en vez de reemplazar a la anterior, así que ante dos filas del mismo movimiento vale la de 'ultimaLecturaEn' mayor. | | | `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. | | `completo` | booleano | null | sí | Si el último sync de ESE período trajo todo. BCI corta en 1000 movimientos por cuenta y mes, así que 'false' significa que faltan filas del mes. 'null' significa «no se sabe», y es lo que devuelve una consulta sin filtro de 'periodo': nunca lo leas como un 'true'. |
JSON Schema de salida ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "movimientos": { "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'." }, "periodo": { "type": "string", "description": "El mes (AAAA-MM) con el que se sincronizó esta fila. Es la ventana con que se pidió, no una propiedad del movimiento: la fecha vive en 'fechaMovimiento'. Es el valor con el que filtra el 'periodo' de la entrada." }, "fechaMovimiento": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "La fecha del movimiento (ISO 8601), tal como la entrega el banco. 'null' cuando no la trajo." }, "fechaContable": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "La fecha contable del movimiento (ISO 8601), que puede diferir de 'fechaMovimiento'. 'null' cuando el banco no la trajo." }, "descripcion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "La glosa del movimiento, tal como la escribe el banco. 'null' cuando llega vacía." }, "monto": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "La magnitud del movimiento SIN signo. El sentido lo da 'type' y el signo visible, 'display'. 'null' significa que el banco no trajo la celda, nunca 0." }, "type": { "anyOf": [ { "type": "string", "enum": [ "credit", "debit" ] }, { "type": "null" } ], "description": "Eje crédito/débito del LIBRO DEL BANCO, no el de la cartola: 'debit' es plata que ENTRA a la cuenta (un abono) y 'credit' es plata que SALE (un cargo). Es al revés de la lectura intuitiva y está así a propósito. El campo 'monto' es la magnitud SIN signo; el signo lo lleva 'display' ('credit' → negativo). 'null' significa que el banco no informó el tipo: no asumas ninguno de los dos." }, "display": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El monto ya formateado a la chilena y CON signo, derivado de 'type' ('credit', plata que sale, se muestra negativo). Es una comodidad de presentación: se calcula en la lectura y no se persiste. Para operar con el número usa 'monto' (magnitud sin signo) junto con 'type'." }, "saldoContable": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "El saldo de la cuenta después de este movimiento. Es un balance: no lleva 'type' y conserva su propio signo, así que un sobregiro es negativo." }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "La categoría con que el propio BCI clasifica el movimiento (por ejemplo 'Transferencias'). Es una etiqueta del banco, no un vocabulario de Connect: puede cambiar sin aviso. 'null' cuando el banco no la trae." }, "mnemonico": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El código corto de transacción del propio BCI (por ejemplo 'TRF'). Es una etiqueta del banco sin catálogo publicado: sirve para agrupar movimientos del mismo tipo, no para deducir qué fue la operación. 'null' cuando el banco no lo trae." }, "counterparty": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El nombre o razón social de la contraparte. 'null' cuando el detalle no lo trae." }, "rut": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El RUT de la contraparte, tal cual. 'null' cuando el detalle no lo trae." }, "bank": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El banco de la contraparte. 'null' cuando el detalle no lo trae." }, "account": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El número de cuenta de la contraparte. 'null' cuando el detalle no lo trae." } }, "required": [ "name", "rut", "bank", "account" ], "additionalProperties": false, "description": "La contraparte del movimiento, extraída del detalle que adjunta el banco. Los cuatro campos vienen en 'null' cuando el movimiento no trae detalle, que es lo normal fuera de las transferencias. Son datos personales de terceros: trátalos como tales." }, "ultimaLecturaEn": { "type": "string", "description": "Instante (ISO 8601) en que esta fila se leyó del banco por última vez. Una corrección del banco entra como fila NUEVA en vez de reemplazar a la anterior, así que ante dos filas del mismo movimiento vale la de 'ultimaLecturaEn' mayor." } }, "required": [ "numeroCuenta", "periodo", "fechaMovimiento", "fechaContable", "descripcion", "monto", "type", "display", "saldoContable", "category", "mnemonico", "counterparty", "ultimaLecturaEn" ], "additionalProperties": false }, "description": "Los movimientos guardados, del más reciente al más antiguo. Una lista vacía significa que ese período todavía no se sincronizó, no que no haya movimientos." }, "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." }, "completo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Si el último sync de ESE período trajo todo. BCI corta en 1000 movimientos por cuenta y mes, así que 'false' significa que faltan filas del mes. 'null' significa «no se sabe», y es lo que devuelve una consulta sin filtro de 'periodo': nunca lo leas como un 'true'." } }, "required": [ "movimientos", "cursor", "completo" ], "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_pyme.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.