# Consultar movimientos de BancoEstado > Lee los movimientos de BancoEstado YA sincronizados de esta conexión, del más reciente al más antiguo. {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **Tool ID** | `banco_estado.movimientos.consultar` | | **Nombre MCP** | `banco_estado__movimientos__consultar` | | **Conector** | `banco_estado` | | **Plano** | `action` | | **Lee el alcance** | `movimientos` (debe estar habilitado en la conexión) | | **Scope (permiso)** | `banco_estado:read` | | **Auth** | `none` | | **Versión** | `2` | | **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] Lectura pura: NO contacta al banco ni dispara una sincronización, así que si falta un período usa 'banco\_estado.conexion.sincronizar' primero. Refleja la cartola del banco: en los días que la última sincronización leyó completos, un movimiento que el banco ya no muestra deja de aparecer aquí (por ejemplo, un provisorio que el banco reemplazó en el cierre nocturno por su versión definitiva, a veces con otra glosa u otro documento) y reaparece si el banco lo vuelve a mostrar. Entre la medianoche y cerca de las 04:00 (hora de Chile) un movimiento del día puede no aparecer, igual que en el portal del banco. Cada movimiento trae 'estado': 'provisorio' si el banco todavía no lo contabiliza (puede cambiar o desaparecer en el cierre) o 'definitivo' si ya lo hizo, y se puede filtrar por él. Si guardas los movimientos en tu sistema, no te limites a agregar filas nuevas: vuelve a leer al menos el mes en curso y el anterior (con 'periodo') y reemplaza esos meses en tu copia. Los montos vienen como NÚMERO: 'monto' es la magnitud SIN signo, 'type' dice si sale ('credit') o entra ('debit') 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. 'saldo' es el saldo arrastrado: 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. ## Entrada [#entrada] | Campo | Tipo | Requerido | Descripción | | -------------- | ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `numeroCuenta` | string | no | Filtra por un número de cuenta. Omítelo para ver los movimientos de todas las cuentas de la conexión. | | `periodo` | string `^\d{4}-\d{2}$` | no | Filtra por el mes de la fecha del movimiento, en formato AAAA-MM (por ejemplo '2026-08'). Omítelo para traer todos los meses guardados. | | `estado` | `"provisorio"` · `"definitivo"` | no | Filtra por estado: 'definitivo' trae solo los movimientos que el banco ya contabilizó y 'provisorio' solo los del día que todavía puede reemplazar. Omítelo para traer los dos. | | `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": { "numeroCuenta": { "description": "Filtra por un número de cuenta. Omítelo para ver los movimientos de todas las cuentas de la conexión.", "type": "string" }, "periodo": { "description": "Filtra por el mes de la fecha del movimiento, en formato AAAA-MM (por ejemplo '2026-08'). Omítelo para traer todos los meses guardados.", "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "estado": { "description": "Filtra por estado: 'definitivo' trae solo los movimientos que el banco ya contabilizó y 'provisorio' solo los del día que todavía puede reemplazar. Omítelo para traer los dos.", "type": "string", "enum": [ "provisorio", "definitivo" ] }, "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_estado.movimientos.consultar/execute \ -H "Authorization: Bearer connect_sk_…" \ -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \ -H "Content-Type: application/json" \ -d '{"input":{"periodo":"2026-08"}}' ``` ```ts title="SDK TypeScript" const data = await connect.tools.banco_estado.movimientos.consultar({ periodo: "2026-08" }, { connectionId: "conn_9tKfR2mQx4Vb" }); ``` ```json title="MCP · meta-tool execute" { "tool": "banco_estado.movimientos.consultar", "params": { "periodo": "2026-08" }, "connectionId": "conn_9tKfR2mQx4Vb" } ``` **Salida esperada (200):** ```json { "data": { "movimientos": [ { "numeroCuenta": "12345678901", "periodo": "2026-08", "fecha": "2026-08-11", "descripcion": "PAGO PROVEEDOR", "documento": "1234567", "monto": 1700000, "type": "credit", "display": "-1.700.000", "saldo": 300000, "oficina": "STGO.PRINCIPAL", "origen": "linea", "estado": "definitivo", "syncedAt": "2026-08-11T17:32:04.000Z" } ], "cursor": null }, "meta": { "request_id": "req_…", "tool_id": "banco_estado.movimientos.consultar", "plane": "action", "latency_ms": 24, "audit_status": "recorded" } } ``` > 'type' es 'credit' porque la plata SALE: es la convención del libro del banco, al revés de como se lee una cartola. 'monto' no lleva el signo; 'display' sí. ## 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 a la que pertenece el movimiento. | | | `movimientos[].periodo` | string | null | sí | El mes (AAAA-MM) de la fecha del movimiento, no el período con que se pidió la sincronización: el banco no se limita al mes pedido. Es el campo por el que filtra 'periodo' en la entrada. No entra en la identidad del movimiento, así que sincronizar pidiendo otro período no lo duplica. | | `movimientos[].fecha` | string | null | sí | Fecha del movimiento, en formato AAAA-MM-DD, sin hora. null si el banco no trajo la celda. | | `movimientos[].descripcion` | string | null | sí | La glosa del movimiento tal como aparece en la cartola (por ejemplo 'PAGO PROVEEDOR'). | | `movimientos[].documento` | string | null | sí | El número de documento asociado al movimiento, cuando el banco lo trae. | | `movimientos[].monto` | número | null | sí | Magnitud del movimiento SIN signo. El sentido lo da 'type' y el signo visible lo trae 'display'. 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[].oficina` | string | null | sí | La oficina que el banco asocia al movimiento, en su propio texto (por ejemplo 'STGO.PRINCIPAL'). | | `movimientos[].origen` | `"linea"` · `"historica"` | sí | Por cuál de las dos cartolas del banco se trajo la fila: 'linea' es la cartola abierta, que el banco todavía no cierra, e 'historica' una cartola que el banco ya cerró. Las cartolas no van por mes: el banco cierra una cuando junta cierta cantidad de movimientos. Es metadato de procedencia y no entra en la identidad del movimiento, así que el mismo movimiento traído por las dos no se duplica. | | | `movimientos[].estado` | `"provisorio"` · `"definitivo"` | sí | Qué versión del movimiento muestra el banco. 'provisorio' = la del día, que el banco todavía no contabiliza: en el cierre nocturno la reemplaza por la definitiva, a veces con otra glosa u otro documento, o la saca. 'definitivo' = la contabilizada. En los dos casos el movimiento ocurrió. En chequera lo marca el banco; en cuenta corriente, que no trae marca, un movimiento sigue 'provisorio' mientras su fecha sea hoy o posterior (hora de Chile). La cartola histórica siempre es 'definitivo'. Se actualiza en cada sincronización. | | | `movimientos[].syncedAt` | string | null | 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. | | `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 a la que pertenece el movimiento." }, "periodo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El mes (AAAA-MM) de la fecha del movimiento, no el período con que se pidió la sincronización: el banco no se limita al mes pedido. Es el campo por el que filtra 'periodo' en la entrada. No entra en la identidad del movimiento, así que sincronizar pidiendo otro período no lo duplica." }, "fecha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Fecha del movimiento, en formato AAAA-MM-DD, sin hora. null si el banco no trajo la celda." }, "descripcion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "La glosa del movimiento tal como aparece en la cartola (por ejemplo 'PAGO PROVEEDOR')." }, "documento": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El número de documento asociado al movimiento, cuando el banco lo trae." }, "monto": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Magnitud del movimiento SIN signo. El sentido lo da 'type' y el signo visible lo trae 'display'. 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." }, "oficina": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "La oficina que el banco asocia al movimiento, en su propio texto (por ejemplo 'STGO.PRINCIPAL')." }, "origen": { "type": "string", "enum": [ "linea", "historica" ], "description": "Por cuál de las dos cartolas del banco se trajo la fila: 'linea' es la cartola abierta, que el banco todavía no cierra, e 'historica' una cartola que el banco ya cerró. Las cartolas no van por mes: el banco cierra una cuando junta cierta cantidad de movimientos. Es metadato de procedencia y no entra en la identidad del movimiento, así que el mismo movimiento traído por las dos no se duplica." }, "estado": { "type": "string", "enum": [ "provisorio", "definitivo" ], "description": "Qué versión del movimiento muestra el banco. 'provisorio' = la del día, que el banco todavía no contabiliza: en el cierre nocturno la reemplaza por la definitiva, a veces con otra glosa u otro documento, o la saca. 'definitivo' = la contabilizada. En los dos casos el movimiento ocurrió. En chequera lo marca el banco; en cuenta corriente, que no trae marca, un movimiento sigue 'provisorio' mientras su fecha sea hoy o posterior (hora de Chile). La cartola histórica siempre es 'definitivo'. Se actualiza en cada sincronización." }, "syncedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "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." } }, "required": [ "numeroCuenta", "periodo", "fecha", "descripcion", "documento", "monto", "type", "display", "saldo", "oficina", "origen", "estado", "syncedAt" ], "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_estado.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.