# Sincronizar y consultar

> En Emisso ninguna consulta pregunta en vivo al SII ni a un banco. Sincronizar encola el trabajo y responde al instante; consultar lee lo guardado. Esta página explica por qué.



Una tool `sincronizar` consulta el sistema externo, trae los datos y los persiste. Las
tools `consultar` leen lo persistido, al instante. Esta separación gobierna toda lectura de datos en
Emisso y tiene consecuencias prácticas para tu integración.

```text
sincronizar                  seguir el trabajo                 consultar
encola y devuelve jobId  ──►  esperar y revisar outcomes  ──►   leer lo persistido
```

Una llamada a `sincronizar` **no te hace esperar el login**. Encola el trabajo, lo dispara enseguida y
te devuelve un `jobId` en el acto. El trabajo contra el SII o el banco puede tardar minutos (un sync
grande del SII gasta más de 100 segundos), y ninguna request debería quedarse abierta tanto rato.

## Por qué no hay consultas en vivo [#por-qué-no-hay-consultas-en-vivo]

* **Los logins son caros y escasos.** Un login bancario tarda cerca de 90 segundos, y en BCI entrar
  corta la sesión de quien esté dentro del portal. Una consulta en vivo por cada pregunta de un agente
  dejaría al contador de tu cliente fuera del banco.
* **Los rate limits son del sistema externo, no tuyos.** Concentrar el contacto en `sincronizar` hace
  controlable cuánto y cuándo se toca el SII o el banco.
* **Tus lecturas se vuelven predecibles.** Un `consultar` responde en milisegundos siempre, sin
  depender de que el banco esté arriba a las 3 de la mañana.

<Callout type="warn" title="La regla que nunca se rompe">
  Un id `recurso.consultar` significa «lee lo ya sincronizado» en todos los sistemas, sin excepción. No
  existe, a propósito, una tool que consulte en vivo sin persistir. Y `conexion.verificar`, que sí abre
  sesión, no devuelve ningún dato de negocio: solo confirma que la credencial sigue viva.
</Callout>

## Es normal que la primera consulta vuelva vacía [#es-normal-que-la-primera-consulta-vuelva-vacía]

Una lista vacía no significa que no haya datos: puede significar que ese período aún no se
sincroniza. Antes de concluir, mira las señales:

