Consultar movimientos de BancoEstado
Antes de pedir datos nuevos, consulta atenciones en conexiones.estado.consultar.
| Tool ID | banco_estado.movimientos.consultar |
| Nombre MCP | banco_estado__movimientos__consultar |
| Conector | banco_estado |
| Plano | action |
| Lee el alcance | movimientos (debe estar habilitado en la conexión) |
| Scope (permiso) | banco_estado:read |
| Auth | none |
| Versión | 3 |
| 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-Connectionen REST y campoconnectionIden elexecutede MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale deconexiones.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 los movimientos de BancoEstado YA sincronizados de esta conexión, del más reciente al más antiguo. Lectura pura: NO contacta al banco ni dispara una sincronización, así que si falta un período usa 'banco_estado.conexion.sincronizar' primero. Refleja la cartola del banco: en los días que la última sincronización leyó completos, un movimiento que el banco ya no muestra deja de aparecer aquí (por ejemplo, un provisorio que el banco reemplazó en el cierre nocturno por su versión definitiva, a veces con otra glosa u otro documento) y reaparece si el banco lo vuelve a mostrar. Un movimiento 'provisorio' de un día anterior tampoco aparece, en ningún día, una vez que una sincronización completa posterior del mismo mes ya no lo trae. Entre la medianoche y cerca de las 04:00 (hora de Chile) un movimiento del día puede no aparecer, igual que en el portal del banco. Cada movimiento trae 'estado': 'provisorio' si el banco todavía no lo contabiliza (puede cambiar o desaparecer en el cierre) o 'definitivo' si ya lo hizo, y se puede filtrar por él. Si guardas los movimientos en tu sistema, no te limites a agregar filas nuevas: vuelve a leer al menos el mes en curso y el anterior (con 'periodo') y reemplaza esos meses en tu copia. Los montos vienen como NÚMERO: 'monto' es la magnitud SIN signo, 'type' dice si sale ('credit') o entra ('debit') plata según el libro del banco (al revés de como se lee una cartola), y 'display' es ese monto ya formateado a la chilena con su signo. 'saldo' es el saldo arrastrado: es un balance, no lleva 'type' y conserva su propio signo. Cada movimiento trae además 'counterparty' con el nombre y el RUT del otro lado cuando la descripción los informa, ya separados y con el RUT en la forma del SII; si no se pueden leer con certeza, vienen en null. Pagina con 'cursor': cuando la respuesta trae 'cursor' distinto de null hay más filas, reenvía ese valor tal cual.
Entrada
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
numeroCuenta | string | no | Filtra por un número de cuenta. Omítelo para ver los movimientos de todas las cuentas de la conexión. |
periodo | string ^\d{4}-\d{2}$ | no | Filtra por el mes de la fecha del movimiento, en formato AAAA-MM (por ejemplo '2026-08'). Omítelo para traer todos los meses guardados. |
estado | "provisorio" · "definitivo" | no | Filtra por estado: 'definitivo' trae solo los movimientos que el banco ya contabilizó y 'provisorio' solo los del día que todavía puede reemplazar. Omítelo para traer los dos. |
cursor | string | no | Puntero opaco a la página siguiente. Reenvía tal cual el 'cursor' que devolvió la llamada anterior; nunca lo construyas a mano. Omítelo para pedir la primera página. |
limit | entero 1-500 | no · default 100 | Cuántas filas trae la página, entre 1 y 500. Por omisión, 100. |
JSON Schema de entrada
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"numeroCuenta": {
"description": "Filtra por un número de cuenta. Omítelo para ver los movimientos de todas las cuentas de la conexión.",
"type": "string"
},
"periodo": {
"description": "Filtra por el mes de la fecha del movimiento, en formato AAAA-MM (por ejemplo '2026-08'). Omítelo para traer todos los meses guardados.",
"type": "string",
"pattern": "^\\d{4}-\\d{2}$"
},
"estado": {
"description": "Filtra por estado: 'definitivo' trae solo los movimientos que el banco ya contabilizó y 'provisorio' solo los del día que todavía puede reemplazar. Omítelo para traer los dos.",
"type": "string",
"enum": [
"provisorio",
"definitivo"
]
},
"cursor": {
"description": "Puntero opaco a la página siguiente. Reenvía tal cual el 'cursor' que devolvió la llamada anterior; nunca lo construyas a mano. Omítelo para pedir la primera página.",
"type": "string"
},
"limit": {
"default": 100,
"description": "Cuántas filas trae la página, entre 1 y 500. Por omisión, 100.",
"type": "integer",
"minimum": 1,
"maximum": 500
}
}
}Ejemplo
curl -X POST https://connect.emisso.ai/api/v1/tools/banco_estado.movimientos.consultar/execute \
-H "Authorization: Bearer connect_sk_…" \
-H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
-H "Content-Type: application/json" \
-d '{"input":{"periodo":"2026-08"}}'{
"tool": "banco_estado.movimientos.consultar",
"params": {
"periodo": "2026-08"
},
"connectionId": "conn_9tKfR2mQx4Vb"
}Salida esperada (200):
{
"data": {
"movimientos": [
{
"numeroCuenta": "12345678901",
"periodo": "2026-08",
"fecha": "2026-08-11",
"descripcion": "TRANSFERENCIA OTRO BANCO A RUT 76111222-8 COMERCIAL DEMO SPA",
"documento": "1234567",
"monto": 1700000,
"type": "credit",
"display": "-1.700.000",
"saldo": 300000,
"oficina": "STGO.PRINCIPAL",
"origen": "linea",
"estado": "definitivo",
"counterparty": {
"name": "COMERCIAL DEMO SPA",
"rut": "76111222-8",
"bank": null,
"account": null
},
"counterpartySource": "descripcion",
"syncedAt": "2026-08-11T17:32:04.000Z"
}
],
"cursor": null
},
"meta": {
"request_id": "req_…",
"tool_id": "banco_estado.movimientos.consultar",
"plane": "action",
"latency_ms": 24,
"audit_status": "recorded"
}
}'type' es 'credit' porque la plata SALE: es la convención del libro del banco, al revés de como se lee una cartola. 'monto' no lleva el signo; 'display' sí. Como es un cargo, 'counterparty' es el destinatario. En un depósito o una comisión los cuatro campos vienen en null y 'counterpartySource' también.
Salida
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
movimientos | lista de objeto | sí | Los movimientos guardados que calzan con los filtros, del más reciente al más antiguo. Una lista vacía significa que ese período no se ha sincronizado, no que no haya movimientos. |
movimientos[].numeroCuenta | string | sí | El número de la cuenta a la que pertenece el movimiento. |
movimientos[].periodo | string | null | sí |
movimientos[].fecha | string | null | sí |
movimientos[].descripcion | string | null | sí |
movimientos[].documento | string | null | sí |
movimientos[].monto | número | null | sí |
movimientos[].type | "credit" · "debit" | null | sí |
movimientos[].display | string | null | sí |
movimientos[].saldo | número | null | sí |
movimientos[].oficina | string | null | sí |
movimientos[].origen | "linea" · "historica" | sí | Por cuál de las dos cartolas del banco se trajo la fila: 'linea' es la cartola abierta, que el banco todavía no cierra, e 'historica' una cartola que el banco ya cerró. Las cartolas no van por mes: el banco cierra una cuando junta cierta cantidad de movimientos. Es metadato de procedencia y no entra en la identidad del movimiento, así que el mismo movimiento traído por las dos no se duplica. |
movimientos[].estado | "provisorio" · "definitivo" | sí | Qué versión del movimiento muestra el banco. 'provisorio' = la del día, que el banco todavía no contabiliza: en el cierre nocturno la reemplaza por la definitiva, a veces con otra glosa u otro documento, o la saca. 'definitivo' = la contabilizada. En los dos casos el movimiento ocurrió. En chequera lo marca el banco; en cuenta corriente, que no trae marca, un movimiento sigue 'provisorio' mientras su fecha sea hoy o posterior (hora de Chile). La cartola histórica siempre es 'definitivo'. Se actualiza en cada sincronización. |
movimientos[].counterparty | objeto | sí | La contraparte del movimiento, extraída de la descripción que escribe el banco. QUÉ LADO ES depende de 'type': en un abono ('debit', plata que entra) es el origen; en un cargo ('credit', plata que sale) es el destinatario. Los campos vienen en 'null' cuando la descripción no la trae (depósitos, comisiones, compras, pagos) o cuando no calza con un formato conocido: nunca se completa ni se adivina. Son datos personales de terceros: trátalos como tales. |
movimientos[].counterparty.name | string | null | sí |
movimientos[].counterparty.rut | string | null | sí |
movimientos[].counterparty.bank | string | null | sí |
movimientos[].counterparty.account | string | null | sí |
movimientos[].counterpartySource | string | null | sí |
movimientos[].syncedAt | string | null | sí |
cursor | string | null | sí |
JSON Schema de salida
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"movimientos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"numeroCuenta": {
"type": "string",
"description": "El número de la cuenta a la que pertenece el movimiento."
},
"periodo": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El mes (AAAA-MM) de la fecha del movimiento, no el período con que se pidió la sincronización: el banco no se limita al mes pedido. Es el campo por el que filtra 'periodo' en la entrada. No entra en la identidad del movimiento, así que sincronizar pidiendo otro período no lo duplica."
},
"fecha": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Fecha del movimiento, en formato AAAA-MM-DD, sin hora. null si el banco no trajo la celda."
},
"descripcion": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La glosa del movimiento tal como aparece en la cartola (por ejemplo 'PAGO PROVEEDOR')."
},
"documento": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El número de documento asociado al movimiento, cuando el banco lo trae."
},
"monto": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Magnitud del movimiento SIN signo. El sentido lo da 'type' y el signo visible lo trae 'display'. Un null significa que el banco no trajo la celda, que no es lo mismo que cero."
},
"type": {
"anyOf": [
{
"type": "string",
"enum": [
"credit",
"debit"
]
},
{
"type": "null"
}
],
"description": "Eje crédito/débito del LIBRO DEL BANCO, no el de la cartola: 'debit' es plata que ENTRA a la cuenta (un abono) y 'credit' es plata que SALE (un cargo). Es al revés de la lectura intuitiva y está así a propósito. El campo 'monto' es la magnitud SIN signo; el signo lo lleva 'display' ('credit' → negativo). 'null' significa que el banco no informó el tipo: no asumas ninguno de los dos."
},
"display": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El monto ya formateado a la chilena y CON signo, derivado de 'type' ('credit', plata que sale, se muestra negativo). Es una comodidad de presentación: se calcula en la lectura y no se persiste. Para operar con el número usa 'monto' (magnitud sin signo) junto con 'type'."
},
"saldo": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "El saldo que queda en la cuenta después de este movimiento. Es un balance: no lleva 'type' y conserva su propio signo."
},
"oficina": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La oficina que el banco asocia al movimiento, en su propio texto (por ejemplo 'STGO.PRINCIPAL')."
},
"origen": {
"type": "string",
"enum": [
"linea",
"historica"
],
"description": "Por cuál de las dos cartolas del banco se trajo la fila: 'linea' es la cartola abierta, que el banco todavía no cierra, e 'historica' una cartola que el banco ya cerró. Las cartolas no van por mes: el banco cierra una cuando junta cierta cantidad de movimientos. Es metadato de procedencia y no entra en la identidad del movimiento, así que el mismo movimiento traído por las dos no se duplica."
},
"estado": {
"type": "string",
"enum": [
"provisorio",
"definitivo"
],
"description": "Qué versión del movimiento muestra el banco. 'provisorio' = la del día, que el banco todavía no contabiliza: en el cierre nocturno la reemplaza por la definitiva, a veces con otra glosa u otro documento, o la saca. 'definitivo' = la contabilizada. En los dos casos el movimiento ocurrió. En chequera lo marca el banco; en cuenta corriente, que no trae marca, un movimiento sigue 'provisorio' mientras su fecha sea hoy o posterior (hora de Chile). La cartola histórica siempre es 'definitivo'. Se actualiza en cada sincronización."
},
"counterparty": {
"type": "object",
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El nombre o razón social de la contraparte, tal como lo escribe el banco (en MAYÚSCULAS o capitalizado según la cartola, y a veces truncado: es el texto del portal, no un dato normalizado). 'null' cuando la descripción no lo trae."
},
"rut": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El RUT de la contraparte, sin puntos, con guion y la K en mayúscula (por ejemplo '76123456-0'), en la misma forma con que el SII identifica a sus contrapartes, para que las dos fuentes crucen. Solo se publica si el dígito verificador es válido; si no, viaja 'null' y el texto original sigue en 'descripcion'. 'null' cuando la descripción no lo trae, que es lo normal en la chequera: ahí casi siempre viene solo el nombre."
},
"bank": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Siempre 'null' en BancoEstado: la descripción no nombra el banco de la contraparte."
},
"account": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Siempre 'null' en BancoEstado: la descripción no trae la cuenta de la contraparte."
}
},
"required": [
"name",
"rut",
"bank",
"account"
],
"additionalProperties": false,
"description": "La contraparte del movimiento, extraída de la descripción que escribe el banco. QUÉ LADO ES depende de 'type': en un abono ('debit', plata que entra) es el origen; en un cargo ('credit', plata que sale) es el destinatario. Los campos vienen en 'null' cuando la descripción no la trae (depósitos, comisiones, compras, pagos) o cuando no calza con un formato conocido: nunca se completa ni se adivina. Son datos personales de terceros: trátalos como tales."
},
"counterpartySource": {
"anyOf": [
{
"type": "string",
"const": "descripcion"
},
{
"type": "null"
}
],
"description": "De dónde salió 'counterparty'. 'descripcion': la extrajimos del texto del movimiento, que en BancoEstado es el único lugar donde viaja. 'null': no hay contraparte que publicar en esta fila, porque el banco no la escribió o porque el texto no calzó con un formato conocido. El texto completo sigue en 'descripcion'."
},
"syncedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Cuándo se leyó esta fila del banco (ISO 8601). Si está vieja, la caché puede haber dejado de moverse (por ejemplo, con la conexión pausada tras varios fallos de credencial) mientras esta tool sigue respondiendo con filas antiguas."
}
},
"required": [
"numeroCuenta",
"periodo",
"fecha",
"descripcion",
"documento",
"monto",
"type",
"display",
"saldo",
"oficina",
"origen",
"estado",
"counterparty",
"counterpartySource",
"syncedAt"
],
"additionalProperties": false
},
"description": "Los movimientos guardados que calzan con los filtros, del más reciente al más antiguo. Una lista vacía significa que ese período no se ha sincronizado, no que no haya movimientos."
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Puntero a la página siguiente. Si viene distinto de null hay más filas: vuelve a llamar reenviándolo tal cual en 'cursor'. Un null significa que no queda nada por traer."
}
},
"required": [
"movimientos",
"cursor"
],
"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
banco_estado.conexion.sincronizar: la tool que escribe los datos que esta lectura devuelve.- Sincronizar y consultar: por qué leer datos reales son dos pasos.