Emisso

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


Tool ID	`bbva_peru_beta.cartolas.consultar`
Nombre MCP	`bbva_peru_beta__cartolas__consultar`
Conector	`bbva_peru_beta`
Plano	`action`
Lee el alcance	`cartolas` (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. Lista PDF originales guardados. Corresponden a la última sincronización completa de una cuenta. Usa el accountId de saldos.consultar. Puede incluir enlaces de descarga válidos por cinco minutos. La cobertura corresponde a los PDF disponibles en el inventario observado; no interpreta el período ni el contenido del archivo. Sin lectura devuelve cobertura null, que no significa que no existan cartolas.

Entrada

Campo	Tipo	Requerido	Descripción
`accountId`	string	sí	Identificador de la cuenta obtenido en saldos.consultar.
`cursor`	string	no	Cursor de la página anterior de la misma cuenta y lectura conservada. Se usa sin modificarlo.
`limite`	entero 1-100	no · default `20`	Máximo de PDF por página de consulta; por defecto 20, hasta 100.
`incluirEnlaceOriginal`	booleano	no · default `false`	Solicita enlaces de descarga del original conservado, válidos por cinco minutos. Por defecto no los incluye.

JSON Schema de entrada

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "accountId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "Identificador de la cuenta obtenido en saldos.consultar."
    },
    "cursor": {
      "description": "Cursor de la página anterior de la misma cuenta y lectura conservada. Se usa sin modificarlo.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "limite": {
      "default": 20,
      "description": "Máximo de PDF por página de consulta; por defecto 20, hasta 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "incluirEnlaceOriginal": {
      "default": false,
      "description": "Solicita enlaces de descarga del original conservado, válidos por cinco minutos. Por defecto no los incluye.",
      "type": "boolean"
    }
  },
  "required": [
    "accountId"
  ],
  "additionalProperties": false
}

Ejemplo

curl

curl -X POST https://connect.emisso.ai/api/v1/tools/bbva_peru_beta.cartolas.consultar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"accountId":"cuenta_ejemplo","limite":20,"incluirEnlaceOriginal":false}}'

MCP · meta-tool execute

