# Sincronizar conexión Banco Security > Sincroniza los alcances solicitados (transferencias, nóminas, 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_security.conexion.sincronizar` | | **Nombre MCP** | `banco_security__conexion__sincronizar` | | **Conector** | `banco_security` | | **Plano** | `read` | | **Alcances** | `transferencias`, `saldos`, `movimientos`, `nominas` | | **Scope (permiso)** | `banco_security:read` | | **Auth** | `connection_credentials` | | **Versión** | `3` | | **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` 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] `saldos` es una foto del momento, no del período: solo se sincroniza cuando se pide el período corriente. `movimientos` cubre cualquier período: el conector elige solo la cartola que corresponde (la del mes en curso o la histórica) y las dos escriben la misma tabla, así que un mismo movimiento traído por las dos NO se duplica. ## 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 `"transferencias"` · `"nominas"` · `"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": [ "transferencias", "nominas", "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_security.conexion.sincronizar/execute \ -H "Authorization: Bearer connect_sk_…" \ -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \ -H "Content-Type: application/json" \ -d '{"input":{"periodo":"2026-07","alcances":["transferencias","saldos","movimientos"]}}' ``` ```ts title="SDK TypeScript" const data = await connect.tools.banco_security.conexion.sincronizar({ periodo: "2026-07", alcances: ["transferencias", "saldos", "movimientos"] }, { connectionId: "conn_9tKfR2mQx4Vb" }); ``` ```json title="MCP · meta-tool execute" { "tool": "banco_security.conexion.sincronizar", "params": { "periodo": "2026-07", "alcances": [ "transferencias", "saldos", "movimientos" ] }, "connectionId": "conn_9tKfR2mQx4Vb" } ``` **Salida esperada (200):** ```json { "data": { "periodo": "2026-07", "results": [ { "alcance": "transferencias", "status": "ok", "recordsSynced": 18 }, { "alcance": "saldos", "status": "ok", "recordsSynced": 0, "detalle": "Los saldos son una foto del momento, no del período, así que solo se sincronizan en el período corriente. Este cero NO significa que la cuenta no tenga saldo: pediste 2026-07; pide 2026-08 para obtenerlo." }, { "alcance": "movimientos", "status": "ok", "recordsSynced": 214 } ] }, "meta": { "request_id": "req_…", "tool_id": "banco_security.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 solo 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ú. | | `results` | lista de objeto | sí | Una fila por alcance pedido, con cómo le fue a cada uno. | | `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[].status` | `"ok"` · `"failed"` | sí | 'ok' = el alcance terminó bien; que 'recordsSynced' sea 0 no lo vuelve un fallo. 'failed' = no terminó bien, y la causa va en 'error'. Ojo con un 'failed': NO garantiza que no se haya escrito nada. Cuando el sistema externo trunca un listado, el alcance queda 'failed' con las filas que alcanzó en 'recordsSynced'. Mira siempre las dos cosas juntas. Y revisa fila por fila: un alcance puede fallar mientras los otros de la misma corrida terminan bien. | | `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 | Por qué este alcance no terminó bien. Presente solo cuando 'status' es 'failed'. Normalmente es un código del catálogo de errores; cuando el sistema externo truncó el listado es una etiqueta de resultado ('movimientos\_truncated', 'cartolas\_truncated') que no está en ese catálogo y que significa «se escribió lo que alcanzó a venir». Decide por el valor, nunca por el texto libre. | | `results[].detalle` | string | no | Explicación en lenguaje llano, presente solo cuando el resultado necesita una. Existe para que un cero se pueda transmitir tal cual en vez de concluir «no hay datos»: transmítelo a quien pregunte en lugar de resumir el número solo. |
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ú." }, "results": { "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." }, "status": { "type": "string", "enum": [ "ok", "failed" ], "description": "'ok' = el alcance terminó bien; que 'recordsSynced' sea 0 no lo vuelve un fallo. 'failed' = no terminó bien, y la causa va en 'error'. Ojo con un 'failed': NO garantiza que no se haya escrito nada. Cuando el sistema externo trunca un listado, el alcance queda 'failed' con las filas que alcanzó en 'recordsSynced'. Mira siempre las dos cosas juntas. Y revisa fila por fila: un alcance puede fallar mientras los otros de la misma corrida terminan bien." }, "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": "Por qué este alcance no terminó bien. Presente solo cuando 'status' es 'failed'. Normalmente es un código del catálogo de errores; cuando el sistema externo truncó el listado es una etiqueta de resultado ('movimientos_truncated', 'cartolas_truncated') que no está en ese catálogo y que significa «se escribió lo que alcanzó a venir». Decide por el valor, nunca por el texto libre.", "type": "string" }, "detalle": { "description": "Explicación en lenguaje llano, presente solo cuando el resultado necesita una. Existe para que un cero se pueda transmitir tal cual en vez de concluir «no hay datos»: transmítelo a quien pregunte en lugar de resumir el número solo.", "type": "string" } }, "required": [ "alcance", "status", "recordsSynced" ], "additionalProperties": false }, "description": "Una fila por alcance pedido, con cómo le fue a cada uno." } }, "required": [ "periodo", "results" ], "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. El candado es por conexión y se suelta solo. | | `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_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_security.transferencias.consultar`](./transferencias-consultar): lee el alcance `transferencias` que esta sincronización escribe. * [`banco_security.nominas.consultar`](./nominas-consultar): lee el alcance `nominas` que esta sincronización escribe. * [`banco_security.nomina_pagos.consultar`](./nomina_pagos-consultar): lee el alcance `nominas` que esta sincronización escribe. * [`banco_security.saldos.consultar`](./saldos-consultar): lee el alcance `saldos` que esta sincronización escribe. * [`banco_security.movimientos.consultar`](./movimientos-consultar): lee el alcance `movimientos` que esta sincronización escribe.