# Tesorería General de la República

> Los convenios de pago de una empresa con la Tesorería: resoluciones, estado de pago, cuotas pagadas y por pagar, y deudas acogidas, con la Clave Tributaria del SII.



Con la Clave Tributaria del SII de la empresa, `tgr` sincroniza las pantallas de convenios de la Tesorería General de la República hacia el plano persistido de Emisso, y cuatro tools de consulta las leen de ahí sin volver a consultar la Tesorería. El `conn_…` de la conexión dice qué empresa lees y viaja en toda llamada (en REST, el header `X-Connect-Connection`).

## Qué necesitas para conectar [#qué-necesitas-para-conectar]

En el [enlace de conexión](/docs/empezar/conectar) la persona entrega la **Clave Tributaria de la empresa**, la misma con que entra a sii.cl:

| Campo             | Qué es                                          |
| ----------------- | ----------------------------------------------- |
| RUT de la empresa | El contribuyente cuyos convenios se van a leer. |
| Clave tributaria  | La clave del SII de ese RUT.                    |

El portal de la Tesorería también acepta Clave Tesorería y ClaveÚnica; esta conexión usa solo la Clave Tributaria. El acceso solo lee: nunca paga, pacta ni modifica un convenio, y desde el dashboard se revoca en el acto.

## El alcance [#el-alcance]

Hay un alcance, `convenios`, que trae tres listados de la Tesorería y el detalle de cada convenio. Cada uno tiene su tool:

| Sección de la Tesorería                                            | Qué trae                                                                                                                                             | Tool                              |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| Estado de pago de convenio                                         | Los convenios activos, con tipo, número de cuotas y fecha de término                                                                                 | `tgr.convenios.consultar`         |
| Cuotas convenios vigentes                                          | Los convenios activos y las propuestas aceptadas, con su número de cuotas                                                                            | `tgr.convenios_cuotas.consultar`  |
| Comprobante de resolución                                          | Las resoluciones que otorgaron cada beneficio, con fecha de resolución y de activación                                                               | `tgr.resoluciones.consultar`      |
| El detalle de cada convenio (su comprobante y su página de cuotas) | Cada cuota con su vencimiento, monto y si está pagada; cuántas van pagadas; la próxima por pagar; el total; y las deudas acogidas con su condonación | `tgr.convenios_detalle.consultar` |

El **número de resolución** identifica al convenio en las tres pantallas y en su detalle: es la llave para cruzarlas. Las cuatro tools aceptan el filtro `numeroResolucion`.

## Sincronizar [#sincronizar]

```bash
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":{}}'
```

Respuesta:

```json
{
  "data": { "periodo": "2026-10", "estado": "encolado", "jobId": "sjb_3h5j7k9m1n2p4q6r8s0t1", "yaEnCurso": false },
  "meta": { "request_id": "req_...", "tool_id": "tgr.conexion.sincronizar", "plane": "read" }
}
```

