# Consultar saldos de Banco Security

> Antes de pedir datos nuevos, consulta atenciones en conexiones.estado.consultar.



{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}

|                     |                                                                    |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID**         | `banco_security.saldos.consultar`                                  |
| **Nombre MCP**      | `banco_security__saldos__consultar`                                |
| **Conector**        | `banco_security`                                                   |
| **Plano**           | `action`                                                           |
| **Lee el alcance**  | `saldos` (debe estar habilitado en la conexión)                    |
| **Scope (permiso)** | `banco_security: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`](/docs/referencia/conexiones/estado-consultar).

## Qué hace [#qué-hace]

Si sincronizarSirve es false, sigue hacer: las indicaciones para pedir datos nuevos que siguen no aplican hasta resolver esa atención. La consulta de datos ya guardados sigue disponible según el plan. Devuelve los saldos guardados de esta conexión (contable, disponible y provisorio), desde la caché ya sincronizada y sin contactar al banco, con el snapshot más reciente primero. Exige el alcance 'saldos' habilitado. Si nunca se sincronizó, devuelve una lista vacía (eso NO significa que la empresa no tenga cuentas); usa 'banco\_security.conexion.sincronizar' primero. Los saldos son un snapshot POR DÍA, así que sin filtro de fecha la primera página ya son los más recientes que hay guardados. Los tres saldos vienen como NÚMERO ya normalizado (antes eran la celda cruda del banco, '$ 12.345.678'), y conservan su signo: un sobregiro es negativo. Un saldo no lleva 'type': no es una operación. 'ultimaLecturaEn' dice cuándo se leyó esa fila del banco: si es vieja, la conexión puede estar pausada. Pagina con 'cursor': cuando la respuesta trae 'cursor' distinto de null hay más filas. reenvía ese valor tal cual; nunca lo construyas a mano. Trae una fila por cuenta, moneda y día, y cada fila indica su número de cuenta y su moneda. El orden es siempre el mismo: del día más reciente al más antiguo y, dentro de cada día, por número de cuenta y luego por moneda. Para obtener el saldo más reciente de una cuenta, filtra por 'numeroCuenta' y toma la primera fila de la moneda que buscas. Sin ese filtro, la primera fila es la cuenta de menor número, que puede no ser la que necesitas.

## Entrada [#entrada]

