# Sincronizar conexión Tesorería > Sincroniza en una sola sesión del portal de la Tesorería General de la República las tres pantallas de convenios: «Comprobante de resolución», «Estado de pago de convenio» y «Cuotas convenios vigentes», y el detalle de cada convenio (cuotas, pagos y deudas acogidas). {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **Tool ID** | `tgr.conexion.sincronizar` | | **Nombre MCP** | `tgr__conexion__sincronizar` | | **Conector** | `tgr` | | **Plano** | `read` | | **Alcances** | `convenios` | | **Scope (permiso)** | `tgr:read` | | **Auth** | `connection_credentials` | | **Versión** | `1` | | **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] Son el estado actual de la empresa, no un período: el período sólo organiza la ejecución, y uno que no es el corriente no vuelve a consultar el portal. Es el ÚNICO camino que trae datos de la Tesorería: las tools '.consultar' leen lo que esto haya guardado. ## Entrada [#entrada] | Campo | Tipo | Requerido | Descripción | | | ---------- | ------------------------ | ---------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `periodo` | string \`^\d{4}-(0\[1-9] | 1\[0-2])$\` | no | Período de ejecución en AAAA-MM; si se omite, el mes actual en Santiago. No filtra los convenios: la Tesorería sólo muestra su estado actual. | | `alcances` | lista de string | no · default `["convenios"]` | Los módulos a sincronizar. Hoy hay uno: 'convenios', que trae las tres pantallas. | |
JSON Schema de entrada ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "periodo": { "description": "Período de ejecución en AAAA-MM; si se omite, el mes actual en Santiago. No filtra los convenios: la Tesorería sólo muestra su estado actual.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "alcances": { "default": [ "convenios" ], "description": "Los módulos a sincronizar. Hoy hay uno: 'convenios', que trae las tres pantallas.", "minItems": 1, "type": "array", "items": { "type": "string", "const": "convenios" } } } } ```
## Ejemplo [#ejemplo] ```bash title="curl" curl -X POST https://connect.emisso.ai/api/v1/tools/tgr.conexion.sincronizar/execute \ -H "Authorization: Bearer connect_sk_…" \ -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \ -H "Content-Type: application/json" \ -d '{"input":{}}' ``` ```ts title="SDK TypeScript" const data = await connect.tools.tgr.conexion.sincronizar({}, { connectionId: "conn_9tKfR2mQx4Vb" }); ``` ```json title="MCP · meta-tool execute" { "tool": "tgr.conexion.sincronizar", "params": {}, "connectionId": "conn_9tKfR2mQx4Vb" } ``` **Salida esperada (200):** ```json { "data": { "periodo": "2026-10", "estado": "encolado", "jobId": "sjb_3h5j7k9m1n2p4q6r8s0t1", "yaEnCurso": false }, "meta": { "request_id": "req_…", "tool_id": "tgr.conexion.sincronizar", "plane": "read", "latency_ms": 58240, "audit_status": "recorded" } } ``` > Las tres pantallas comparten un solo login con la Clave Tributaria del SII. Si la empresa no tiene convenios, el resultado trae cero filas y un 'detalle' que lo dice: la Tesorería mostró las pantallas vacías. ## Salida [#salida] | Campo | Tipo | Requerido | Descripción | | | ------------------------- | ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `periodo` | string | sí | Período de ejecución en AAAA-MM. | | | `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í | El módulo sincronizado. | | | `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"` · `"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": "Período de ejecución en AAAA-MM." }, "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", "const": "convenios", "description": "El módulo sincronizado." }, "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", "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 } } }, "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_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] * [`tgr.convenios.consultar`](./convenios-consultar): lee el alcance `convenios` que esta sincronización escribe. * [`tgr.convenios_cuotas.consultar`](./convenios_cuotas-consultar): lee el alcance `convenios` que esta sincronización escribe. * [`tgr.convenios_detalle.consultar`](./convenios_detalle-consultar): lee el alcance `convenios` que esta sincronización escribe. * [`tgr.resoluciones.consultar`](./resoluciones-consultar): lee el alcance `convenios` que esta sincronización escribe.