# Sincronizar y consultar

> En Connect ninguna consulta pregunta en vivo al SII ni a un banco. Leer datos reales son dos pasos, y esta página explica por qué.



Una tool `sincronizar` abre la sesión contra 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
Connect y tiene consecuencias prácticas para tu integración.

```text
sincronizar (escribe)                    consultar (lee)
un login real, un logout      ──►        responde al instante
trae y guarda los alcances               desde lo ya guardado
tarda lo que tarde el sistema            barata, paginada, ilimitada
```

## 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 cada respuesta de `consultar` | La completitud del último sync del período pedido: `sincronizadoEn`, `completo`, cuántas filas quedaron `incompletos`.                                                                                                         |
| `sincronizacion: null` | en cada respuesta de `consultar` | Dos causas, y ninguna invalida las filas devueltas: (a) no filtraste por `periodo`, así que no hay un sync único al que mirar; (b) ese período nunca se sincronizó. Un `null` junto a una lista con documentos es siempre (a). |

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

| Camino              | Cómo                                                                                                                                   | Cuándo usarlo                                                                             |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Programada          | `cadencia` de la conexión: `daily`, `12h`, `6h` u `off`                                                                                | El caso normal. Tus lecturas siempre encuentran datos frescos sin que nadie llame a nada. |
| A pedido, en línea  | `sistema.conexion.sincronizar` vía `execute`                                                                                           | Cuando el llamador quiere esperar el resultado (un agente cerrando un mes, por ejemplo).  |
| A pedido, asíncrona | `POST /v1/connections/{conn}/syncs` responde `202` con `job_ids`; el resultado llega por los webhooks `sync.succeeded` y `sync.failed` | Backends que no quieren mantener una request abierta un minuto.                           |

Dos syncs del mismo período no se pisan: hay un candado por conexión, y el segundo recibe
`connection_sync_in_progress` (409, reintentable). Basta esperar al primero.

## 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.