# Consultar saldos Santander
> Lee los saldos ya sincronizados de esta conexión, con el snapshot más reciente primero.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **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`](../conexiones/estado-consultar).
## Qué hace [#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 [#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
```json
{
"$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 [#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í | 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. |
| `saldos[].saldoDisponible` | número | null | sí | 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. |
| `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": {
"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 [#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.