Consultar saldos de BICE Empresas

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


Tool ID	`bice_empresas.saldos.consultar`
Nombre MCP	`bice_empresas__saldos__consultar`
Conector	`bice_empresas`
Plano	`action`
Lee el alcance	`saldos` (debe estar habilitado en la conexión)
Scope (permiso)	`bice_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, 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 'bice_empresas.conexion.sincronizar' primero. Los saldos son un snapshot POR DÍA, así que sin filtro de fecha la primera página ya son los saldos más recientes que hay guardados. Los dos saldos vienen como NÚMERO y conservan su signo: un sobregiro es negativo. Un saldo no lleva 'type' (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; nunca lo construyas a mano.

Entrada

Campo	Tipo	Requerido	Descripción
`observedDay`	string `^\d{4}-\d{2}-\d{2}$`	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",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "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
    }
  }
}

Ejemplo

curl

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

SDK TypeScript

const data = await connect.tools.bice_empresas.saldos.consultar({}, { connectionId: "conn_9tKfR2mQx4Vb" });

MCP · meta-tool execute

{
  "tool": "bice_empresas.saldos.consultar",
  "params": {},
  "connectionId": "conn_9tKfR2mQx4Vb"
}

Salida esperada (200):

{
  "data": {
    "saldos": [
      {
        "numeroCuenta": "07203344",
        "numProducto": "07203344",
        "currency": "CLP",
        "observedDay": "2026-08-07",
        "observedAt": "2026-08-07T13:05:12.000Z",
        "saldoContable": 5214890,
        "saldoDisponible": 5158210
      }
    ],
    "cursor": null
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "bice_empresas.saldos.consultar",
    "plane": "action",
    "latency_ms": 24,
    "audit_status": "recorded"
  }
}

'numeroCuenta' y 'numProducto' traen el mismo valor a propósito: ambos guardan el identificador estable de la cuenta (nunca la máscara de sesión del portal).

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 identificador ESTABLE de la cuenta a la que pertenece esta fila. No es la máscara que muestra el portal en pantalla, que cambia en cada sesión: es el mismo valor en saldos y movimientos, y el que espera el filtro 'numeroCuenta'.
`saldos[].numProducto`	string	sí	El mismo identificador estable de la cuenta que 'numeroCuenta'. Los dos campos traen el mismo valor a propósito: es el nombre con el que el propio BICE lo pide en sus llamadas.
`saldos[].currency`	string	sí	La moneda de la cuenta, en código de tres letras (por ejemplo 'CLP'). BICE la manda a veces como código numérico y aquí ya viene traducida a las tres letras.
`saldos[].observedDay`	string	sí	El día (AAAA-MM-DD) de esta foto de saldos. Los saldos se guardan como un snapshot por día, así que sin filtro de fecha la primera página ya trae el más reciente de cada cuenta.
`saldos[].observedAt`	string	sí	El instante exacto (ISO 8601) en que se tomó la foto, dentro del día de '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 identificador ESTABLE de la cuenta a la que pertenece esta fila. No es la máscara que muestra el portal en pantalla, que cambia en cada sesión: es el mismo valor en saldos y movimientos, y el que espera el filtro 'numeroCuenta'."
          },
          "numProducto": {
            "type": "string",
            "description": "El mismo identificador estable de la cuenta que 'numeroCuenta'. Los dos campos traen el mismo valor a propósito: es el nombre con el que el propio BICE lo pide en sus llamadas."
          },
          "currency": {
            "type": "string",
            "description": "La moneda de la cuenta, en código de tres letras (por ejemplo 'CLP'). BICE la manda a veces como código numérico y aquí ya viene traducida a las tres letras."
          },
          "observedDay": {
            "type": "string",
            "description": "El día (AAAA-MM-DD) de esta foto de saldos. Los saldos se guardan como un snapshot por día, así que sin filtro de fecha la primera página ya trae el más reciente de cada cuenta."
          },
          "observedAt": {
            "type": "string",
            "description": "El instante exacto (ISO 8601) en que se tomó la foto, dentro del día de 'observedDay'."
          },
          "saldoContable": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "El saldo contable de la cuenta, como número y con su propio signo (un sobregiro es negativo). 'null' significa que el banco no trajo la celda, nunca 0: un 0 es un saldo real."
          },
          "saldoDisponible": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "El saldo disponible de la cuenta, con el mismo criterio de signo y de 'null' que 'saldoContable'."
          }
        },
        "required": [
          "numeroCuenta",
          "numProducto",
          "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

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