Conecta tu primera empresa

De cero a leer el Registro de Compra-Venta de un cliente real, con un enlace de un solo uso, una sincronización y una consulta.

En este recorrido tu organización conecta a Comercial Aurora SpA (77.123.456-9) al SII: creas un enlace, la persona entrega su clave tributaria en una página de Connect, sincronizas un período y lees el resultado. Toma cerca de 10 minutos más el login del SII.

Antes de empezar

Tu API key connect_sk_… con los scopes conexiones:write y sii:read (connect.emisso.ai/api-keys).
La clave tributaria la entrega tu cliente, no tú. No la pidas por correo ni la pegues en tu código: para eso existe el enlace.

1. Crea el enlace de conexión

curl

curl -X POST https://connect.emisso.ai/api/v1/tools/conexiones.enlace.crear/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"input": {"sistema": "sii"}}'

Salida esperada (200, campo data):

{
  "url": "https://connect.emisso.ai/c/mYw2kQ81xR4tPnZs",
  "dominio": "connect.emisso.ai",
  "sistema": "sii",
  "sistemaNombre": "Servicio de Impuestos Internos",
  "modo": "crear",
  "expiraEn": "2026-08-07T15:32:11.000Z",
  "intentosMaximos": 5,
  "advertencia": "Este enlace pide credenciales de acceso al sistema. Muéstralo siempre con su dominio completo y di quién lo pidió y para qué. No lo presentes como un aviso del banco ni del SII."
}

SDK TypeScript

const enlace = await connect.tools.conexiones.enlace.crear({ sistema: "sii" });
// enlace.url: compártela con tu cliente. enlace.expiraEn: cuándo vence.

MCP

{ "tool": "conexiones.enlace.crear", "params": { "sistema": "sii" } }

Cómo presentar el enlace

Siempre con su dominio completo visible, y explicando quién lo pidió y para qué. Nunca lo presentes como un aviso del banco ni del SII: esa es exactamente la forma de un phishing, y tu cliente hace bien en desconfiar. El enlace vence y sirve una sola vez.

2. Tu cliente entrega su clave, en nuestra página

Al abrir el enlace, la persona ve una página de Connect con el nombre de tu organización y el sistema a conectar, e ingresa el RUT de la empresa y su clave tributaria. La credencial viaja directo al vault, cifrada para tu organización. No la ves tú, ni tu frontend, ni el agente que creó el enlace.

Si el login falla, la persona puede reintentar (cada intento reemplaza la credencial guardada). Si el enlace venció, crea otro. El resultado te llega por dos vías: el webhook connect_session.consumed (si tienes webhooks configurados) o consultando el estado, que es el paso siguiente.

3. Confirma la conexión

curl -X POST https://connect.emisso.ai/api/v1/tools/conexiones.estado.consultar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"input": {"sistema": "sii"}}'

Salida esperada (200, campo data, recortada):

{
  "conexiones": [{
    "id": "conn_9tKfR2mQx4Vb",
    "sistema": "sii",
    "nombre": "Comercial Aurora SpA",
    "estado": "active",
    "credencial": "linked",
    "verificadaEn": "2026-08-07T14:12:03.220Z",
    "alcances": ["rcv", "boletas", "guias", "boletas_honorarios"],
    "cadencia": "daily",
    "trabajos": [],
    "datosListos": false
  }]
}

Guarda ese conn_9tKfR2mQx4Vb: es el connectionId que toda tool del SII te va a exigir, incluso mientras tengas una sola conexión. Cuando conectes la segunda, el id va a ser lo único que las distinga, y por eso no hay resolución implícita. El detalle del modelo está en Conexiones.

datosListos: false dice la verdad: la credencial quedó vinculada, pero todavía no hay nada que leer. Falta un paso.

4. Sincroniza el primer período

La sincronización abre una sesión real en el SII (un login, un logout) y persiste los alcances solicitados en una sola pasada.

curl -X POST https://connect.emisso.ai/api/v1/tools/sii.conexion.sincronizar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input": {"periodo": "2026-07", "alcances": ["rcv"]}}'

Salida esperada (200, campo data, recortada):

{
  "periodo": "2026-07",
  "results": [{
    "alcance": "rcv",
    "status": "ok",
    "recordsSynced": 214,
    "completo": true
  }]
}

¿Prefieres no esperar el login en línea?

El mismo trabajo corre asíncrono por la API de control: POST /v1/connections/conn_…/syncs responde 202 con job_ids al instante, y el resultado llega por el webhook sync.succeeded. Además, cadencia: "daily" ya deja este sync corriendo solo todos los días.

5. Lee el RCV

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

Salida esperada (200, campo data, recortada):

{
  "documentos": [
    { "tipoDte": 33, "folio": 4712, "rutReceptor": "76543210-3", "montoNeto": 1250000, "montoIva": 237500, "montoTotal": 1487500 }
  ],
  "cursor": null,
  "sincronizacion": { "sincronizadoEn": "2026-08-07T14:18:52.000Z", "completo": true }
}

La respuesta llega al instante porque lee lo que el paso 4 dejó persistido, no al SII. El shape completo, con los 22 campos por documento y montos que cuadran al peso, está en la referencia de la tool.

Criterio de éxito

conexiones.estado.consultar ahora muestra datosListos: true, y sii.rcv.consultar devuelve documentos con sincronizacion.completo: true. En tu bitácora quedaron las filas de cada paso, incluida la sincronización con su latencia real.

Próximos pasos

Sincronizar y consultar: el modelo de dos pasos que acabas de usar, explicado entero.
Guía del SII: los cuatro alcances y sus verdades operativas.
Webhooks: entérate de cada sincronización sin hacer polling.
Conecta a tus clientes: si esto lo vas a repetir para muchos clientes finales desde tu producto.

Conecta tu primera empresa

On this page