Cuentas y saldos

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


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.

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

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

{
  "$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

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}}'

MCP · meta-tool execute

{
  "tool": "bbva_peru_beta.saldos.consultar",
  "params": {
    "limite": 100
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}

Salida esperada (200):

{
  "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

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í
`cuentas[].monedasDeclaradas`	lista de string `^[A-Z]{3}$`	null	sí
`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
`cuentas[].saldos[].saldoContable`	string `^-?(?:0	[1-9][0-9])(?:.[0-9][1-9])?$`	null
`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]
`cursor`	string	null	sí
`completo`	booleano	null	sí
`sincronizadoEn`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]

JSON Schema de salida

{
  "$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

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.

Próximos pasos

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