La llamada vuelve al instante con `estado: "encolado"` y un `jobId`; el resultado de la corrida llega por [webhook](/docs/operar/webhooks) o en el estado de la conexión. Emisso además sincroniza solo una vez al día, y una sincronización pedida así relee las cuotas que lleven más de 30 minutos sin leerse: ver [Pedir una lectura fresca de las cuotas](#pedir-una-lectura-fresca-de-las-cuotas).

Las pantallas son el **estado actual** de la empresa ante la Tesorería, no un historial por mes: `periodo` es opcional y solo organiza la ejecución. Un período que no es el corriente no vuelve a consultar el portal.

## Consultar [#consultar]

```bash
curl -X POST https://connect.emisso.ai/api/v1/tools/tgr.convenios.consultar/execute \
  -H "Authorization: Bearer connect_sk_..." \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{}}'
```

Respuesta de una empresa sin convenios activos:

```json
{
  "data": { "convenios": [], "pantallaLeidaEn": "2026-10-02T14:02:11.000Z", "cursor": null },
  "meta": { "request_id": "req_...", "tool_id": "tgr.convenios.consultar", "plane": "action" }
}
```

Cada fila trae los campos derivados (fechas en `AAAA-MM-DD`, cuotas como número) y, en `celdas`, el texto original de la Tesorería por columna. Si un campo derivado viene en `null`, el texto está ahí.

### El detalle: cuotas, pagos y deudas [#el-detalle-cuotas-pagos-y-deudas]

`tgr.convenios_detalle.consultar` responde cuánto se debe y cuándo vence lo siguiente. Filtra por `numeroResolucion` para ver un convenio:

```bash
curl -X POST https://connect.emisso.ai/api/v1/tools/tgr.convenios_detalle.consultar/execute \
  -H "Authorization: Bearer connect_sk_..." \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"numeroResolucion":"4455667"}}'
```

Respuesta (datos ficticios, con las cuotas recortadas):

```json
{
  "data": {
    "convenios": [{
      "numeroResolucion": "4455667",
      "tipoConvenio": "Ley 20.780 Fiscal",
      "tipoPago": "CONVENIO CON CONDONACION",
      "numeroCuotas": 3,
      "cuotasPagadas": 1,
      "montoCuotaContado": 250000,
      "totalAPagar": 600000,
      "proximaCuota": { "numero": 2, "fechaVencimiento": "2026-04-30", "monto": 175000 },
      "cuotas": [
        { "numero": 1, "fechaVencimiento": "2026-03-31", "monto": 250000, "tipo": "Cuota contado", "pagada": true },
        { "numero": 2, "fechaVencimiento": "2026-04-30", "monto": 175000, "tipo": "Cuota normal", "pagada": false },
        { "numero": 3, "fechaVencimiento": "2026-05-31", "monto": null, "tipo": "Cuota de ajuste", "pagada": false }
      ],
      "deudas": [{ "tipo": "FISCAL", "formulario": "22", "folio": "998877665", "condonacionIntereses": 40, "condonacionMultas": 40, "totalAPagar": 600000 }],
      "observadoEn": "2026-10-04T14:02:11.000Z",
      "cuotasLeidasEn": "2026-10-04T14:02:11.000Z",
      "comprobanteLeidoEn": "2026-10-04T14:01:40.000Z"
    }],
    "pantallaLeidaEn": "2026-10-04T14:02:11.000Z",
    "cursor": null
  },
  "meta": { "request_id": "req_...", "tool_id": "tgr.convenios_detalle.consultar", "plane": "action" }
}
```

Los montos son pesos enteros. `cuotasPagadas` cuenta las cuotas que la página de cuotas de la Tesorería marca como pagadas. `proximaCuota` es la primera que la Tesorería no registra pagada; Emisso no la marca como vencida, porque eso depende de la fecha en que leas.

Cada convenio dice de cuándo es cada parte: `cuotasLeidasEn` para las cuotas, `pagada`, `cuotasPagadas` y `proximaCuota`, y `comprobanteLeidoEn` para `deudas`, `totalAPagar` y `montoCuotaContado`. Al informar un dato, di de qué fecha es. En `null`, no se conoce la fecha de esa lectura: la página todavía no se ha leído, o la fila se guardó antes de que se anotaran las fechas. Si trae datos, son reales pero de fecha desconocida: dilo así, y no inventes los valores que vengan en `null`.

## Antes de depender de los datos [#antes-de-depender-de-los-datos]

### Una lista vacía tiene dos lecturas, y `pantallaLeidaEn` las separa [#una-lista-vacía-tiene-dos-lecturas-y-pantallaleidaen-las-separa]

Las cuatro tools devuelven `pantallaLeidaEn`: cuándo se leyó esa pantalla (o el detalle) por última vez.

* **Con fecha y sin filas**: la Tesorería mostró la pantalla vacía. La empresa no tiene convenios ahí.
* **En `null`**: la pantalla todavía no se ha leído. Sincroniza antes de concluir nada.

### Lo que sale de la pantalla deja de aparecer [#lo-que-sale-de-la-pantalla-deja-de-aparecer]

Cada sincronización reemplaza lo que se ve de cada pantalla. Un convenio que terminó y ya no aparece en el portal deja de salir en la consulta en la sincronización siguiente; `observadoEn` dice cuándo se vio cada fila por última vez. Lo mismo vale para su detalle: `tgr.convenios_detalle.consultar` deja de devolver un convenio cuando ninguna de las tres pantallas lo muestra.

### La cuota de ajuste muestra su monto cuando la Tesorería la liquida [#la-cuota-de-ajuste-muestra-su-monto-cuando-la-tesorería-la-liquida]

La última cuota de un convenio se calcula después de pagar la penúltima. Mientras la Tesorería no la liquida, `tgr.convenios_detalle.consultar` la devuelve con `monto: null`, aunque el portal pinte un 0 en una de sus pantallas: ese cero no es lo que se debe. Cuando la Tesorería la liquida, la página de cuotas trae su monto y la cuota sale con ese valor. Un detalle que el portal no enlazó desde una fila deja su parte en `null` (por ejemplo, `pagada` y `cuotasPagadas` sin la pantalla de cuotas).

### Una fila que Emisso no reconoce detiene la sincronización [#una-fila-que-emisso-no-reconoce-detiene-la-sincronización]

Si el portal cambia las columnas de una de las tres pantallas o publica una fila con otra forma, la sincronización falla con `upstream_unexpected_response` en vez de guardar una lectura parcial. Nunca vas a recibir una lista vacía que en realidad era un error de lectura.

### El detalle puede quedar atrás de las pantallas [#el-detalle-puede-quedar-atrás-de-las-pantallas]

El detalle de cada convenio (sus cuotas y su comprobante) se completa en rondas, después de los tres listados. Si queda detalle por traer, la sincronización continúa sola unos 15 minutos después, hasta completarlo (hasta 8 rondas: el detalle de unos 20 convenios). Con 15 convenios, la primera lectura completa del detalle toma unas seis rondas, algo más de 1 hora.

En cada ronda Emisso empieza por lo que nunca se leyó: primero las cuotas y después los comprobantes. Cuando ya está todo leído, repasa lo que pudo cambiar: las cuotas de un convenio cuya próxima cuota vence en los próximos 5 días o venció en los últimos 5, las que llevan 7 días o más sin leerse y los comprobantes que llevan 90 días o más. Dentro de esa ventana se releen una vez al día, incluido el día del vencimiento, para detectar también pagos anticipados; una página ya leída hoy en Santiago no se repite en las rondas siguientes. Fuera de esa ventana las cuotas se releen cada 7 días. Las sincronizaciones diarias hacen ese repaso.

Mientras el detalle se completa, el resultado del trabajo lo dice: la fila `convenios` trae `completo: false` e `incompletos` con cuántas páginas (de cuotas o de comprobante) quedaron por leer, y en `GET /v1/syncs/{id}` un `motivo` con su `detalle` explican la causa cuando la Tesorería cortó la lectura; es transitorio.

Con muchos convenios, el mismo job queda 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 mientras tanto. Mientras `incompletos` sea mayor que cero, esa ronda guardó páginas y quedan otras por leer: la sincronización sigue sola unos minutos después o, si ya hizo sus 8 rondas, en la próxima programada. No es un error. Por lo mismo, un trabajo `succeeded` no garantiza que se hayan releído todas las cuotas: la fila `convenios` de sus `outcomes` (también en el webhook y en `conexiones.estado.consultar`) lo declara con `completo` e `incompletos`. Y `completo: true` significa que se leyó todo lo que **tocaba** leer según las reglas de relectura, no que se hayan releído las cuotas de todos los convenios en esa corrida: una página al día no se vuelve a pedir. Si un convenio te importa, mira su `cuotasLeidasEn`: esa es la fecha de sus cuotas.

Cada convenio conserva la última lectura de cada una de sus páginas y la fecha de cada una (`cuotasLeidasEn` y `comprobanteLeidoEn`). Una ronda que no alcanza a leer una página, o un convenio entero, no borra lo que ya tenías: el convenio sigue con su última lectura, y la página que sí se leyó se combina con la que había. Por eso un convenio puede traer las cuotas de hoy con el total del comprobante de hace dos meses: el comprobante cambia poco, y la fecha te dice cuánto confiar en cada dato. Un convenio cuyas páginas todavía no se han leído nunca no aparece en el detalle, y uno que tiene solo las cuotas trae `deudas` vacío y `totalAPagar` y `montoCuotaContado` en `null`: eso no significa que no haya deudas.

Si no se alcanza a leer ninguna página, o una página no tiene la forma conocida, la sincronización termina igual con las tres pantallas guardadas, no toca el detalle que ya había y lo dice en el resultado: `completo: false` y, en `GET /v1/syncs/{id}`, el `motivo` con su `detalle`. El `pantallaLeidaEn` de `tgr.convenios_detalle.consultar` dice cuándo una sincronización leyó páginas del detalle por última vez (puede haber sido solo de algunos convenios, y una sincronización que no leyó ninguna página no lo mueve); para saber qué tan al día está un convenio, mira sus dos fechas (`cuotasLeidasEn` y `comprobanteLeidoEn`), no esa. Un `pantallaLeidaEn` en `null` aunque las pantallas ya traigan convenios significa que el detalle todavía no se leyó, no que no haya deuda. Un convenio que sale de las pantallas y vuelve queda sin detalle hasta que se lea de nuevo alguna de sus páginas.

### Pedir una lectura fresca de las cuotas [#pedir-una-lectura-fresca-de-las-cuotas]

Una sincronización que pides tú (por la API, por MCP o con el botón del panel) hace algo más que la programada: relee las cuotas de cada convenio que no se hayan leído en los últimos 30 minutos, primero las de los convenios con vencimiento en la ventana de ±5 días y después las demás, de la más antigua a la más reciente, con el mismo tope de páginas por ronda. Los comprobantes conservan su regla de 90 días. Así, si pagas una cuota y quieres verla reflejada el mismo día, pide una sincronización: si la Tesorería ya registra el pago, la siguiente lectura lo trae. Una página leída hace menos de 30 minutos no se repite, y sigue vigente el límite de una sincronización pedida cada 10 minutos por conexión; si la Tesorería aún muestra la cuota como pendiente, vuelve a intentarlo más tarde.

## Errores que vas a ver [#errores-que-vas-a-ver]

| Código                               | Qué significa                                                                                                                                                   | Qué hacer                                                                                                                                   |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `428 connection_credential_required` | El SII rechazó la Clave Tributaria: incorrecta, bloqueada, caducada o pendiente de actualizar. El motivo dice cuál: `credencial_rechazada` o `clave_bloqueada`. | Emite un enlace de reconexión y pide la clave de nuevo. No reintentes con la anterior: cada intento fallido cuenta para el bloqueo del SII. |
| `428 connector_onboarding_required`  | El SII pide que una persona haga algo antes de seguir, como comprobar su identidad.                                                                             | Que la persona entre una vez a sii.cl con esa clave y luego vuelve a sincronizar.                                                           |
| `409 connection_identity_mismatch`   | La Tesorería abrió los convenios de otro RUT.                                                                                                                   | Revisa que la clave sea la de la empresa conectada.                                                                                         |
| `502 upstream_error`                 | La Tesorería o el SII fallaron de forma transitoria, o la Tesorería frenó la lectura por exceso de consultas (motivo `acceso_no_disponible`).                   | Reintenta más tarde. La sincronización programada lo reintenta sola.                                                                        |
| `502 upstream_unexpected_response`   | La Tesorería cambió el formato de sus datos.                                                                                                                    | Avísanos: hay que actualizar el conector.                                                                                                   |

El envelope de cada código está en el [catálogo de errores](/docs/operar/errores).

## Próximos pasos [#próximos-pasos]

* Las seis tools, con contrato completo: [referencia de `tgr`](/docs/referencia/tgr).
* La separación entre escribir la caché y leerla: [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar).


---

Esta página es parte de la documentación de Emisso. El índice completo, con cada página y su descripción, está en https://connect.emisso.ai/llms.txt. Esta misma página en HTML: https://connect.emisso.ai/docs/sistemas/tgr.
