# Consultar movimientos Santander > Lee los movimientos ya sincronizados de esta conexión, del más reciente al más antiguo, filtrables por período (AAAA-MM), por cuenta y por 'type' (el eje cargo/abono del libro del banco). {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **Tool ID** | `santander_empresas.movimientos.consultar` | | **Nombre MCP** | `santander_empresas__movimientos__consultar` | | **Conector** | `santander_empresas` | | **Plano** | `action` | | **Lee el alcance** | `movimientos` (debe estar habilitado en la conexión) | | **Scope (permiso)** | `santander_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, 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. Si el período nunca se sincronizó, devuelve una lista vacía, que NO significa que no haya movimientos. Para traer datos nuevos, usa 'santander\_empresas.conexion.sincronizar' primero. ## Entrada [#entrada] | Campo | Tipo | Requerido | Descripción | | -------------- | ------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `periodo` | string | no | Filtra por el mes (AAAA-MM) con el que se sincronizó la fila. Sin él, la respuesta cruza todos los períodos guardados. | | `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. | | `type` | string | no | Filtra por el eje del monto, en la forma persistida ('cargo'/'abono'). | | `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.", "type": "string" }, "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" }, "type": { "description": "Filtra por el eje del monto, en la forma persistida ('cargo'/'abono').", "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 } } } ```
## 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[].id` | string | sí | El identificador ESTABLE de este movimiento: la clave natural con la que Connect lo guardó (no un número de operación del banco). Es el mismo valor entre sincronizaciones repetidas: úsalo para deduplicar en tu propio sistema. | | | `movimientos[].numeroCuenta` | string | sí | El número de la cuenta a la que pertenece el movimiento. | | | `movimientos[].currency` | string | sí | La moneda de la cuenta ('CLP', 'USD', ...). A diferencia de otros bancos de Connect, Santander siempre la declara: nunca viene vacía ni ausente. | | | `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 movimiento: no entra en su identidad, así que volver a traerlo bajo otro período no crea una fila nueva ni infla los totales. | | | `movimientos[].fecha` | string | null | sí | Fecha y hora del movimiento (ISO 8601). null si el banco no trajo la celda. | | `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` | `"cargo"` · `"abono"` | null | sí | Eje cargo/abono, en la MISMA palabra con la que Santander lo persiste, a diferencia de otros bancos de Connect, este campo no está invertido: 'cargo' es plata que SALE de la cuenta y 'abono' es plata que ENTRA. El campo 'monto' es la magnitud SIN signo; el signo lo lleva 'display'. 'null' significa que Santander 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' ('cargo', 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 que queda en la cuenta después de este movimiento. Es un balance: no lleva 'type' y conserva su propio signo. | | `movimientos[].descripcion` | string | sí | La glosa del movimiento tal como aparece en la cartola (por ejemplo 'PAGO PROVEEDOR'). | | | `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. |
JSON Schema de salida ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "movimientos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "El identificador ESTABLE de este movimiento: la clave natural con la que Connect lo guardó (no un número de operación del banco). Es el mismo valor entre sincronizaciones repetidas: úsalo para deduplicar en tu propio sistema." }, "numeroCuenta": { "type": "string", "description": "El número de la cuenta a la que pertenece el movimiento." }, "currency": { "type": "string", "description": "La moneda de la cuenta ('CLP', 'USD', ...). A diferencia de otros bancos de Connect, Santander siempre la declara: nunca viene vacía ni ausente." }, "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 movimiento: no entra en su identidad, así que volver a traerlo bajo otro período no crea una fila nueva ni infla los totales." }, "fecha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Fecha y hora del movimiento (ISO 8601). null si el banco no trajo la celda." }, "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": [ "cargo", "abono" ] }, { "type": "null" } ], "description": "Eje cargo/abono, en la MISMA palabra con la que Santander lo persiste, a diferencia de otros bancos de Connect, este campo no está invertido: 'cargo' es plata que SALE de la cuenta y 'abono' es plata que ENTRA. El campo 'monto' es la magnitud SIN signo; el signo lo lleva 'display'. 'null' significa que Santander 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' ('cargo', 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 que queda en la cuenta después de este movimiento. Es un balance: no lleva 'type' y conserva su propio signo." }, "descripcion": { "type": "string", "description": "La glosa del movimiento tal como aparece en la cartola (por ejemplo 'PAGO PROVEEDOR')." } }, "required": [ "id", "numeroCuenta", "currency", "periodo", "fecha", "monto", "type", "display", "saldoContable", "descripcion" ], "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." } }, "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] * [`santander_empresas.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.