# Cartolas PDF
> Antes de pedir datos nuevos, consulta atenciones en conexiones.estado.consultar.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **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`](/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. 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 [#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
```json
{
"$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 [#ejemplo]
```bash title="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}}'
```
```json title="MCP · meta-tool execute"
{
"tool": "bbva_peru_beta.cartolas.consultar",
"params": {
"accountId": "cuenta_ejemplo",
"limite": 20,
"incluirEnlaceOriginal": false
},
"connectionId": "conn_9tKfR2mQx4Vb"
}
```
**Salida esperada (200):**
```json
{
"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 [#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] | \[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 de observación de la lectura guardada, en formato ISO 8601. |
| `cartolas[].original` | objeto | null | sí | Enlace temporal del PDF original; null cuando no se solicitó incluirlo. | | | | | | | | | | | | | | | |
| `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] | \[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 de vencimiento del enlace de descarga, en formato ISO 8601. |
| `cursor` | string | null | sí | Cursor de la siguiente página de la misma lectura conservada; null al terminar. | | | | | | | | | | | | | | | |
| `cobertura` | objeto | null | sí | Cobertura de los PDF elegibles del inventario observado. null indica que no hay lectura conservada, no que no existan cartolas. | | | | | | | | | | | | | | | |
| `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] | \[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 de observación del inventario guardado, en formato ISO 8601. |
| `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
```json
{
"$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 [#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/cartolas-consultar.