# Consultar con la API

> Lee el registro de ventas del SII de una empresa con una llamada HTTP y tu clave de API, sin instalar nada. Con demo animada del editor y la terminal, y la misma llamada con curl.



<CompartirGuia />

La API de Connect es HTTP: una llamada `POST` por herramienta, con tu clave de API y el ID de la conexión de
la empresa. No hay nada que instalar y sirve desde cualquier lenguaje: `fetch` en JavaScript, `requests` en
Python, `UrlFetchApp` en Apps Script. En esta guía, un programa en Node lee 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 correrlo tú. No consulta nada y no
sale de tu navegador.

<RecorridoDemo guion="api" />

## Antes de empezar [#antes-de-empezar]

* **Node 22 o más nuevo**, que ya trae `fetch`. 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. Guarda tu clave en un archivo .env [#1-guarda-tu-clave-en-un-archivo-env]

Crea una carpeta para tu proyecto y, dentro, un archivo `.env` con 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.

### 2. Agrega la conexión de la empresa [#2-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_••••••••
```

### 3. Escribe el programa [#3-escribe-el-programa]

Crea `ventas.mjs`. Cada herramienta tiene su dirección,
`POST https://connect.emisso.ai/api/v1/tools/<herramienta>/execute`: la clave va en `Authorization`, la
conexión en la cabecera `X-Connect-Connection` y los argumentos en el cuerpo, dentro de `input`. La
respuesta trae los datos en `data`, o el problema en `error`.

El programa 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
const API = "https://connect.emisso.ai/api/v1/tools";
// La conexión es la empresa: su ID está en Conexiones, en el panel.
const headers = {
  Authorization: `Bearer ${process.env.EMISSO_CONNECT_API_KEY}`,
  "X-Connect-Connection": process.env.EMISSO_CONNECTION_ID,
  "Content-Type": "application/json",
};

// 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 input = { periodo: "2026-07", perspectiva: "ventas", cursor };
  const res = await fetch(`${API}/sii.rcv.consultar/execute`, {
    method: "POST",
    headers,
    body: JSON.stringify({ input }),
  });
  const { data, error } = await res.json();
  if (error) throw new Error(JSON.stringify(error));
  // sincronizacion en null: ese mes no está cargado, no es un mes sin ventas.
  if (data.sincronizacion === null) {
    throw new Error("Ese mes todavía no está sincronizado en Connect.");
  }
  for (const doc of data.documentos) {
    const monto = pesos.format(doc.montoTotal);
    console.log(`${doc.razonSocial} · folio ${doc.folio} · ${monto}`);
  }
  cursor = data.cursor;
} while (cursor);
```

### 4. Córrelo [#4-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 en la dirección: la
[referencia](/docs/referencia) tiene cada una con sus campos y un ejemplo.

## La misma llamada con curl [#la-misma-llamada-con-curl]

Para probarla desde la terminal, sin programa. Reemplaza los puntos por tu clave y tu conexión:

```bash
curl -X POST https://connect.emisso.ai/api/v1/tools/sii.rcv.consultar/execute \
  -H "Authorization: Bearer connect_sk_••••••••" \
  -H "X-Connect-Connection: conn_••••••••" \
  -H "Content-Type: application/json" \
  -d '{"input":{"periodo":"2026-07","perspectiva":"ventas"}}'
```

```json
{
  "data": {
    "documentos": [
      { "tipoDte": 33, "folio": "4712", "razonSocial": "Constructora Los Robles Ltda", "montoTotal": 1487500 },
      { "tipoDte": 33, "folio": "4718", "razonSocial": "Ferretería El Volcán SpA", "montoTotal": 571200 }
    ],
    "cursor": null,
    "sincronizacion": { "sincronizadoEn": "2026-08-06T03:15:42.000Z", "completo": true }
  },
  "meta": { "request_id": "req_…", "tool_id": "sii.rcv.consultar", "plane": "action" }
}
```

Recortado: cada documento trae más campos, y [la referencia de esta herramienta](/docs/referencia/sii/rcv-consultar)
los lista todos. `meta.request_id` identifica la llamada en la [bitácora](https://connect.emisso.ai/bitacora).

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

Todo error llega como `{"error": {"code", "message", "suggested_fix", "request_id"}}`. Sigue el
`suggested_fix`; si no lo reconoces, el `request_id` es lo primero que pide soporte.

<Callout type="warn" title="«unauthorized»">
  La clave no llegó o no sirve. Revisa que corras el programa con `--env-file=.env` y que en el `.env` se llame
  `EMISSO_CONNECT_API_KEY`. Si se publicó por error, rótala en [API keys](https://connect.emisso.ai/api-keys).
</Callout>

<Callout type="info" title="Un error que menciona la conexión">
  Revisa `EMISSO_CONNECTION_ID` en el `.env`: tiene que ser el ID que empieza con `conn_`, de una conexión de
  tu organización.
</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>

## Siguiente paso [#siguiente-paso]

* [Tu primera llamada](/docs/empezar/primera-llamada): la UF de hoy por la API, sin conectar nada.
* [Con tu asistente de IA](/docs/empezar/con-tu-asistente-de-ia): el texto para que tu asistente escriba
  este código por ti, en el lenguaje que uses.
* [Consultar con el SDK](/docs/como-consultar/sdk): el mismo programa con el cliente tipado.