# Consultar saldos de Banco Itaú > Lee los saldos de Banco Itaú Empresas YA sincronizados de esta conexión, del más reciente al más antiguo. {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **Tool ID** | `itau_empresas.saldos.consultar` | | **Nombre MCP** | `itau_empresas__saldos__consultar` | | **Conector** | `itau_empresas` | | **Plano** | `action` | | **Lee el alcance** | `saldos` (debe estar habilitado en la conexión) | | **Scope (permiso)** | `itau_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, así que si nunca se sincronizó devuelve una lista vacía. Para traer datos nuevos usa 'itau\_empresas.conexion.sincronizar' primero. Los saldos son una foto POR DÍA y vienen como NÚMERO conservando su signo: un sobregiro es negativo, y un saldo no lleva 'type' porque no es una operación. Pagina con 'cursor': cuando la respuesta trae 'cursor' distinto de null hay más filas, reenvía ese valor tal cual y nunca lo construyas a mano. ## 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. |
JSON Schema de entrada ```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 } } } ```
## Ejemplo [#ejemplo] ```bash title="curl" curl -X POST https://connect.emisso.ai/api/v1/tools/itau_empresas.saldos.consultar/execute \ -H "Authorization: Bearer connect_sk_…" \ -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \ -H "Content-Type: application/json" \ -d '{"input":{}}' ``` ```ts title="SDK TypeScript" const data = await connect.tools.itau_empresas.saldos.consultar({}, { connectionId: "conn_9tKfR2mQx4Vb" }); ``` ```json title="MCP · meta-tool execute" { "tool": "itau_empresas.saldos.consultar", "params": {}, "connectionId": "conn_9tKfR2mQx4Vb" } ``` **Salida esperada (200):** ```json { "data": { "saldos": [ { "numeroCuenta": "0011223344", "currency": "CLP", "observedDay": "2026-09-23", "observedAt": "2026-09-23T14:02:11.000Z", "saldoTotal": 7518523, "retenciones": 0, "saldoDisponible": 7518523, "saldoDisponibleLineaCredito": 2000000, "syncedAt": "2026-09-23T14:02:11.000Z" } ], "cursor": null }, "meta": { "request_id": "req_…", "tool_id": "itau_empresas.saldos.consultar", "plane": "action", "latency_ms": 24, "audit_status": "recorded" } } ``` ## 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í | La moneda de la cuenta en código ISO ('CLP', 'USD'). El portal la publica como palabra ('Pesos') y Connect la normaliza antes de guardarla. Una etiqueta que el portal estrene y Connect no conozca llega como 'moneda\_\' en vez de asumirse pesos. | | | `saldos[].observedDay` | string | sí | El día de esta foto de saldo, en formato AAAA-MM-DD. Lo pone Connect al sincronizar, porque la ficha de Itaú no publica fecha. 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 tomó esta foto: el timestamp completo, no sólo el día. Para filtrar o comparar por día usa 'observedDay'. | | | `saldos[].saldoTotal` | número | null | sí | El saldo total 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 portal no trajo la celda, que no es lo mismo que cero. | | `saldos[].retenciones` | número | null | sí | Lo retenido según el portal. Un 0 afirma que no hay retención; un null dice que la celda no vino, que es un dato distinto. | | `saldos[].saldoDisponible` | número | null | sí | El saldo disponible de la cuenta. Es un balance: conserva su propio signo y no lleva 'type'. | | `saldos[].saldoDisponibleLineaCredito` | número | null | sí | El saldo disponible contando la línea de crédito. Un null significa que el portal no trajo la celda, no que la cuenta no tenga línea. | | `saldos[].syncedAt` | string | sí | Cuándo se leyó esta fila del banco (ISO 8601). Si está vieja, la sincronización puede haber dejado de correr (por ejemplo, con la conexión pausada tras varios fallos) mientras esta tool sigue respondiendo con filas antiguas. | | | `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. |
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 en código ISO ('CLP', 'USD'). El portal la publica como palabra ('Pesos') y Connect la normaliza antes de guardarla. Una etiqueta que el portal estrene y Connect no conozca llega como 'moneda_' en vez de asumirse pesos." }, "observedDay": { "type": "string", "description": "El día de esta foto de saldo, en formato AAAA-MM-DD. Lo pone Connect al sincronizar, porque la ficha de Itaú no publica fecha. 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 tomó esta foto: el timestamp completo, no sólo el día. Para filtrar o comparar por día usa 'observedDay'." }, "saldoTotal": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "El saldo total 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 portal no trajo la celda, que no es lo mismo que cero." }, "retenciones": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Lo retenido según el portal. Un 0 afirma que no hay retención; un null dice que la celda no vino, que es un dato distinto." }, "saldoDisponible": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "El saldo disponible de la cuenta. Es un balance: conserva su propio signo y no lleva 'type'." }, "saldoDisponibleLineaCredito": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "El saldo disponible contando la línea de crédito. Un null significa que el portal no trajo la celda, no que la cuenta no tenga línea." }, "syncedAt": { "type": "string", "description": "Cuándo se leyó esta fila del banco (ISO 8601). Si está vieja, la sincronización puede haber dejado de correr (por ejemplo, con la conexión pausada tras varios fallos) mientras esta tool sigue respondiendo con filas antiguas." } }, "required": [ "numeroCuenta", "currency", "observedDay", "observedAt", "saldoTotal", "retenciones", "saldoDisponible", "saldoDisponibleLineaCredito", "syncedAt" ], "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 } ```
## 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] * [`itau_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.