Sincronizar y consultar
En Connect 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 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)
encola el trabajo y responde ──► responde al instante
ya con el jobId desde lo ya guardado
abre la sesión real en cola barata, paginada, ilimitadaUna 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
- 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 | La cadencia de la conexión, que decide Connect por conector y no se configura | El caso normal, y no hay que hacer nada para que ocurra: toda conexión activa sincroniza sola. 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 hacen lo mismo y responden igual de rápido: dejan la fila durable, adelantan su ejecución y te devuelven el identificador.
Cómo sabes que terminó
| Camino | Cómo | Disponible en |
|---|---|---|
| Webhook | sync.succeeded y sync.failed llegan firmados a tu endpoint, con el jobId | 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 |
Dos syncs del mismo período no se pisan: sólo hay una sincronización activa por conexión y período. Si
pides una que ya está andando, la respuesta trae yaEnCurso: true y el jobId de la que corre: no es
un error ni un rechazo, es el mismo trabajo que ya pediste.
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.