# Consultar movimientos de Banco Security > Lee la caché ya sincronizada; NO contacta al banco. {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **Tool ID** | `banco_security.movimientos.consultar` | | **Nombre MCP** | `banco_security__movimientos__consultar` | | **Conector** | `banco_security` | | **Plano** | `action` | | **Lee el alcance** | `movimientos` (debe estar habilitado en la conexión) | | **Scope (permiso)** | `banco_security: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 de cuenta corriente guardados de esta conexión, del más reciente al más antiguo, filtrables por período (AAAA-MM). Exige el alcance 'movimientos' habilitado. Sin 'periodo' devuelve todos los períodos sincronizados. Si el período nunca se sincronizó, devuelve una lista vacía (lo que NO significa que no haya movimientos): usa 'banco\_security.conexion.sincronizar' primero. El banco sirve el mes en curso y los meses ya cerrados por dos cartolas distintas, pero eso es interno: las dos escriben esta misma caché con la misma identidad por movimiento, así que un mes de solape NO aparece duplicado y los resultados se pueden sumar sin miedo. 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. Un saldo NO lleva 'type': es un balance 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 | Un mes, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Cada sitio de uso afina qué significa ahí: en una sincronización es el mes que se va a traer, y en una consulta a la caché es el filtro. Esta descripción base existe para que el campo nunca llegue pelado a quien lee el contrato. | | `cursor` | string | no | Puntero opaco a la página siguiente. Reenvía tal cual el 'cursor' que devolvió la llamada anterior; nunca lo construyas a mano. Omítelo para pedir la primera página. | | `limit` | entero 1-500 | no · default `100` | Cuántas filas trae la página, entre 1 y 500. Por omisión, 100. |
JSON Schema de entrada ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "periodo": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Un mes, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Cada sitio de uso afina qué significa ahí: en una sincronización es el mes que se va a traer, y en una consulta a la caché es el filtro. Esta descripción base existe para que el campo nunca llegue pelado a quien lee el contrato." }, "cursor": { "description": "Puntero opaco a la página siguiente. Reenvía tal cual el 'cursor' que devolvió la llamada anterior; nunca lo construyas a mano. Omítelo para pedir la primera página.", "type": "string" }, "limit": { "default": 100, "description": "Cuántas filas trae la página, entre 1 y 500. Por omisión, 100.", "type": "integer", "minimum": 1, "maximum": 500 } } } ```
## Ejemplo [#ejemplo] ```bash title="curl" curl -X POST https://connect.emisso.ai/api/v1/tools/banco_security.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.banco_security.movimientos.consultar({ periodo: "2026-07" }, { connectionId: "conn_9tKfR2mQx4Vb" }); ``` ```json title="MCP · meta-tool execute" { "tool": "banco_security.movimientos.consultar", "params": { "periodo": "2026-07" }, "connectionId": "conn_9tKfR2mQx4Vb" } ``` **Salida esperada (200):** ```json { "data": { "movimientos": [ { "numeroCuenta": "915042876", "currency": "CLP", "periodo": "2026-07", "fechaMovimiento": "2026-07-28T00:00:00.000Z", "monto": 2380000, "type": "credit", "display": "-2.380.000", "saldo": 12456789, "descripcion": "TEF A DISTRIBUIDORA LOS ANDES LTDA", "documento": "9081234", "ultimaLecturaEn": "2026-08-07T07:15:42.000Z" }, { "numeroCuenta": "915042876", "currency": "CLP", "periodo": "2026-07", "fechaMovimiento": "2026-07-21T00:00:00.000Z", "monto": 5490000, "type": "debit", "display": "5.490.000", "saldo": 14836789, "descripcion": "DEPOSITO TRANSFERENCIA DE FONDOS", "documento": null, "ultimaLecturaEn": "2026-08-07T07:15:42.000Z" } ], "cursor": null }, "meta": { "request_id": "req_…", "tool_id": "banco_security.movimientos.consultar", "plane": "action", "latency_ms": 24, "audit_status": "recorded" } } ``` > El cargo del 28 de julio sale como 'credit' con 'display' negativo y el abono del 21 como 'debit' positivo (libro del banco); 'saldo' conserva su propio signo. ## Salida [#salida] | Campo | Tipo | Requerido | Descripción | | | ------------------------------- | ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `movimientos` | lista de objeto | sí | Los movimientos guardados que calzan con los filtros, del más reciente al más antiguo. Una lista vacía significa que ese período no se ha sincronizado, no que no haya movimientos. | | | `movimientos[].numeroCuenta` | string | sí | El número de la cuenta corriente a la que pertenece el movimiento. | | | `movimientos[].periodo` | string | sí | El mes (AAAA-MM) con el que se sincronizó esta fila. Es cómo se pidió el dato, no una propiedad del objeto: no entra en su identidad, así que volver a traerlo bajo otro período no crea una fila nueva. | | | `movimientos[].fechaMovimiento` | string | null | sí | Fecha del movimiento en la cartola (ISO 8601). null si el banco no la trajo. | | `movimientos[].monto` | número | null | sí | Magnitud del movimiento SIN signo. El sentido lo da 'type' y el signo visible lo trae 'display'. Reemplaza al par cargo/abono del portal, que obligaba a mirar cuál de las dos celdas venía llena. Un null significa que el banco no trajo la celda, que no es lo mismo que cero. | | `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[].saldo` | número | null | sí | El saldo que queda en la cuenta después de este movimiento. Es un balance: no lleva 'type' y conserva su propio signo. | | `movimientos[].descripcion` | string | null | sí | La glosa del movimiento tal como aparece en la cartola (por ejemplo 'TEF A PROVEEDOR LTDA'). | | `movimientos[].documento` | string | null | sí | El número de documento asociado al movimiento, cuando el banco lo trae. | | `movimientos[].ultimaLecturaEn` | string | sí | Cuándo se leyó esta fila del banco (ISO 8601). Si está vieja, la caché puede haber dejado de moverse (por ejemplo, con la conexión pausada tras varios fallos de credencial) mientras esta tool sigue respondiendo con filas antiguas. Entre dos filas del mismo hecho, gana la de 'ultimaLecturaEn' mayor. | | | `movimientos[].currency` | string | sí | Moneda de la cuenta, en código ISO. Se deriva de la cuenta, así que viene igual por las dos cartolas del banco y nunca es null. | | | `cursor` | string | null | sí | Puntero a la página siguiente. Si viene distinto de null hay más filas: vuelve a llamar reenviándolo tal cual en 'cursor'. Un null significa que no queda nada por traer. |
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 corriente a la que pertenece el movimiento." }, "periodo": { "type": "string", "description": "El mes (AAAA-MM) con el que se sincronizó esta fila. Es cómo se pidió el dato, no una propiedad del objeto: no entra en su identidad, así que volver a traerlo bajo otro período no crea una fila nueva." }, "fechaMovimiento": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Fecha del movimiento en la cartola (ISO 8601). null si el banco no la trajo." }, "monto": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Magnitud del movimiento SIN signo. El sentido lo da 'type' y el signo visible lo trae 'display'. Reemplaza al par cargo/abono del portal, que obligaba a mirar cuál de las dos celdas venía llena. Un null significa que el banco no trajo la celda, que no es lo mismo que cero." }, "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'." }, "saldo": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "El saldo que queda en la cuenta después de este movimiento. Es un balance: no lleva 'type' y conserva su propio signo." }, "descripcion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "La glosa del movimiento tal como aparece en la cartola (por ejemplo 'TEF A PROVEEDOR LTDA')." }, "documento": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El número de documento asociado al movimiento, cuando el banco lo trae." }, "ultimaLecturaEn": { "type": "string", "description": "Cuándo se leyó esta fila del banco (ISO 8601). Si está vieja, la caché puede haber dejado de moverse (por ejemplo, con la conexión pausada tras varios fallos de credencial) mientras esta tool sigue respondiendo con filas antiguas. Entre dos filas del mismo hecho, gana la de 'ultimaLecturaEn' mayor." }, "currency": { "type": "string", "description": "Moneda de la cuenta, en código ISO. Se deriva de la cuenta, así que viene igual por las dos cartolas del banco y nunca es null." } }, "required": [ "numeroCuenta", "periodo", "fechaMovimiento", "monto", "type", "display", "saldo", "descripcion", "documento", "ultimaLecturaEn", "currency" ], "additionalProperties": false }, "description": "Los movimientos guardados que calzan con los filtros, del más reciente al más antiguo. Una lista vacía significa que ese período no se ha sincronizado, no que no haya movimientos." }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Puntero a la página siguiente. Si viene distinto de null hay más filas: vuelve a llamar reenviándolo tal cual en 'cursor'. Un null significa que no queda nada por traer." } }, "required": [ "movimientos", "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. | | `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] * [`banco_security.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.