Emisso

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


Tool ID	`bbva_peru_beta.movimientos.consultar`
Nombre MCP	`bbva_peru_beta__movimientos__consultar`
Conector	`bbva_peru_beta`
Plano	`action`
Lee el alcance	`movimientos` (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. Consulta movimientos guardados. Corresponden a una cuenta y al intervalo exacto de una sincronización. Usa el accountId obtenido en saldos.consultar. Conserva importes, monedas y fechas originales. Para meses anteriores la sincronización cubre del primer al último día; para el mes actual, hasta el día de lectura en Perú. La disponibilidad histórica depende del banco. Sin lectura de ese intervalo devuelve cobertura null, que no significa cero movimientos.

Entrada

Campo	Tipo	Requerido	Descripción
`accountId`	string	sí	Identificador de la cuenta obtenido en saldos.consultar.
`period`	objeto	sí	Intervalo civil exacto de la sincronización que se consulta, por fecha de operación y dentro de un mismo mes.
`period.axis`	string	sí	Fecha de operación usada por la sincronización.
`period.from`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`period.to`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`cursor`	string	no	Cursor de la página anterior para la misma cuenta e intervalo. Se usa sin construirlo ni modificarlo.
`limite`	entero 1-200	no · default `100`	Máximo de movimientos por página de consulta; por defecto 100, hasta 200.

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."
    },
    "period": {
      "type": "object",
      "properties": {
        "axis": {
          "type": "string",
          "const": "operationDate",
          "description": "Fecha de operación usada por la sincronización."
        },
        "from": {
          "type": "string",
          "format": "date",
          "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])))$",
          "description": "Primer día del intervalo sincronizado, AAAA-MM-DD."
        },
        "to": {
          "type": "string",
          "format": "date",
          "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])))$",
          "description": "Último día del intervalo sincronizado, AAAA-MM-DD."
        }
      },
      "required": [
        "axis",
        "from",
        "to"
      ],
      "additionalProperties": false,
      "description": "Intervalo civil exacto de la sincronización que se consulta, por fecha de operación y dentro de un mismo mes."
    },
    "cursor": {
      "description": "Cursor de la página anterior para la misma cuenta e intervalo. Se usa sin construirlo ni modificarlo.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "limite": {
      "default": 100,
      "description": "Máximo de movimientos por página de consulta; por defecto 100, hasta 200.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "accountId",
    "period"
  ],
  "additionalProperties": false
}

Ejemplo

curl

curl -X POST https://connect.emisso.ai/api/v1/tools/bbva_peru_beta.movimientos.consultar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"accountId":"cuenta_ejemplo","period":{"axis":"operationDate","from":"2026-11-01","to":"2026-11-06"},"limite":100}}'

MCP · meta-tool execute

