Consultar saldos Santander

Lee los saldos ya sincronizados de esta conexión, con el snapshot más reciente primero.


Tool ID	`santander_empresas.saldos.consultar`
Nombre MCP	`santander_empresas__saldos__consultar`
Conector	`santander_empresas`
Plano	`action`
Lee el alcance	`saldos` (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.

Qué hace

Lectura pura: NO contacta al banco ni dispara una sincronización. Si nunca se sincronizó, devuelve una lista vacía. Para traer datos nuevos, usa 'santander_empresas.conexion.sincronizar' primero.

Entrada

Campo	Tipo	Requerido	Descripción
`observedDay`	string	no	Filtra por el día del snapshot, en formato AAAA-MM-DD. Sin él, la primera página ya trae los saldos más recientes que hay guardados de cada cuenta.
`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

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "observedDay": {
      "description": "Filtra por el día del snapshot, en formato AAAA-MM-DD. Sin él, la primera página ya trae los saldos más recientes que hay guardados de cada cuenta.",
      "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"
    },
    "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
`saldos`	lista de objeto	sí	Los snapshots de saldo guardados, el más reciente primero. Una lista vacía significa que esta conexión todavía no se sincronizó, no que la empresa no tenga cuentas.
`saldos[].numeroCuenta`	string	sí	El número de la cuenta a la que corresponde esta foto de saldo.
`saldos[].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.
`saldos[].observedDay`	string	sí	El día de esta foto de saldo, en formato AAAA-MM-DD. Hay una foto por cuenta y por día: volver a sincronizar el mismo día actualiza esta fila en vez de agregar otra.
`saldos[].observedAt`	string	sí	El instante exacto (ISO 8601) en que se generó esta foto de saldo: el timestamp completo con el que se guardó la fila, no sólo el día. Para filtrar o comparar por día usa 'observedDay'.
`saldos[].saldoContable`	número	null	sí
`saldos[].saldoDisponible`	número	null	sí
`cursor`	string	null	sí

JSON Schema de salida

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "saldos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "numeroCuenta": {
            "type": "string",
            "description": "El número de la cuenta a la que corresponde esta foto de saldo."
          },
          "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."
          },
          "observedDay": {
            "type": "string",
            "description": "El día de esta foto de saldo, en formato AAAA-MM-DD. Hay una foto por cuenta y por día: volver a sincronizar el mismo día actualiza esta fila en vez de agregar otra."
          },
          "observedAt": {
            "type": "string",
            "description": "El instante exacto (ISO 8601) en que se generó esta foto de saldo: el timestamp completo con el que se guardó la fila, no sólo el día. Para filtrar o comparar por día usa 'observedDay'."
          },
          "saldoContable": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "El saldo contable de la cuenta. Es un balance, no una operación: conserva su propio signo (un sobregiro es negativo) y no lleva 'type'. Un null significa que el banco no trajo la celda, que no es lo mismo que cero."
          },
          "saldoDisponible": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "El saldo disponible de la cuenta. Es un balance: conserva su propio signo y no lleva 'type'. Un null significa que el banco no trajo la celda, que no es lo mismo que cero."
          }
        },
        "required": [
          "numeroCuenta",
          "currency",
          "observedDay",
          "observedAt",
          "saldoContable",
          "saldoDisponible"
        ],
        "additionalProperties": false
      },
      "description": "Los snapshots de saldo guardados, el más reciente primero. Una lista vacía significa que esta conexión todavía no se sincronizó, no que la empresa no tenga cuentas."
    },
    "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": [
    "saldos",
    "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.
`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.