# Consultar con el SDK

> Instala @emisso/connect, guarda tu clave y tu conexión en un .env y lee el registro de ventas del SII de una empresa con un programa corto. Con demo animada del editor y la terminal.



<CompartirGuia />

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.

<RecorridoDemo guion="sdk" />

## Antes de empezar [#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](https://connect.emisso.ai/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](/docs/como-conectar/sii). Después Connect sincroniza solo.

## Los pasos [#los-pasos]

### 1. Instala el SDK [#1-instala-el-sdk]

En la carpeta de tu proyecto:

```bash
npm install @emisso/connect
```

### 2. Guarda tu clave en un archivo .env [#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 [#3-agrega-la-conexión-de-la-empresa]

La conexión es la empresa. Copia su ID, el que empieza con `conn_`, desde
[Conexiones](https://connect.emisso.ai/connections) 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:

```bash
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 [#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.

```js
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 [#5-córrelo]

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

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

```text
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](/docs/referencia) tiene cada una con sus campos y un ejemplo.

## Si algo falla [#si-algo-falla]

<Callout type="warn" title="«createClient requires apiKey» o «unauthorized»">
  El primero dice que Node no leyó la clave: corre el programa con `--env-file=.env` y revisa que en el `.env`
  se llame `EMISSO_CONNECT_API_KEY`. El segundo, que la clave llegó y no sirve: revisa que la copiaste
  completa, o crea otra. Si se publicó por error, rótala en [API keys](https://connect.emisso.ai/api-keys).
</Callout>

<Callout type="info" title="«validation_error» que pide el connectionId">
  El programa no encontró `EMISSO_CONNECTION_ID` en el `.env`. Revisa el nombre y que el ID empiece con
  `conn_`.
</Callout>

<Callout type="info" title="«Ese mes todavía no está sincronizado en Connect»">
  La conexión no tiene cargado ese mes. Revisa en el panel qué meses tiene la conexión antes de concluir que
  no hubo ventas.
</Callout>

<Callout type="info" title="No imprime nada">
  El mes está cargado y no tiene facturas ni notas de venta. Las boletas (39) y los comprobantes de pago con
  tarjeta (48) no vienen documento por documento: están en `sii.rcv_totales.consultar`.
</Callout>

La versión del SDK publicada en npm ya trae `sii.rcv.consultar`. Para saber qué cubre cada versión, mira
[SDK de TypeScript](/docs/sdk).

## Siguiente paso [#siguiente-paso]

* [SDK de TypeScript](/docs/sdk): las opciones del cliente, los errores, los reintentos y la idempotencia.
* [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar): por qué leer datos reales son dos pasos.
* [Consultar con la API](/docs/como-consultar/api): el mismo programa sin el SDK, con `fetch`.
* [Consultar con Claude](/docs/como-consultar/claude): la misma consulta, preguntándole a un agente.