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).


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	`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 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.

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. 'counterparty' se deriva de los textos persistidos y 'counterpartySource' indica su procedencia. Los datos ambiguos o de formatos no soportados quedan en null; la cobertura depende de lo informado por el banco.

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

{
  "$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

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í
`movimientos[].monto`	número	null	sí
`movimientos[].type`	`"cargo"` · `"abono"`	null	sí
`movimientos[].display`	string	null	sí
`movimientos[].saldoContable`	número	null	sí
`movimientos[].descripcion`	string	sí	La glosa del movimiento tal como aparece en la cartola (por ejemplo 'PAGO PROVEEDOR').
`movimientos[].descripcionAmpliada`	string	null	sí
`movimientos[].observacion`	string	null	sí
`movimientos[].counterparty`	objeto	sí	Contraparte derivada al consultar los textos ya sincronizados, sin otro login ni migración de datos. Los campos ambiguos o de formatos no soportados quedan en null; 'descripcion' se conserva íntegra.
`movimientos[].counterparty.name`	string	null	sí
`movimientos[].counterparty.rut`	string	null	sí
`movimientos[].counterparty.bank`	string	null	sí
`movimientos[].counterparty.account`	string	null	sí
`movimientos[].counterpartySource`	`"descripcion"` · `"observacion"`	null	sí
`cursor`	string	null	sí

JSON Schema de salida

{
  "$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')."
          },
          "descripcionAmpliada": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El texto literal que Santander entrega en 'CodigoAmp', leído de la respuesta cifrada ya sincronizada (por ejemplo 'Depósito en efectivo'). Es independiente de 'descripcion' y 'observacion': no es una clasificación de Connect ni identifica automáticamente a la contraparte. null cuando no hay texto disponible. No expone la respuesta cruda del banco."
          },
          "observacion": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El texto complementario que Santander entrega en 'Observacion', separado de la glosa ('descripcion'). Puede contener detalles de la operación; no se identifica automáticamente como el comentario escrito por quien transfiere. 'null' cuando el banco no entrega texto o el movimiento histórico todavía no se ha enriquecido con este campo."
          },
          "counterparty": {
            "type": "object",
            "properties": {
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Nombre de la contraparte. Actualmente null: todavía no hay un formato respaldado para extraerlo."
              },
              "rut": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "RUT de la contraparte derivado del texto persistido, solo cuando un formato soportado permite atribuirlo sin ambigüedad y su dígito verificador es válido. Sin puntos, con guion y DV en mayúscula. null si no se puede derivar; no está disponible en todos los movimientos."
              },
              "bank": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Banco de la contraparte. Actualmente null: todavía no hay un formato respaldado para extraerlo."
              },
              "account": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Cuenta de la contraparte, como texto. Actualmente null: todavía no hay un formato respaldado para extraerla. No es 'numeroCuenta', que identifica la cuenta conectada."
              }
            },
            "required": [
              "name",
              "rut",
              "bank",
              "account"
            ],
            "additionalProperties": false,
            "description": "Contraparte derivada al consultar los textos ya sincronizados, sin otro login ni migración de datos. Los campos ambiguos o de formatos no soportados quedan en null; 'descripcion' se conserva íntegra."
          },
          "counterpartySource": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "descripcion",
                  "observacion"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Texto del banco del que se derivó la contraparte: 'descripcion' corresponde a la glosa y 'observacion' al texto complementario del movimiento. null significa que no se pudo derivar con los formatos soportados, no que el banco nunca informe contraparte. La respuesta cruda no se expone."
          }
        },
        "required": [
          "id",
          "numeroCuenta",
          "currency",
          "periodo",
          "fecha",
          "monto",
          "type",
          "display",
          "saldoContable",
          "descripcion",
          "descripcionAmpliada",
          "observacion",
          "counterparty",
          "counterpartySource"
        ],
        "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

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.

Próximos pasos

santander_empresas.conexion.sincronizar: la tool que escribe los datos que esta lectura devuelve.
Sincronizar y consultar: por qué leer datos reales son dos pasos.