Sincronizar conexión Tesorería
Sincroniza en una sola pasada, desde 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).
| 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-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
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. El detalle se lee por tandas y se mantiene al día con estas reglas: las cuotas de cada convenio se releen a diario desde 5 días antes de su próximo vencimiento hasta 5 después, y cada 7 días fuera de esa ventana; el comprobante, cada 90 días. Una sincronización que pide el cliente (API, MCP o panel) además relee las cuotas que no se han leído en los últimos 30 minutos, primero las de convenios con vencimiento cercano, con el mismo tope por tanda. Si la Tesorería no deja leer el detalle, las tres pantallas se guardan igual, el detalle anterior se mantiene y el resultado lo dice en 'detalle'. Un 'upstream_error' es transitorio, también cuando la Tesorería frena la lectura por exceso de consultas: no es la clave ni un cambio del portal, y la sincronización programada lo reintenta sola. Con muchos convenios el detalle se lee por rondas: el mismo job sigue en curso entre una ronda y otra (hasta cerca de 2 horas), el webhook 'sync.succeeded' llega al final y lo que cada ronda guardó ya se puede consultar.
Entrada
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
periodo | string `^\d4-(0[1-9] | 1[0-2])$` | no |
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
{
"$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
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":{}}'{
"tool": "tgr.conexion.sincronizar",
"params": {},
"connectionId": "conn_9tKfR2mQx4Vb"
}Salida esperada (200):
{
"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
| 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 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í | El módulo sincronizado. |
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" · "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. |
results[].completo | booleano | no | true cuando esta corrida leyó todo lo que tocaba leer según las reglas de relectura; NO significa que se hayan releído las cuotas de todos los convenios ahora (una página al día no se vuelve a pedir). Para saber si las cuotas de un convenio se releyeron en esta corrida, mira su 'cuotasLeidasEn' en 'tgr.convenios_detalle.consultar'. false cuando quedaron páginas del detalle por leer: 'incompletos' dice cuántas, y las sincronizaciones siguientes las retoman solas. Un trabajo 'succeeded' con completo:false guardó las pantallas pero NO releyó todas las cuotas que tocaban. |
results[].incompletos | entero | no | Cuántas páginas del detalle (de cuotas o de comprobante) quedaron por leer en esta corrida. |
JSON Schema de salida
{
"$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 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",
"const": "convenios",
"description": "El módulo sincronizado."
},
"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",
"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"
},
"completo": {
"description": "true cuando esta corrida leyó todo lo que tocaba leer según las reglas de relectura; NO significa que se hayan releído las cuotas de todos los convenios ahora (una página al día no se vuelve a pedir). Para saber si las cuotas de un convenio se releyeron en esta corrida, mira su 'cuotasLeidasEn' en 'tgr.convenios_detalle.consultar'. false cuando quedaron páginas del detalle por leer: 'incompletos' dice cuántas, y las sincronizaciones siguientes las retoman solas. Un trabajo 'succeeded' con completo:false guardó las pantallas pero NO releyó todas las cuotas que tocaban.",
"type": "boolean"
},
"incompletos": {
"description": "Cuántas páginas del detalle (de cuotas o de comprobante) quedaron por leer en esta corrida.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"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
tgr.convenios.consultar: lee el alcanceconveniosque esta sincronización escribe.tgr.convenios_cuotas.consultar: lee el alcanceconveniosque esta sincronización escribe.tgr.convenios_detalle.consultar: lee el alcanceconveniosque esta sincronización escribe.tgr.resoluciones.consultar: lee el alcanceconveniosque esta sincronización escribe.