# Sincronizar conexión BancoEstado > Inicia sesión en BancoEstado Empresas y persiste los alcances pedidos (saldos, movimientos) para un período, en UNA sola sesión (un login, un logout). {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **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-Connection` en REST, campo `connectionId` en el `execute_write` de MCP y en las opciones del SDK. 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`](../conexiones/estado-consultar). ## Qué hace [#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 [#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 sincronizan sobre UNA sola sesión (un login, un logout), 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 ```json { "$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 sincronizan sobre UNA sola sesión (un login, un logout), 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 [#ejemplo] ```bash title="curl" 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"]}}' ``` ```ts title="SDK TypeScript" const data = await connect.tools.banco_estado.conexion.sincronizar({ periodo: "2026-08", alcances: ["saldos", "movimientos"] }, { connectionId: "conn_9tKfR2mQx4Vb" }); ``` ```json title="MCP · meta-tool execute" { "tool": "banco_estado.conexion.sincronizar", "params": { "periodo": "2026-08", "alcances": [ "saldos", "movimientos" ] }, "connectionId": "conn_9tKfR2mQx4Vb" } ``` **Salida esperada (200):** ```json { "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 [#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 abre una sesión real contra el sistema externo y puede tardar minutos, así que no se te hace esperar por él. | | | `jobId` | string | null | no | 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.completed' o 'sync.failed' si tu plan los incluye. Es null cuando 'estado' es 'completado': ahí el resultado ya está en la respuesta y no hay nada que seguir. | | `yaEnCurso` | booleano | no | 'true' significa que ya había una sincronización viva para esa conexión y ese período, y que 'jobId' es la de ella. No es un error ni un rechazo: pedir dos veces el mismo período es inofensivo y te devuelve el trabajo que ya está andando. 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, así que el 'jobId' que recibes es el trabajo que cubre tu pedido, lo hayas encolado tú o no. | | | `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 | Detalle técnico, cuando el conector pudo componer uno. En una fila que falló dice en qué paso ocurrió y qué se encontró (conteos, status HTTP, content-type); en una que terminó incompleta, qué no se pudo cubrir. Sirve para diagnosticar sin volver a reproducirlo, y nunca contiene datos del contribuyente. | | | `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 ```json { "$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 abre una sesión real contra 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.completed' o 'sync.failed' si tu plan los incluye. Es null cuando 'estado' es 'completado': ahí el resultado ya está en la respuesta y no hay nada que seguir.", "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, y que 'jobId' es la de ella. No es un error ni un rechazo: pedir dos veces el mismo período es inofensivo y te devuelve el trabajo que ya está andando. 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, así que el 'jobId' que recibes es el trabajo que cubre tu pedido, lo hayas encolado tú o no.", "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": "Detalle técnico, cuando el conector pudo componer uno. En una fila que falló dice en qué paso ocurrió y qué se encontró (conteos, status HTTP, content-type); en una que terminó incompleta, qué no se pudo cubrir. Sirve para diagnosticar sin volver a reproducirlo, y nunca contiene datos del contribuyente.", "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 [#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_credential_required` | 428 | no | Crea un enlace con conexiones.enlace.crear (modo reconectar si la conexión ya existe) y pide a la persona que entregue la credencial de nuevo. No reintentes con la credencial anterior. | | `connection_busy` | 409 | sí | Espera unos segundos y reintenta. Es una espera transitoria: no necesitas volver a conectar ni ingresar la credencial otra vez. | | `upstream_error` | 502 | sí | Reintenta más tarde. Si persiste, el problema está en el sistema externo, no en tu integración. | | `timeout` | 504 | sí | Reintenta. Para sincronizaciones largas usa la vía asíncrona y consulta el estado del trabajo. | | `connection_session_pending` | 409 | sí | Ejecuta la sincronización de esa conexión (ella acuña la sesión) o espera la programada, y reintenta. | | `connection_sync_in_progress` | 409 | sí | Espera a que termine y reintenta, o consulta directamente: puede que ya haya datos. | | `too_many_pending` | 429 | sí | Deja terminar los trabajos en curso antes de encolar más. | 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](../errores). ## Próximos pasos [#próximos-pasos] * [`banco_estado.movimientos.consultar`](./movimientos-consultar): lee el alcance `movimientos` que esta sincronización escribe. * [`banco_estado.saldos.consultar`](./saldos-consultar): lee el alcance `saldos` que esta sincronización escribe.