| Campo          | Tipo                         | Requerido          | Descripción                                                                                                                                                           |
| -------------- | ---------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `observedDay`  | string `^\d{4}-\d{2}-\d{2}$` | no                 | Filtra por el día de la foto de saldo, en formato AAAA-MM-DD. Si lo omites, la primera página ya trae las fotos más recientes que haya guardadas.                     |
| `numeroCuenta` | string                       | no                 | Filtra por un número de cuenta. Omítelo para ver todas las cuentas de la conexión.                                                                                    |
| `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.                                                                                                        |

<details>
  <summary>
    JSON Schema de entrada
  </summary>

  ```json
  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "observedDay": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
        "x-emisso-formato": "AAAA-MM-DD",
        "description": "Filtra por el día de la foto de saldo, en formato AAAA-MM-DD. Si lo omites, la primera página ya trae las fotos más recientes que haya guardadas."
      },
      "numeroCuenta": {
        "description": "Filtra por un número de cuenta. Omítelo para ver todas las cuentas de la conexión.",
        "type": "string"
      },
      "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
      }
    }
  }
  ```
</details>

## Ejemplo [#ejemplo]

```bash title="curl"
curl -X POST https://connect.emisso.ai/api/v1/tools/banco_security.saldos.consultar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{}}'
```

```json title="MCP · meta-tool execute"
{
  "tool": "banco_security.saldos.consultar",
  "params": {},
  "connectionId": "conn_9tKfR2mQx4Vb"
}
```

**Salida esperada (200):**

```json
{
  "data": {
    "saldos": [
      {
        "numeroCuenta": "915042876",
        "currency": "CLP",
        "observedDay": "2026-08-07",
        "observedAt": "2026-08-07T07:15:38.000Z",
        "saldoContable": 12845301,
        "saldoDisponible": 12610301,
        "saldoProvisorio": 235000,
        "ultimaLecturaEn": "2026-08-07T07:15:42.000Z"
      },
      {
        "numeroCuenta": "915042884",
        "currency": "USD",
        "observedDay": "2026-08-07",
        "observedAt": "2026-08-07T07:15:38.000Z",
        "saldoContable": 15230.5,
        "saldoDisponible": 15230.5,
        "saldoProvisorio": 0,
        "ultimaLecturaEn": "2026-08-07T07:15:42.000Z"
      }
    ],
    "cursor": null
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "banco_security.saldos.consultar",
    "plane": "action",
    "latency_ms": 24,
    "audit_status": "recorded"
  }
}
```

> Sin filtros, la primera página trae el snapshot más reciente de cada cuenta; la misma empresa puede tener cuentas en pesos y en dólares.

## Salida [#salida]

| Campo                      | Tipo            | Requerido | Descripción                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                        |
| -------------------------- | --------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `saldos`                   | lista de objeto | sí        | Las fotos de saldo guardadas que calzan con los filtros, de la más reciente a la más antigua. Una lista vacía significa que la conexión nunca sincronizó saldos, 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í        | Moneda de la cuenta, en código ISO ('CLP' o 'USD'). La misma empresa puede tener cuentas en pesos y en dólares, y cada una trae su propia fila.                                                                                                                                                             |                                                                                                                                                                                                                        |
| `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 (ISO 8601) en que se tomó la foto dentro de ese día.                                                                                                                                                                                                                                            |                                                                                                                                                                                                                        |
| `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.                                            |
| `saldos[].saldoProvisorio` | número          | null      | sí                                                                                                                                                                                                                                                                                                          | El saldo provisorio de la cuenta, tal como lo publica el portal. Es un balance: conserva su propio signo y no lleva 'type'. Un null significa que el banco no trajo la celda.                                          |
| `saldos[].ultimaLecturaEn` | string          | 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. Entre dos filas del mismo hecho, gana la de 'ultimaLecturaEn' mayor. |                                                                                                                                                                                                                        |
| `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.                                              |

<details>
  <summary>
    JSON Schema de salida
  </summary>

  ```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": "Moneda de la cuenta, en código ISO ('CLP' o 'USD'). La misma empresa puede tener cuentas en pesos y en dólares, y cada una trae su propia fila."
            },
            "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 (ISO 8601) en que se tomó la foto dentro de ese día."
            },
            "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."
            },
            "saldoProvisorio": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "description": "El saldo provisorio de la cuenta, tal como lo publica el portal. Es un balance: conserva su propio signo y no lleva 'type'. Un null significa que el banco no trajo la celda."
            },
            "ultimaLecturaEn": {
              "type": "string",
              "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. Entre dos filas del mismo hecho, gana la de 'ultimaLecturaEn' mayor."
            }
          },
          "required": [
            "numeroCuenta",
            "currency",
            "observedDay",
            "observedAt",
            "saldoContable",
            "saldoDisponible",
            "saldoProvisorio",
            "ultimaLecturaEn"
          ],
          "additionalProperties": false
        },
        "description": "Las fotos de saldo guardadas que calzan con los filtros, de la más reciente a la más antigua. Una lista vacía significa que la conexión nunca sincronizó saldos, no que la empresa no tenga cuentas."
      },
      "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": [
      "saldos",
      "cursor"
    ],
    "additionalProperties": false
  }
  ```
</details>

## 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.                                                   |
| `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](/docs/referencia/errores).

## Próximos pasos [#próximos-pasos]

* [`banco_security.conexion.sincronizar`](/docs/referencia/banco_security/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.


---

Esta página es parte de la documentación de Emisso. El índice completo, con cada página y su descripción, está en https://connect.emisso.ai/llms.txt. Esta misma página en HTML: https://connect.emisso.ai/docs/referencia/banco_security/saldos-consultar.