{
  "tool": "bbva_peru_beta.movimientos.consultar",
  "params": {
    "accountId": "cuenta_ejemplo",
    "period": {
      "axis": "operationDate",
      "from": "2026-11-01",
      "to": "2026-11-06"
    },
    "limite": 100
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}

Salida esperada (200):

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

Salida

Campo	Tipo	Requerido	Descripción
`movimientos`	lista de objeto	sí	Página de movimientos guardados de la cuenta y del intervalo solicitados.
`movimientos[].id`	string	sí	Identificador nativo íntegro del movimiento, dentro de su cuenta.
`movimientos[].accountId`	string	sí	Identificador de la cuenta a la que pertenece el movimiento.
`movimientos[].numeroCuenta`	string	null	sí
`movimientos[].importe`	objeto	sí	Importe del movimiento y su moneda originales, sin convertir ni inferir el signo.
`movimientos[].importe.amount`	string `^-?(?:0	[1-9][0-9]*)(?:.[0-9]+)?$`	sí
`movimientos[].importe.currency`	string `^[A-Z]{3}$`	sí	Código de tres letras de la moneda informada para este importe.
`movimientos[].saldoContable`	objeto	null	sí
`movimientos[].saldoContable.amount`	string `^-?(?:0	[1-9][0-9]*)(?:.[0-9]+)?$`	sí
`movimientos[].saldoContable.currency`	string `^[A-Z]{3}$`	sí	Código de tres letras de la moneda informada para este importe.
`movimientos[].fechas`	objeto	sí	Fechas informadas por el banco, conservadas por separado sin equiparar sus significados.
`movimientos[].fechas.operation`	objeto	null	sí
`movimientos[].fechas.process`	objeto	null	sí
`movimientos[].fechas.valuation`	objeto	null	sí
`movimientos[].concepto`	objeto	null	sí
`movimientos[].concepto.id`	string	null	sí
`movimientos[].concepto.name`	string	null	sí
`movimientos[].comentarios`	string	null	sí
`movimientos[].datosAdicionales`	string	null	sí
`movimientos[].camposNoInterpretados`	booleano	sí	La fuente incluyó campos adicionales que esta lectura no interpreta.
`cursor`	string	null	sí
`cobertura`	objeto	null	sí
`cobertura.accountId`	string	sí	Cuenta cubierta por esta lectura conservada.
`cobertura.eje`	string	sí	Fecha de operación usada para seleccionar el intervalo.
`cobertura.desde`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`cobertura.hasta`	string `^(?:(?:\d\d[2468][048]	\d\d[13579][26]	\d\d0[48]
`cobertura.desdeLiteral`	string	sí	Límite inicial exacto enviado por el portal, sin convertir su zona horaria.
`cobertura.hastaLiteral`	string	sí	Límite final exacto enviado por el portal; conserva el corte de la lectura, sin extenderlo al cierre del día.
`cobertura.representacion`	string	sí	Los límites conservan la representación civil original del portal.
`cobertura.completo`	booleano	sí	Se conservaron todas las páginas de ese intervalo y corte; no acredita frescura posterior ni un día terminado.
`cobertura.registros`	entero 0-10000	sí	Total de movimientos de la lectura completa, no sólo de esta página de consulta.
`cobertura.paginas`	entero 1-20	sí	Número de páginas bancarias que se leyeron para completar el intervalo.
`cobertura.observadoEn`	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": {
    "movimientos": {
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "Identificador nativo íntegro del movimiento, dentro de su cuenta."
          },
          "accountId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "Identificador de la cuenta a la que pertenece el movimiento."
          },
          "numeroCuenta": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 512
              },
              {
                "type": "null"
              }
            ],
            "description": "Número de cuenta informado para el movimiento; null si no está presente."
          },
          "importe": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "string",
                "maxLength": 258,
                "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$",
                "description": "Importe decimal exacto como texto, con el signo informado. No convierte moneda ni infiere cargo o abono."
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$",
                "description": "Código de tres letras de la moneda informada para este importe."
              }
            },
            "required": [
              "amount",
              "currency"
            ],
            "additionalProperties": false,
            "description": "Importe del movimiento y su moneda originales, sin convertir ni inferir el signo."
          },
          "saldoContable": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "string",
                    "maxLength": 258,
                    "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$",
                    "description": "Importe decimal exacto como texto, con el signo informado. No convierte moneda ni infiere cargo o abono."
                  },
                  "currency": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "Código de tres letras de la moneda informada para este importe."
                  }
                },
                "required": [
                  "amount",
                  "currency"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "Saldo contable informado para esta fila, con su propia moneda; null cuando está ausente."
          },
          "fechas": {
            "type": "object",
            "properties": {
              "operation": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "format": {
                        "type": "string",
                        "enum": [
                          "date_only",
                          "datetime_zone",
                          "datetime_no_zone"
                        ],
                        "description": "Formato original: fecha sola, fecha y hora con zona explícita, o fecha y hora sin zona. No infiere una zona ausente."
                      },
                      "value": {
                        "type": "string",
                        "minLength": 10,
                        "maxLength": 128,
                        "description": "Texto original de la fecha o fecha y hora, sin conversión de zona."
                      }
                    },
                    "required": [
                      "format",
                      "value"
                    ],
                    "additionalProperties": false,
                    "description": "Fecha y hora originales del banco. Se conserva su calendario y texto; no se convierte a otra zona horaria."
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Fecha de operación original; null si el banco no la informó."
              },
              "process": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "format": {
                        "type": "string",
                        "enum": [
                          "date_only",
                          "datetime_zone",
                          "datetime_no_zone"
                        ],
                        "description": "Formato original: fecha sola, fecha y hora con zona explícita, o fecha y hora sin zona. No infiere una zona ausente."
                      },
                      "value": {
                        "type": "string",
                        "minLength": 10,
                        "maxLength": 128,
                        "description": "Texto original de la fecha o fecha y hora, sin conversión de zona."
                      }
                    },
                    "required": [
                      "format",
                      "value"
                    ],
                    "additionalProperties": false,
                    "description": "Fecha y hora originales del banco. Se conserva su calendario y texto; no se convierte a otra zona horaria."
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Fecha de proceso original; null si el banco no la informó."
              },
              "valuation": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "format": {
                        "type": "string",
                        "enum": [
                          "date_only",
                          "datetime_zone",
                          "datetime_no_zone"
                        ],
                        "description": "Formato original: fecha sola, fecha y hora con zona explícita, o fecha y hora sin zona. No infiere una zona ausente."
                      },
                      "value": {
                        "type": "string",
                        "minLength": 10,
                        "maxLength": 128,
                        "description": "Texto original de la fecha o fecha y hora, sin conversión de zona."
                      }
                    },
                    "required": [
                      "format",
                      "value"
                    ],
                    "additionalProperties": false,
                    "description": "Fecha y hora originales del banco. Se conserva su calendario y texto; no se convierte a otra zona horaria."
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Fecha de valoración original; null si el banco no la informó."
              }
            },
            "required": [
              "operation",
              "process",
              "valuation"
            ],
            "additionalProperties": false,
            "description": "Fechas informadas por el banco, conservadas por separado sin equiparar sus significados."
          },
          "concepto": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 512
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Código original del concepto; null si no está presente."
                  },
                  "name": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 4096
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Nombre original del concepto; null si no está presente."
                  }
                },
                "required": [
                  "id",
                  "name"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "Concepto informado para el movimiento; null si no está presente."
          },
          "comentarios": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 4096
              },
              {
                "type": "null"
              }
            ],
            "description": "Comentarios conservados como texto; null si no se recibió un texto interpretable."
          },
          "datosAdicionales": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 4096
              },
              {
                "type": "null"
              }
            ],
            "description": "Datos adicionales conservados como texto; null si no se recibió un texto interpretable."
          },
          "camposNoInterpretados": {
            "type": "boolean",
            "description": "La fuente incluyó campos adicionales que esta lectura no interpreta."
          }
        },
        "required": [
          "id",
          "accountId",
          "numeroCuenta",
          "importe",
          "saldoContable",
          "fechas",
          "concepto",
          "comentarios",
          "datosAdicionales",
          "camposNoInterpretados"
        ],
        "additionalProperties": false
      },
      "description": "Página de movimientos guardados de la cuenta y del intervalo solicitados."
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Cursor de la siguiente página de esta misma lectura conservada; null al terminar."
    },
    "cobertura": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "accountId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512,
              "description": "Cuenta cubierta por esta lectura conservada."
            },
            "eje": {
              "type": "string",
              "const": "operationDate",
              "description": "Fecha de operación usada para seleccionar el intervalo."
            },
            "desde": {
              "type": "string",
              "format": "date",
              "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])))$",
              "description": "Primer día civil del intervalo sincronizado, AAAA-MM-DD."
            },
            "hasta": {
              "type": "string",
              "format": "date",
              "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])))$",
              "description": "Último día civil del intervalo sincronizado, AAAA-MM-DD."
            },
            "desdeLiteral": {
              "type": "string",
              "minLength": 10,
              "maxLength": 128,
              "description": "Límite inicial exacto enviado por el portal, sin convertir su zona horaria."
            },
            "hastaLiteral": {
              "type": "string",
              "minLength": 10,
              "maxLength": 128,
              "description": "Límite final exacto enviado por el portal; conserva el corte de la lectura, sin extenderlo al cierre del día."
            },
            "representacion": {
              "type": "string",
              "const": "portal_civil_original",
              "description": "Los límites conservan la representación civil original del portal."
            },
            "completo": {
              "type": "boolean",
              "const": true,
              "description": "Se conservaron todas las páginas de ese intervalo y corte; no acredita frescura posterior ni un día terminado."
            },
            "registros": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10000,
              "description": "Total de movimientos de la lectura completa, no sólo de esta página de consulta."
            },
            "paginas": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "description": "Número de páginas bancarias que se leyeron para completar el intervalo."
            },
            "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."
            }
          },
          "required": [
            "accountId",
            "eje",
            "desde",
            "hasta",
            "desdeLiteral",
            "hastaLiteral",
            "representacion",
            "completo",
            "registros",
            "paginas",
            "observadoEn"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Cobertura íntegra del intervalo hasta el corte conservado. No afirma que el día haya terminado ni que los datos estén actualizados ahora. null significa que no hay lectura de ese intervalo, no cero movimientos."
    }
  },
  "required": [
    "movimientos",
    "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.

Movimientos