Consultar con la API

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.

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

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

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.

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

--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 en la dirección: la referencia tiene cada una con sus campos y un ejemplo.

La misma llamada con curl

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

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"}}'

{
  "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 los lista todos. meta.request_id identifica la llamada en la bitácora.

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.

Siguiente paso

• Tu primera llamada: la UF de hoy por la API, sin conectar nada.
• 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: el mismo programa con el cliente tipado.