Consultar con el SDK

Con el SDK, tu propio programa lee lo que Connect sincronizó: instalas un paquete, guardas tu clave de API y el ID de la conexión de tu empresa, y llamas a la consulta que necesitas. En esta guía, las ventas de un mes según el registro del SII.

La demo de abajo escribe el programa completo y lo corre, con datos de ejemplo y la clave enmascarada. Puedes pausarla, verla otra vez o tomar el control con «Probarlo yo» y correr tú los comandos. No consulta nada y no sale de tu navegador.

Antes de empezar

• Node 22 o más nuevo. Revisa tu versión con node --version.
• Una clave de API. Créala en API keys; el perfil «Solo lectura» alcanza. El texto de la clave se muestra una sola vez.
• Una empresa conectada con datos. Si todavía no la conectas, sigue la guía del SII. Después Connect sincroniza solo.

Los pasos

1. Instala el SDK

En la carpeta de tu proyecto:

npm install @emisso/connect

2. Guarda tu clave en un archivo .env

Crea un archivo .env en la misma carpeta y pega tu clave en EMISSO_CONNECT_API_KEY. Agrega .env a tu .gitignore: con esa clave se leen todas las empresas conectadas de tu organización.

3. Agrega la conexión de la empresa

La conexión es la empresa. Copia su ID, el que empieza con conn_, desde Conexiones en el panel: está en la fila de la conexión y en su detalle. Pégalo en EMISSO_CONNECTION_ID. El .env queda así, con tus valores en lugar de los puntos:

EMISSO_CONNECT_API_KEY=connect_sk_••••••••
EMISSO_CONNECTION_ID=conn_••••••••

El programa no busca la conexión por su nombre: Connect nombra cada conexión como su sistema («SII», «SII 2»), no como la empresa, así que el ID es la forma segura de elegirla.

4. Escribe el programa

Crea ventas.mjs. Llama a sii.rcv.consultar con el mes y la conexión, y lee lo que Connect ya sincronizó, sin entrar al SII. Pide página por página hasta que cursor vuelve en null, y si sincronizacion viene en null se detiene: ese mes no está cargado, que no es lo mismo que un mes sin ventas.

import { createClient } from "@emisso/connect";

const connect = createClient({ apiKey: process.env.EMISSO_CONNECT_API_KEY });
// La conexión es la empresa: su ID está en Conexiones, en el panel.
const connectionId = process.env.EMISSO_CONNECTION_ID;

// Las ventas de julio de 2026, ya sincronizadas, página por página.
const pesos = new Intl.NumberFormat("es-CL", {
  style: "currency",
  currency: "CLP",
});
let cursor;
do {
  const pagina = await connect.tools.sii.rcv.consultar(
    { periodo: "2026-07", perspectiva: "ventas", cursor },
    { connectionId },
  );
  // sincronizacion en null: ese mes no está cargado, no es un mes sin ventas.
  if (pagina.sincronizacion === null) {
    throw new Error("Ese mes todavía no está sincronizado en Connect.");
  }
  for (const doc of pagina.documentos) {
    const monto = pesos.format(doc.montoTotal);
    console.log(`${doc.razonSocial} · folio ${doc.folio} · ${monto}`);
  }
  cursor = pagina.cursor;
} while (cursor);

5. Córrelo

--env-file hace que Node lea el .env sin instalar nada más:

node --env-file=.env ventas.mjs

Constructora Los Robles Ltda · folio 4712 · $1.487.500
Ferretería El Volcán SpA · folio 4718 · $571.200

Para leer otro mes, cambia periodo. Para otro dato, cambia la herramienta: la referencia tiene cada una con sus campos y un ejemplo.

Si algo falla

La versión del SDK publicada en npm ya trae sii.rcv.consultar. Para saber qué cubre cada versión, mira SDK de TypeScript.

Siguiente paso

• SDK de TypeScript: las opciones del cliente, los errores, los reintentos y la idempotencia.
• Sincronizar y consultar: por qué leer datos reales son dos pasos.
• Consultar con la API: el mismo programa sin el SDK, con fetch.
• Consultar con Claude: la misma consulta, preguntándole a un agente.