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.
sincronizar seguir el trabajo consultar
encola y devuelve jobId ──► esperar y revisar outcomes ──► leer lo persistidoUna 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 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. |
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
| 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
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,
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ó
| 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
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; 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
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.
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
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
- 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.