# 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 Emisso, Emisso sincroniza los primeros
meses y tú 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`, `conexiones:read` 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."
}
```

### 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 Emisso 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]

Este paso llama una tool por **POST**. No existe `GET /v1/connections/{id}/estado`.
Para filtrar una sola conexión, usa `{"input":{"conexionId":"conn_..."}}` en esta misma ruta.
`trabajos` muestra los cinco últimos; para seguir un trabajo concreto usa `GET /v1/syncs/{id}`.

```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": "4h",
    "trabajos": [{
      "id": "sjb_4hqm7tz2kd9xwp1nr6c8v",
      "estado": "running",
      "periodo": "2026-08",
      "alcances": ["rcv", "boletas", "guias", "boletas_honorarios"],
      "registros": null,
      "error": null
    }],
    "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 y la primera sincronización ya
está en `trabajos`, pero todavía no terminó. No tienes que pedirla: el enlace la encoló al recibir la
clave, con el mes corriente y los dos anteriores.

## 4. Espera la primera sincronización [#4-espera-la-primera-sincronización]

Mientras el `estado` del trabajo sea `queued` o `running`, todavía no hay nada que leer. Para saber
cuándo terminó, consulta el trabajo por su id:

```bash
curl https://connect.emisso.ai/api/v1/syncs/sjb_4hqm7tz2kd9xwp1nr6c8v \
  -H "Authorization: Bearer connect_sk_…"
```

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

```json
{
  "job_id": "sjb_4hqm7tz2kd9xwp1nr6c8v",
  "status": "succeeded",
  "periodo": "2026-08",
  "outcomes": [
    { "alcance": "rcv", "status": "ok", "recordsSynced": 214, "completo": true, "reconMismatches": 0, "filasDescartadas": 0 },
    { "alcance": "boletas", "status": "ok", "recordsSynced": 31 }
  ]
}
```

Cuando termina, revisa que el resultado de `rcv` en `outcomes` sea `ok`, con `completo: true`,
`reconMismatches: 0` y `filasDescartadas: 0`;
`status: "succeeded"` por sí solo no acredita el mes completo. `datosListos` pasa a `true` en
`conexiones.estado.consultar` cuando ya no queda ninguno de los meses del alta en cola ni corriendo:
los dos anteriores llegan después, uno tras otro.

### Pide una sincronización cuando la necesites [#pide-una-sincronización-cuando-la-necesites]

Para traer datos frescos de un mes sin esperar la cadencia, llama a `sii.conexion.sincronizar`. La
sincronización consulta el SII y persiste los alcances solicitados en una sola pasada,
pero no te hace esperar ese login: la llamada encola el trabajo y responde al instante.

`alcances` es obligatorio en esta tool; aquí pedimos `rcv`, que debe estar habilitado en la conexión.
Reemplaza el período del ejemplo por el que necesitas; durante la prueba puedes cargar el mes actual
y los dos anteriores.

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

```json
{
  "periodo": "2026-07",
  "estado": "encolado",
  "jobId": "sjb_9f2kc0q8w1m4x7t3p6b5d",
  "yaEnCurso": false
}
```

El `200` confirma el encolado, no que el mes ya esté cargado. Guarda `data.jobId` y sigue ese trabajo.
Si `yaEnCurso` es `true`, ya había uno para esa conexión y período: usa su `jobId` cuando venga.
Si viene `null`, revisa la sincronización de la conexión en el panel; no consultes `/syncs/null`
ni vuelvas a encolar para obtener otro identificador. El mismo mes de una conexión se puede volver a
pedir una vez cada 10 minutos; antes responde `rate_limited`.

La [API de control](/docs/operar/api-control) permite pedir varios períodos con
`POST /v1/connections/{conn}/syncs`: responde `202` con `data.job_ids`. Ambos caminos son asíncronos.

## 5. Espera y comprueba el resultado [#5-espera-y-comprueba-el-resultado]

Con el `jobId` del paso anterior y la misma API key:

```bash
curl https://connect.emisso.ai/api/v1/syncs/sjb_9f2kc0q8w1m4x7t3p6b5d \
  -H "Authorization: Bearer connect_sk_…"