| Señal                  | Dónde                                                                       | Qué te dice                                                                                                                                                                                                                                                  |
| ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `datosListos`          | `conexiones.estado.consultar`                                               | Si la conexión ya tiene algo que leer. Consúltalo después de conectar y antes de la primera lectura.                                                                                                                                                         |
| `sincronizacion`       | En las consultas que lo declaran, como `sii.rcv.consultar`                  | La completitud del último sync del período pedido: `sincronizadoEn`, `completo`, cuántas filas quedaron `incompletos`. Consulta el schema de cada tool.                                                                                                      |
| `sincronizacion: null` | En esas consultas                                                           | Sin `periodo` no hay un sync único que mirar. Con `periodo`, no hay evidencia de una sincronización de ese mes: no interpretes una lista vacía como ausencia de actividad.                                                                                   |
| `verificadoAl`         | `sii.documentos.consultar` y `verificados` en `conexiones.estado.consultar` | Desde cuándo lo guardado de un mes de documentos del SII coincide con lo que el SII mostraba. Un documento atrasado puede aparecer después: ver [hasta cuándo está verificado un mes](/docs/sistemas/sii#hasta-cuándo-está-verificado-un-mes-de-documentos). |

`datosListos` no prueba que haya terminado el trabajo que acabas de pedir: puede referirse a datos de
otro período o de una corrida anterior. Si necesitas datos actualizados, sigue su trabajo antes de leer.

## Quién dispara la sincronización [#quién-dispara-la-sincronización]

| Camino             | Cómo                                                                                                           | Cuándo usarlo                                                                                                                                                                                             |
| ------------------ | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Programada         | La cadencia de la conexión, que decide Emisso por conector y no se configura                                   | El caso normal, y no hay que hacer nada para que ocurra: las conexiones con sincronización habilitada y sin pausas se actualizan solas. Tus lecturas encuentran datos frescos sin que nadie llame a nada. |
| A pedido, por tool | `sistema.conexion.sincronizar` vía `execute_write`. Responde al instante con `estado: "encolado"` y el `jobId` | El camino normal para un agente o una integración: pedir datos frescos de un período puntual.                                                                                                             |
| A pedido, por REST | `POST /v1/connections/{conn}/syncs` responde `202` con `job_ids`                                               | Lo mismo, cuando prefieres el control-plane REST y quieres encolar varios períodos de una vez.                                                                                                            |

Los dos caminos a pedido encolan. La tool intenta disparar la ejecución enseguida; el endpoint de
control deja el trabajo en la cola para su procesamiento. La tool devuelve `data.jobId` con HTTP `200`;
el endpoint de control devuelve `data.job_ids` con HTTP `202`. Ninguno de esos estados HTTP certifica
que el trabajo haya terminado. Por MCP, `execute_write` devuelve la salida de la tool sin el sobre `data`.

### Rutas exactas para pedir y seguir datos [#rutas-exactas-para-pedir-y-seguir-datos]

La base REST es `https://connect.emisso.ai/api/v1`. `GET /v1/connections` lista ids, no trabajos.
Para el estado de una conexión llama a **`POST /v1/tools/conexiones.estado.consultar/execute`** con
`{"input":{"conexionId":"conn_..."}}`; muestra los cinco últimos trabajos. No existe
`GET /v1/connections/{id}/estado` ni un listado REST `GET /v1/connections/{id}/syncs`.

Para [pedir agosto y septiembre y ver su estado](/docs/operar/api-control#pedir-agosto-y-septiembre-y-ver-su-estado),
usa `POST /v1/connections/{conn}/syncs` con `{"periodos":["2026-08","2026-09"]}` y conserva todos
los `data.job_ids`. El cuerpo no lleva `input`. Cada id se sigue con `GET /v1/syncs/{id}`.
Una tool sí lleva `{"input":{...}}` y `Content-Type: application/json`. Todas las tools de un sistema
conectado exigen `X-Connect-Connection`; las de plataforma o datos abiertos, como `conexiones.*`,
`core.*`, `indicadores.*` y `echo.*`, no lo necesitan. En prueba, SII solo permite pedir los tres
meses más recientes, incluido el corriente de Chile; ajusta las fechas del ejemplo si corresponde.

El cliente no dispone de un parámetro para priorizar la cola. Si es urgente o no avanza, escríbenos
por el chat con la conexión, el período y el trabajo; lo revisamos sin prometer adelanto ni plazo.

### Cómo sabes que terminó [#cómo-sabes-que-terminó]

| Camino    | Cómo                                                                                            | Disponible en                        |
| --------- | ----------------------------------------------------------------------------------------------- | ------------------------------------ |
| Webhook   | `sync.succeeded` y `sync.failed` llegan firmados a tu endpoint, con `data.job_id`               | Starter, Pro y Max                   |
| Consulta  | `GET /v1/syncs/{jobId}` devuelve el estado y el resumen por alcance                             | Todos los planes, incluida la prueba |
| Los datos | `recurso.consultar` con el `periodo`: el campo `sincronizacion` te dice si ese período ya cerró | Todos los planes                     |

La consulta del trabajo responde con `data.job_id`, `data.status` y `data.outcomes`. En este endpoint,
los contadores dentro de `outcomes` conservan `recordsSynced`; el webhook usa `records_synced`.

| Resultado                                                           | Qué hacer                                                                                                                                                         |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queued` o `running`                                                | Espera unos segundos y vuelve a consultar el mismo trabajo. No vuelvas a encolarlo.                                                                               |
| `succeeded`                                                         | Revisa `outcomes` para los alcances pedidos. Puede contener `partial` o `failed` aunque el estado general sea exitoso.                                            |
| `partial`, o un alcance con `partial`, `failed` o `completo: false` | Hay información incompleta. Usa el detalle por alcance para diagnosticarla; no la presentes como un período cerrado.                                              |
| `failed`                                                            | Consulta `last_error` y el catálogo de errores antes de decidir si corresponde otro intento. Una caída o espera del portal no implica que debas cambiar la clave. |
| Se agotó tu tiempo de espera                                        | Conserva el identificador y continúa el seguimiento después. Terminar la espera local no cancela el trabajo.                                                      |

Revisa también el significado de un cero: un alcance puede terminar `ok` sin filas porque no había
actividad, o porque la fuente no ofrece ese dato para el período pedido. Las guías de cada sistema
explican esas diferencias.

Para el RCV del SII exige además `completo: true`, `reconMismatches: 0` y `filasDescartadas: 0` en su
`outcome`. `completo` sólo indica que no fallaron casillas: puede seguir en `true` si el detalle no
cuadra con el resumen o se descartaron filas. Si esos contadores faltan, no tienes evidencia para
cerrar el mes. La consulta `sii.rcv.consultar` no proyecta esos dos contadores; compruébalos en el trabajo.

### Si ya había una sincronización [#si-ya-había-una-sincronización]

Sólo hay una sincronización activa por conexión y período. Al pedirla por tool, `yaEnCurso: true`
indica que ya existía: sigue `jobId` si viene. Puede ser `null` cuando el trabajo ya está corriendo y
el adaptador no devuelve su identificador. En ese caso revisa la sincronización de esa conexión en
[el panel](https://connect.emisso.ai/connections); no construyas `/syncs/null` ni encoles otra para
obtener un id. Conserva el identificador si lo habías recibido en una llamada anterior.

El endpoint de control `POST /v1/connections/{conn}/syncs` conserva otra respuesta para este caso:
`409 connection_sync_in_progress`. Tampoco es motivo para crear un trabajo duplicado.

### Seguimiento desde tu código [#seguimiento-desde-tu-código]

Esta función para Node 22 recibe la salida de la tool (`data` en REST), el período y los alcances que
pediste. La clave se lee de tu variable `EMISSO_CONNECT_API_KEY` y se pasa como `apiKey`.
Hace hasta 60 consultas separadas por cinco segundos; cada petición tiene un tope de diez segundos.
Sólo devuelve el trabajo cuando los alcances pedidos terminaron `ok` y ninguno declara incompletitud.
Para `rcv`, también exige las tres señales de integridad descritas arriba.

```js
async function esperarSincronizacion(solicitud, { apiKey, periodo, alcances, maxConsultas = 60 }) {
  if (solicitud.estado !== "encolado" || !solicitud.jobId) {
    throw new Error("Sin identificador de seguimiento: revisa la sincronización de la conexión en el panel.");
  }
  if (alcances.length === 0) throw new Error("Indica los alcances que pediste.");
  const jobId = solicitud.jobId;
  for (let intento = 0; intento < maxConsultas; intento++) {
    const res = await fetch(`https://connect.emisso.ai/api/v1/syncs/${encodeURIComponent(jobId)}`, {
      method: "GET",
      headers: { Authorization: `Bearer ${apiKey}` },
      signal: AbortSignal.timeout(10_000),
    });
    const { data, error } = await res.json();
    if (!res.ok) {
      throw new Error(`${error?.code ?? res.status}: ${error?.suggested_fix ?? error?.message ?? "Consulta rechazada"} (${error?.request_id ?? jobId})`);
    }
    if (data.job_id !== jobId || data.periodo !== periodo) {
      throw new Error(`El trabajo no corresponde al período solicitado: ${jobId}.`);
    }
    if (data.status === "queued" || data.status === "running") {
      if (intento + 1 < maxConsultas) await new Promise((resolve) => setTimeout(resolve, 5_000));
      continue;
    }
    if (data.status !== "succeeded") {
      throw new Error(`Trabajo ${jobId}: ${data.status}; revisa last_error=${data.last_error ?? "sin código"} y outcomes en el panel.`);
    }
    const completos = alcances.every((alcance) => data.outcomes?.some(
      (r) => r.alcance === alcance && r.status === "ok" && r.completo !== false
        && (alcance !== "rcv" || (r.completo === true && r.reconMismatches === 0 && r.filasDescartadas === 0)),
    ));
    if (!completos) {
      throw new Error(`Trabajo ${jobId}: faltan alcances completos. Revisa outcomes antes de usar los datos como completos.`);
    }
    return data;
  }
  throw new Error(`Se agotó la espera local. Conserva ${jobId} y sigue consultándolo; no vuelvas a encolar.`);
}
```

Para el RCV del tutorial, pasa `periodo: "2026-07"` y `alcances: ["rcv"]`. Si la función devuelve el
trabajo, consulta `sii.rcv.consultar` para esa conexión y período y recorre sus páginas. Si lanza un
error, muestra el motivo antes de continuar. Un error de red o timeout también detiene la función:
conserva la solicitud y vuelve a seguir el mismo `jobId`, sin repetir el POST de sincronización.

## Leer el saldo de una cuenta [#leer-el-saldo-de-una-cuenta]

En los bancos, `saldos.consultar` trae una fila por cuenta, moneda y día, y cada fila indica su
`numeroCuenta` y su moneda. Volver a sincronizar el mismo día actualiza la fila de ese día. El orden es
siempre el mismo: del día más reciente al más antiguo y, dentro de cada día, por número de cuenta y luego
por moneda.

Para quedarte con el saldo más reciente de una cuenta, filtra por `numeroCuenta` y toma la primera fila de
la moneda que buscas. Sin ese filtro, la primera fila es la cuenta de menor número, que puede no ser la que
necesitas: con una cuenta en pesos y otra en dólares, el primer elemento de la lista no basta para
distinguirlas.

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

* [Conecta tu primera empresa](/docs/empezar/conectar): el recorrido completo, de punta a punta.
* [Guía del SII](/docs/sistemas/sii): qué trae cada alcance y cada cuánto conviene sincronizar.
* [Planos, scopes y alcances](/docs/conceptos/planos): el modelo completo detrás de esta regla.


---

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/conceptos/sincronizar-consultar.
