Cómo funciona

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

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

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ñalDóndeQué te dice
datosListosconexiones.estado.consultarSi la conexión ya tiene algo que leer. Consúltalo después de conectar y antes de la primera lectura.
sincronizacionEn las consultas que lo declaran, como sii.rcv.consultarLa completitud del último sync del período pedido: sincronizadoEn, completo, cuántas filas quedaron incompletos. Consulta el schema de cada tool.
sincronizacion: nullEn esas consultasSin 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.
verificadoAlsii.documentos.consultar y verificados en conexiones.estado.consultarDesde 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

CaminoCómoCuándo usarlo
ProgramadaLa cadencia de la conexión, que decide Emisso por conector y no se configuraEl 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 toolsistema.conexion.sincronizar vía execute_write. Responde al instante con estado: "encolado" y el jobIdEl camino normal para un agente o una integración: pedir datos frescos de un período puntual.
A pedido, por RESTPOST /v1/connections/{conn}/syncs responde 202 con job_idsLo 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ó

CaminoCómoDisponible en
Webhooksync.succeeded y sync.failed llegan firmados a tu endpoint, con data.job_idStarter, Pro y Max
ConsultaGET /v1/syncs/{jobId} devuelve el estado y el resumen por alcanceTodos los planes, incluida la prueba
Los datosrecurso.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.

ResultadoQué hacer
queued o runningEspera unos segundos y vuelve a consultar el mismo trabajo. No vuelvas a encolarlo.
succeededRevisa 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: falseHay información incompleta. Usa el detalle por alcance para diagnosticarla; no la presentes como un período cerrado.
failedConsulta 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 esperaConserva 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

En esta página