```

Respuesta cuando el trabajo terminó bien (recortada):

```json
{
  "data": {
    "job_id": "sjb_9f2kc0q8w1m4x7t3p6b5d",
    "periodo": "2026-07",
    "status": "succeeded",
    "outcomes": [{ "alcance": "rcv", "status": "ok", "recordsSynced": 214, "completo": true, "reconMismatches": 0, "filasDescartadas": 0 }],
    "last_error": null
  }
}
```

* Con `queued` o `running`, espera unos segundos y repite **esta consulta**, no el POST de sincronización.
* Con `succeeded`, comprueba el período y el resultado de `rcv` en `outcomes`. Un trabajo puede terminar
  con alcances parciales o fallidos: no basta el estado general para dar el mes por completo.
  Para RCV exige `completo: true`, `reconMismatches: 0` y `filasDescartadas: 0`; si falta alguna señal
  o un contador es distinto de cero, detén el informe. `completo` no detecta esas pérdidas por sí solo.
* Con `failed`, revisa `last_error` y el [catálogo de errores](/docs/referencia/errores). Si `rcv` está
  `partial`, `failed` o trae `completo: false`, los datos disponibles no acreditan el mes completo.
  Corrige la causa indicada antes de pedir otra sincronización.

Este seguimiento funciona durante la prueba, sin configurar webhooks. Para automatizarlo con una
espera acotada y manejo de errores, usa el [ejemplo de seguimiento](/docs/conceptos/sincronizar-consultar#seguimiento-desde-tu-código).

Para pedir varios meses, consulta el [ejemplo de agosto y septiembre](/docs/operar/api-control#pedir-agosto-y-septiembre-y-ver-su-estado):
usa `periodos` en plural por la API de control y guarda cada id de trabajo para seguirlo.

## 6. Lee el RCV [#6-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 lee lo que el trabajo dejó persistido, después de comprobarlo en el paso 5. 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]

El trabajo del período solicitado terminó y su alcance `rcv` quedó `ok`, con `completo: true`,
`reconMismatches: 0` y `filasDescartadas: 0`. Estos contadores se revisan en `outcomes`, porque la
consulta no los devuelve. La consulta de ese
mismo período trae `sincronizacion.completo: true`: si `documentos` está vacío, no hay documentos para
los filtros pedidos; si `sincronizacion` es `null` o está incompleta, no concluyas que el mes no tiene
ventas. Recorre las páginas mientras `cursor` tenga valor.

Para pedir la página siguiente, repite `POST /api/v1/tools/sii.rcv.consultar/execute` con las mismas
cabeceras, conexión, período y perspectiva, y agrega el `data.cursor` recibido como `input.cursor`.
Por ejemplo, si recibiste `"cursor_opaco"`, el cuerpo siguiente es:

```json
{ "input": { "periodo": "2026-07", "perspectiva": "ventas", "cursor": "cursor_opaco" } }
```

El cursor es opaco: pásalo sin modificarlo. Acumula `data.documentos` de cada página hasta recibir
`data.cursor: null`; comprueba `sincronizacion.completo` en cada respuesta. Si una página falla o no
acredita completitud, detén el informe en lugar de devolver lo acumulado como el mes completo.

`datosListos: true` solo indica que la conexión tiene datos, que pueden ser de otro período o de una
sincronización anterior. No sustituye la comprobación del trabajo. En tu
[bitácora](https://connect.emisso.ai/bitacora) quedaron las filas de cada paso, incluida la
solicitud de encolado y la ejecución posterior de la sincronización.

## 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): sus alcances y sus verdades operativas.
* [Webhooks](/docs/operar/webhooks): entérate de cada sincronización sin hacer polling.
* [Conecta a tus clientes](/docs/plataformas): si esto lo vas a repetir para muchos clientes finales desde tu producto.


---

Esta página es parte de la documentación de Emisso. El índice completo, con cada página y su descripción, está en https://connect.emisso.ai/llms.txt. Esta misma página en HTML: https://connect.emisso.ai/docs/empezar/conectar.