{
  "tool": "bbva_peru_beta.cartolas.consultar",
  "params": {
    "accountId": "cuenta_ejemplo",
    "limite": 20,
    "incluirEnlaceOriginal": false
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}

Salida esperada (200):

{
  "data": {
    "cartolas": [],
    "cursor": null,
    "cobertura": null
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "bbva_peru_beta.cartolas.consultar",
    "plane": "action",
    "latency_ms": 24,
    "audit_status": "recorded"
  }
}

Salida

Campo	Tipo	Requerido	Descripción
`cartolas`	lista de objeto	sí	Página de PDF originales de la lectura completa seleccionada para esta cuenta.
`cartolas[].id`	string	sí	Identificador opaco de la captura conservada del PDF, no el identificador bancario del documento.
`cartolas[].accountId`	string	sí	Identificador de la cuenta a la que pertenece el original conservado.
`cartolas[].nombreArchivo`	string	sí	Nombre original informado por el banco; no acredita el período ni el contenido del PDF.
`cartolas[].paginas`	entero 1-100	sí	Número de páginas comprobado al validar el formato del PDF conservado.
`cartolas[].bytes`	entero 8-5242880	sí	Tamaño en bytes del archivo PDF original conservado.
`cartolas[].observadoEn`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`cartolas[].original`	objeto	null	sí
`cartolas[].original.url`	string	sí	Enlace temporal para descargar el original conservado; la entrega vuelve a comprobar la autorización.
`cartolas[].original.expiraEn`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`cursor`	string	null	sí
`cobertura`	objeto	null	sí
`cobertura.accountId`	string	sí	Cuenta cubierta por el inventario conservado.
`cobertura.completo`	booleano	sí	Se conservaron todos los PDF elegibles del inventario observado; no afirma cobertura de otros períodos ni documentos futuros.
`cobertura.documentosInventario`	entero 0-500	sí	Total de registros originales del inventario bancario observado, incluidos otros formatos y versiones.
`cobertura.grupos`	entero 0-500	sí	Total de grupos documentales del inventario observado, con o sin PDF elegible.
`cobertura.pdfsElegibles`	entero 0-500	sí	Total de PDF elegibles conservados, uno por grupo con una versión PDF inequívoca.
`cobertura.gruposSinPdf`	entero 0-500	sí	Grupos del inventario observado que no tenían un PDF elegible.
`cobertura.observadoEn`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`cobertura.identidadContenido`	string	sí	No se ha interpretado ni verificado la identidad escrita dentro del PDF.
`cobertura.periodo`	string	sí	No se ha interpretado ni acreditado el período del contenido del PDF.

JSON Schema de salida

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "cartolas": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "Identificador opaco de la captura conservada del PDF, no el identificador bancario del documento."
          },
          "accountId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "Identificador de la cuenta a la que pertenece el original conservado."
          },
          "nombreArchivo": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096,
            "description": "Nombre original informado por el banco; no acredita el período ni el contenido del PDF."
          },
          "paginas": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Número de páginas comprobado al validar el formato del PDF conservado."
          },
          "bytes": {
            "type": "integer",
            "minimum": 8,
            "maximum": 5242880,
            "description": "Tamaño en bytes del archivo PDF original conservado."
          },
          "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 de observación de la lectura guardada, en formato ISO 8601."
          },
          "original": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Enlace temporal para descargar el original conservado; la entrega vuelve a comprobar la autorización."
                  },
                  "expiraEn": {
                    "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 de vencimiento del enlace de descarga, en formato ISO 8601."
                  }
                },
                "required": [
                  "url",
                  "expiraEn"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "Enlace temporal del PDF original; null cuando no se solicitó incluirlo."
          }
        },
        "required": [
          "id",
          "accountId",
          "nombreArchivo",
          "paginas",
          "bytes",
          "observadoEn",
          "original"
        ],
        "additionalProperties": false
      },
      "description": "Página de PDF originales de la lectura completa seleccionada para esta cuenta."
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Cursor de la siguiente página de la misma lectura conservada; null al terminar."
    },
    "cobertura": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "accountId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512,
              "description": "Cuenta cubierta por el inventario conservado."
            },
            "completo": {
              "type": "boolean",
              "const": true,
              "description": "Se conservaron todos los PDF elegibles del inventario observado; no afirma cobertura de otros períodos ni documentos futuros."
            },
            "documentosInventario": {
              "type": "integer",
              "minimum": 0,
              "maximum": 500,
              "description": "Total de registros originales del inventario bancario observado, incluidos otros formatos y versiones."
            },
            "grupos": {
              "type": "integer",
              "minimum": 0,
              "maximum": 500,
              "description": "Total de grupos documentales del inventario observado, con o sin PDF elegible."
            },
            "pdfsElegibles": {
              "type": "integer",
              "minimum": 0,
              "maximum": 500,
              "description": "Total de PDF elegibles conservados, uno por grupo con una versión PDF inequívoca."
            },
            "gruposSinPdf": {
              "type": "integer",
              "minimum": 0,
              "maximum": 500,
              "description": "Grupos del inventario observado que no tenían un PDF elegible."
            },
            "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 de observación del inventario guardado, en formato ISO 8601."
            },
            "identidadContenido": {
              "type": "string",
              "const": "no_interpretada",
              "description": "No se ha interpretado ni verificado la identidad escrita dentro del PDF."
            },
            "periodo": {
              "type": "string",
              "const": "no_interpretado",
              "description": "No se ha interpretado ni acreditado el período del contenido del PDF."
            }
          },
          "required": [
            "accountId",
            "completo",
            "documentosInventario",
            "grupos",
            "pdfsElegibles",
            "gruposSinPdf",
            "observadoEn",
            "identidadContenido",
            "periodo"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Cobertura de los PDF elegibles del inventario observado. null indica que no hay lectura conservada, no que no existan cartolas."
    }
  },
  "required": [
    "cartolas",
    "cursor",
    "cobertura"
  ],
  "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.

Cartolas PDF