# Cuentas y saldos > Antes de pedir datos nuevos, consulta atenciones en conexiones.estado.consultar. {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **Tool ID** | `bbva_peru_beta.saldos.consultar` | | **Nombre MCP** | `bbva_peru_beta__saldos__consultar` | | **Conector** | `bbva_peru_beta` | | **Plano** | `action` | | **Lee el alcance** | `saldos` (debe estar habilitado en la conexión) | | **Scope (permiso)** | `bbva_peru_beta: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 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. Lee saldos guardados por moneda. Incluye las cuentas conservadas por la última sincronización de esta conexión. No ingresa al banco. Un snapshot completo describe lo observado en ese instante; no garantiza el saldo actual. Sin sincronización devuelve cuentas vacías y metadatos null, que no significan cero cuentas. ## Entrada [#entrada] | Campo | Tipo | Requerido | Descripción | | ----------- | ------------ | ------------------ | -------------------------------------------------------------------------------------------------------------- | | `accountId` | string | no | Filtra la lectura persistida por el accountId de una cuenta. No limita las cuentas que sincroniza la conexión. | | `cursor` | string | no | Cursor devuelto por la página anterior, sin construirlo ni modificarlo. | | `limite` | entero 1-200 | no · default `100` | Cantidad máxima de cuentas de la página: entre 1 y 200, por defecto 100. |
JSON Schema de entrada ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accountId": { "description": "Filtra la lectura persistida por el accountId de una cuenta. No limita las cuentas que sincroniza la conexión.", "type": "string" }, "cursor": { "description": "Cursor devuelto por la página anterior, sin construirlo ni modificarlo.", "type": "string", "minLength": 1, "maxLength": 2048 }, "limite": { "default": 100, "description": "Cantidad máxima de cuentas de la página: entre 1 y 200, por defecto 100.", "type": "integer", "minimum": 1, "maximum": 200 } } } ```
## Ejemplo [#ejemplo] ```bash title="curl" curl -X POST https://connect.emisso.ai/api/v1/tools/bbva_peru_beta.saldos.consultar/execute \ -H "Authorization: Bearer connect_sk_…" \ -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \ -H "Content-Type: application/json" \ -d '{"input":{"limite":100}}' ``` ```json title="MCP · meta-tool execute" { "tool": "bbva_peru_beta.saldos.consultar", "params": { "limite": 100 }, "connectionId": "conn_9tKfR2mQx4Vb" } ``` **Salida esperada (200):** ```json { "data": { "cuentas": [], "cursor": null, "completo": null, "sincronizadoEn": null }, "meta": { "request_id": "req_…", "tool_id": "bbva_peru_beta.saldos.consultar", "plane": "action", "latency_ms": 24, "audit_status": "recorded" } } ``` ## Salida [#salida] | Campo | Tipo | Requerido | Descripción | | | | | | | | | | | | | | | | | | | ---------------------------------- | --------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | --------------------- | ------------------ | ------- | ------- | ---------- | -------------- | ------- | --- | ----------------- | --- | ------------------------ | ------------------------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `cuentas` | lista de objeto | sí | Cuentas de esta página del snapshot persistido. Una lista vacía con completo null indica que aún no existe una lectura conservada. | | | | | | | | | | | | | | | | | | | `cuentas[].accountId` | string | sí | Identificador opaco textual de la cuenta; se conserva sin conversión numérica. | | | | | | | | | | | | | | | | | | | `cuentas[].numeroCuenta` | string | null | sí | Número de cuenta tal como fue conservado; null si el banco no lo informó. | | | | | | | | | | | | | | | | | | `cuentas[].monedasDeclaradas` | lista de string `^[A-Z]{3}$` | null | sí | Monedas declaradas para la cuenta; null cuando el banco no entregó esa lista. | | | | | | | | | | | | | | | | | | `cuentas[].saldos` | lista de objeto | sí | Saldos interpretados por moneda de esta cuenta. Conserva cada moneda por separado, sin sumar ni convertir importes. | | | | | | | | | | | | | | | | | | | `cuentas[].saldos[].moneda` | string `^[A-Z]{3}$` | sí | Código de moneda informado por el banco, sin equivalencias ni conversión. | | | | | | | | | | | | | | | | | | | `cuentas[].saldos[].saldoActual` | string \`^-?(?:0 | \[1-9]\[0-9]*)(?:.\[0-9]*\[1-9])?$\` | null | sí | Importe decimal exacto como texto, con su signo. null indica ausencia de ese saldo; no equivale a cero. | | | | | | | | | | | | | | | | | `cuentas[].saldos[].saldoContable` | string \`^-?(?:0 | \[1-9]\[0-9]*)(?:.\[0-9]*\[1-9])?$\` | null | sí | Importe decimal exacto como texto, con su signo. null indica ausencia de ese saldo; no equivale a cero. | | | | | | | | | | | | | | | | | `cuentas[].otrasClasesDeSaldo` | booleano | sí | El banco informó otras clases de saldo que no están interpretadas en esta lectura. | | | | | | | | | | | | | | | | | | | `cuentas[].observadoEn` | string \`^(?:(?:\d\d\[2468]\[048] | \d\d\[13579]\[26] | \d\d0\[48] | \[02468]\[048]00 | \[13579]\[26]00)-02-29 | \d{4}-(?:(?:0\[13578] | 1\[02])-(?:0\[1-9] | \[12]\d | 3\[01]) | (?:0\[469] | 11)-(?:0\[1-9] | \[12]\d | 30) | (?:02)-(?:0\[1-9] | 1\d | 2\[0-8])))T(?:(?:\[01]\d | 2\[0-3]):\[0-5]\d(?::\[0-5]\d(?:.\d+)?)?(?:Z))$\` | sí | Instante ISO 8601 UTC en que se observó este snapshot. No es una afirmación de saldo vigente al consultar. | | | `cursor` | string | null | sí | Cursor opaco de la próxima página persistida; null cuando no quedan cuentas en esta consulta. | | | | | | | | | | | | | | | | | | `completo` | booleano | null | sí | Cobertura del snapshot conservado; no acredita frescura actual ni cambia al filtrar una cuenta. null si no hay snapshot. | | | | | | | | | | | | | | | | | | `sincronizadoEn` | string \`^(?:(?:\d\d\[2468]\[048] | \d\d\[13579]\[26] | \d\d0\[48] | \[02468]\[048]00 | \[13579]\[26]00)-02-29 | \d{4}-(?:(?:0\[13578] | 1\[02])-(?:0\[1-9] | \[12]\d | 3\[01]) | (?:0\[469] | 11)-(?:0\[1-9] | \[12]\d | 30) | (?:02)-(?:0\[1-9] | 1\d | 2\[0-8])))T(?:(?:\[01]\d | 2\[0-3]):\[0-5]\d(?::\[0-5]\d(?:.\d+)?)?(?:Z))$\` | null | sí | Instante ISO 8601 UTC de la última lectura conservada, o null si aún no existe. |
JSON Schema de salida ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cuentas": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Identificador opaco textual de la cuenta; se conserva sin conversión numérica." }, "numeroCuenta": { "anyOf": [ { "type": "string", "description": "Identificador opaco textual de la cuenta; se conserva sin conversión numérica." }, { "type": "null" } ], "description": "Número de cuenta tal como fue conservado; null si el banco no lo informó." }, "monedasDeclaradas": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Código de moneda informado por el banco, sin equivalencias ni conversión." } }, { "type": "null" } ], "description": "Monedas declaradas para la cuenta; null cuando el banco no entregó esa lista." }, "saldos": { "type": "array", "items": { "type": "object", "properties": { "moneda": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Código de moneda informado por el banco, sin equivalencias ni conversión." }, "saldoActual": { "anyOf": [ { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]*[1-9])?$" }, { "type": "null" } ], "description": "Importe decimal exacto como texto, con su signo. null indica ausencia de ese saldo; no equivale a cero." }, "saldoContable": { "anyOf": [ { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]*[1-9])?$" }, { "type": "null" } ], "description": "Importe decimal exacto como texto, con su signo. null indica ausencia de ese saldo; no equivale a cero." } }, "required": [ "moneda", "saldoActual", "saldoContable" ], "additionalProperties": false }, "description": "Saldos interpretados por moneda de esta cuenta. Conserva cada moneda por separado, sin sumar ni convertir importes." }, "otrasClasesDeSaldo": { "type": "boolean", "description": "El banco informó otras clases de saldo que no están interpretadas en esta lectura." }, "observadoEn": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Instante ISO 8601 UTC en que se observó este snapshot. No es una afirmación de saldo vigente al consultar." } }, "required": [ "accountId", "numeroCuenta", "monedasDeclaradas", "saldos", "otrasClasesDeSaldo", "observadoEn" ], "additionalProperties": false }, "description": "Cuentas de esta página del snapshot persistido. Una lista vacía con completo null indica que aún no existe una lectura conservada." }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor opaco de la próxima página persistida; null cuando no quedan cuentas en esta consulta." }, "completo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Cobertura del snapshot conservado; no acredita frescura actual ni cambia al filtrar una cuenta. null si no hay snapshot." }, "sincronizadoEn": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Instante ISO 8601 UTC de la última lectura conservada, o null si aún no existe." } }, "required": [ "cuentas", "cursor", "completo", "sincronizadoEn" ], "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. | | `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] * [`bbva_peru_beta.conexion.sincronizar`](/docs/referencia/bbva_peru_beta/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 Connect. 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/bbva_peru_beta/saldos-consultar.