# 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 [#antes-de-empezar]

* Tu API key `connect_sk_…` con los scopes `conexiones:write` y `sii:read`
  ([connect.emisso.ai/api-keys](https://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 [#1-crea-el-enlace-de-conexión]

### curl [#curl]

```bash
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`):

```json
{
  "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 [#sdk-typescript]

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

### MCP [#mcp]

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

<Callout type="warn" title="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.
</Callout>

## 2. Tu cliente entrega su clave, en nuestra página [#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](/docs/operar/webhooks) configurados) o consultando el estado, que es el paso
siguiente.

## 3. Confirma la conexión [#3-confirma-la-conexión]

```bash
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):

```json
{
  "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](/docs/conceptos/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 [#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.

```bash
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):

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

<Callout type="info" title="¿Prefieres no esperar el login en línea?">
  El mismo trabajo corre asíncrono por la [API de control](/docs/api-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.
</Callout>

## 5. Lee el RCV [#5-lee-el-rcv]

```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_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input": {"periodo": "2026-07", "perspectiva": "ventas"}}'
```

Salida esperada (`200`, campo `data`, recortada):

```json
{
  "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](/docs/referencia/sii/rcv-consultar).

## Criterio de éxito [#criterio-de-éxito]

`conexiones.estado.consultar` ahora muestra `datosListos: true`, y `sii.rcv.consultar` devuelve
documentos con `sincronizacion.completo: true`. En tu
[bitácora](https://connect.emisso.ai/bitacora) quedaron las filas de cada paso, incluida la
sincronización con su latencia real.

## Próximos pasos [#próximos-pasos]

* [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar): el modelo de dos pasos que acabas de usar, explicado entero.
* [Guía del SII](/docs/sistemas/sii): los cuatro alcances y sus verdades operativas.
* [Webhooks](/docs/operar/webhooks): entérate de cada sincronización sin hacer polling.
* [Conecta a tus clientes](/docs/operar/plataformas): si esto lo vas a repetir para muchos clientes finales desde tu producto.