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.
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, ilimitadaPor 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
sincronizarhace controlable cuánto y cuándo se toca el SII o el banco. - Tus lecturas se vuelven predecibles. Un
consultarresponde en milisegundos siempre, sin depender de que el banco esté arriba a las 3 de la mañana.
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.
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
| 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
- Conecta tu primera empresa: el recorrido completo, de punta a punta.
- Guía del SII: qué trae cada alcance y cada cuánto conviene sincronizar.
- Planos, scopes y alcances: el modelo completo detrás de esta regla.