Sincronizar conexión BancoEstado
Inicia sesión en BancoEstado Empresas y persiste los alcances pedidos (saldos, movimientos) para un período, en una sola sincronización.
| Tool ID | banco_estado.conexion.sincronizar |
| Nombre MCP | banco_estado__conexion__sincronizar |
| Conector | banco_estado |
| Plano | read |
| Alcances | saldos, movimientos |
| Scope (permiso) | banco_estado:read |
| Auth | connection_credentials |
| Versión | 2 |
| Sensible | sí |
| Deprecado | no |
| Comportamiento | readOnly=false, destructive=false, idempotent=true, openWorld=true |
Requiere conexión. Indica cuál en cada llamada: header
X-Connect-Connectionen REST y campoconnectionIden elexecute_writede 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
Es el ÚNICO camino que trae datos del banco: las tools de consulta leen lo ya guardado. Deja los movimientos guardados iguales a la cartola del banco en los días que leyó completos: lo que el banco ya no muestra deja de aparecer en 'banco_estado.movimientos.consultar', y lo que vuelve a mostrar reaparece. saldos es una foto del momento, no del período, así que sólo se sincroniza pidiendo el período corriente. Puede tardar cerca de un minuto, y mientras corre el titular no va a poder entrar al portal: BancoEstado admite una sola sesión activa por usuario.
Entrada
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
periodo | string ^\d{4}-\d{2}$ | sí | Un mes, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Cada sitio de uso afina qué significa ahí: en una sincronización es el mes que se va a traer, y en una consulta a la caché es el filtro. Esta descripción base existe para que el campo nunca llegue pelado a quien lee el contrato. |
alcances | lista de "saldos" · "movimientos" | sí | Qué módulos de datos traer en esta corrida, al menos uno. Todos se traen en la misma sincronización, así que pedir varios en una llamada cuesta menos que llamar una vez por cada uno. Un alcance debe estar habilitado en la conexión; si no lo está, la llamada responde 'alcance_not_enabled'. |
JSON Schema de entrada
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"periodo": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}$",
"description": "Un mes, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Cada sitio de uso afina qué significa ahí: en una sincronización es el mes que se va a traer, y en una consulta a la caché es el filtro. Esta descripción base existe para que el campo nunca llegue pelado a quien lee el contrato."
},
"alcances": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"saldos",
"movimientos"
]
},
"description": "Qué módulos de datos traer en esta corrida, al menos uno. Todos se traen en la misma sincronización, así que pedir varios en una llamada cuesta menos que llamar una vez por cada uno. Un alcance debe estar habilitado en la conexión; si no lo está, la llamada responde 'alcance_not_enabled'."
}
},
"required": [
"periodo",
"alcances"
]
}Ejemplo
curl -X POST https://connect.emisso.ai/api/v1/tools/banco_estado.conexion.sincronizar/execute \
-H "Authorization: Bearer connect_sk_…" \
-H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
-H "Content-Type: application/json" \
-d '{"input":{"periodo":"2026-08","alcances":["saldos","movimientos"]}}'{
"tool": "banco_estado.conexion.sincronizar",
"params": {
"periodo": "2026-08",
"alcances": [
"saldos",
"movimientos"
]
},
"connectionId": "conn_9tKfR2mQx4Vb"
}Salida esperada (200):
{
"data": {
"periodo": "2026-08",
"estado": "encolado",
"jobId": "sjb_7q1w3e5r9t0y2u4i6o8p1",
"yaEnCurso": false
},
"meta": {
"request_id": "req_…",
"tool_id": "banco_estado.conexion.sincronizar",
"plane": "read",
"latency_ms": 58240,
"audit_status": "recorded"
}
}Con un período ya cerrado, 'saldos' devuelve 0 con su 'detalle': es una foto del momento y sólo se sincroniza pidiendo el período corriente.
Salida
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
periodo | string | sí | Eco del período que se pidió, para poder correlacionar la respuesta sin guardarlo tú. |
estado | "encolado" · "completado" | sí | 'encolado' = la sincronización quedó en cola y va a empezar enseguida; esta respuesta NO trae datos todavía, y el trabajo se sigue por 'jobId'. 'completado' = la sincronización ya corrió y su resumen por alcance viene en 'results'. Un cliente recibe siempre 'encolado': un sync consulta el sistema externo y puede tardar minutos, así que no se te hace esperar por él. |
jobId | string | null | no |
yaEnCurso | booleano | no | 'true' significa que ya había una sincronización viva para esa conexión y ese período, así que no se creó otra. No es un error ni un rechazo. Si esa sincronización sigue en cola, 'jobId' es el suyo; si ya está corriendo, 'jobId' llega null y su avance se ve en 'trabajos' de 'conexiones.estado.consultar'. Cubre el período, no necesariamente los alcances que pediste: si pediste otros, vuelve a pedirlos cuando termine. Ojo con el otro lado: 'false' NO garantiza que la hayas creado tú: dos llamadas a la vez pueden recibir las dos 'false' y el MISMO 'jobId'. Lo que sí vale siempre es que hay una sola sincronización activa por conexión y período. |
results | lista de objeto | no | El resumen por alcance, una fila por alcance sincronizado. AUSENTE cuando 'estado' es 'encolado': el trabajo todavía no corrió. Ausente no es lo mismo que vacío: un arreglo vacío significaría que se miró y no había nada. |
results[].alcance | string | sí | Cuál de los alcances pedidos describe esta fila. Hay una fila por alcance solicitado, en el orden canónico del conector, no en el orden en que los pediste. |
results[].marcador | string | no | Uso interno de Emisso; no se publica. En GET /v1/syncs/{id}, la fila trae en su lugar 'motivo': qué pasó y quién tiene que actuar, de la lista cerrada del catálogo de errores. |
results[].status | "ok" · "partial" · "failed" | sí | 'ok' = se cubrió el alcance completo; 'partial' = se guardaron las filas legibles, pero una pata o parte de la cartola quedó sin cubrir (puede haber 0 filas). La causa va en 'marcador' y la advertencia en 'detalle'. 'failed' = no se pudo completar el alcance; revisa 'error' y 'recordsSynced'. |
results[].recordsSynced | entero | sí | Cuántos registros de este alcance escribió ESTA corrida. Es el trabajo de esta llamada, no el total acumulado que tienes guardado: para saber cuánto hay, consulta. Un 0 no significa por sí solo «no hay datos»; cuando el cero tiene una explicación, viene en 'detalle'. |
results[].error | string | no | Código de error del alcance cuando 'status' es 'failed'. Un 'partial' conserva los datos legibles y explica la cobertura incompleta mediante 'detalle' y 'marcador'. |
results[].detalle | string | no | Explicación en lenguaje llano cuando el alcance quedó parcial o un cero necesita contexto; transmítela junto con 'recordsSynced'. |
JSON Schema de salida
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"periodo": {
"type": "string",
"description": "Eco del período que se pidió, para poder correlacionar la respuesta sin guardarlo tú."
},
"estado": {
"type": "string",
"enum": [
"encolado",
"completado"
],
"description": "'encolado' = la sincronización quedó en cola y va a empezar enseguida; esta respuesta NO trae datos todavía, y el trabajo se sigue por 'jobId'. 'completado' = la sincronización ya corrió y su resumen por alcance viene en 'results'. Un cliente recibe siempre 'encolado': un sync consulta el sistema externo y puede tardar minutos, así que no se te hace esperar por él."
},
"jobId": {
"description": "El identificador de la sincronización encolada. Por la API REST, el avance se consulta en 'GET /v1/syncs/{jobId}'; por MCP, búscalo en 'trabajos' de 'conexiones.estado.consultar' y revisa 'datosListos' ahí mismo. Es el mismo id que viaja en el webhook 'sync.succeeded' o 'sync.failed' si tu plan los incluye. Es null cuando 'estado' es 'completado', porque ahí el resultado ya está en la respuesta, y cuando 'yaEnCurso' es true y esa sincronización ya está corriendo.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"yaEnCurso": {
"description": "'true' significa que ya había una sincronización viva para esa conexión y ese período, así que no se creó otra. No es un error ni un rechazo. Si esa sincronización sigue en cola, 'jobId' es el suyo; si ya está corriendo, 'jobId' llega null y su avance se ve en 'trabajos' de 'conexiones.estado.consultar'. Cubre el período, no necesariamente los alcances que pediste: si pediste otros, vuelve a pedirlos cuando termine. Ojo con el otro lado: 'false' NO garantiza que la hayas creado tú: dos llamadas a la vez pueden recibir las dos 'false' y el MISMO 'jobId'. Lo que sí vale siempre es que hay una sola sincronización activa por conexión y período.",
"type": "boolean"
},
"results": {
"description": "El resumen por alcance, una fila por alcance sincronizado. AUSENTE cuando 'estado' es 'encolado': el trabajo todavía no corrió. Ausente no es lo mismo que vacío: un arreglo vacío significaría que se miró y no había nada.",
"type": "array",
"items": {
"type": "object",
"properties": {
"alcance": {
"type": "string",
"description": "Cuál de los alcances pedidos describe esta fila. Hay una fila por alcance solicitado, en el orden canónico del conector, no en el orden en que los pediste."
},
"marcador": {
"description": "Uso interno de Emisso; no se publica. En GET /v1/syncs/{id}, la fila trae en su lugar 'motivo': qué pasó y quién tiene que actuar, de la lista cerrada del catálogo de errores.",
"type": "string"
},
"status": {
"type": "string",
"enum": [
"ok",
"partial",
"failed"
],
"description": "'ok' = se cubrió el alcance completo; 'partial' = se guardaron las filas legibles, pero una pata o parte de la cartola quedó sin cubrir (puede haber 0 filas). La causa va en 'marcador' y la advertencia en 'detalle'. 'failed' = no se pudo completar el alcance; revisa 'error' y 'recordsSynced'."
},
"recordsSynced": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Cuántos registros de este alcance escribió ESTA corrida. Es el trabajo de esta llamada, no el total acumulado que tienes guardado: para saber cuánto hay, consulta. Un 0 no significa por sí solo «no hay datos»; cuando el cero tiene una explicación, viene en 'detalle'."
},
"error": {
"description": "Código de error del alcance cuando 'status' es 'failed'. Un 'partial' conserva los datos legibles y explica la cobertura incompleta mediante 'detalle' y 'marcador'.",
"type": "string"
},
"detalle": {
"description": "Explicación en lenguaje llano cuando el alcance quedó parcial o un cero necesita contexto; transmítela junto con 'recordsSynced'.",
"type": "string"
}
},
"required": [
"alcance",
"status",
"recordsSynced"
],
"additionalProperties": false
}
}
},
"required": [
"periodo",
"estado"
],
"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. |
too_many_pending | 429 | sí | Deja terminar los trabajos en curso antes de encolar más. |
La llamada solo encola: las fallas del sistema externo (credencial, sesión, caída del portal) no llegan en esta respuesta, sino en el trabajo: en outcomes y last_error de GET /v1/syncs/{jobId}, o en los webhooks sync.succeeded (un alcance que falló junto a otros que terminaron) y sync.failed.
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.movimientos.consultar: lee el alcancemovimientosque esta sincronización escribe.banco_estado.saldos.consultar: lee el alcancesaldosque esta sincronización escribe.