Empieza aquí

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

  • Tu API key connect_sk_… con los scopes conexiones:write, conexiones:read 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."
}

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 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 configurados) o consultando el estado, que es el paso siguiente.

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

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": "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.

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

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:

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

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

{
  "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

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.

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

{
  "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 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

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

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

Respuesta cuando el trabajo terminó bien (recortada):

{
  "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. 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.

Para pedir varios meses, consulta el ejemplo de agosto y septiembre: usa periodos en plural por la API de control y guarda cada id de trabajo para seguirlo.

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

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:

{ "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 quedaron las filas de cada paso, incluida la solicitud de encolado y la ejecución posterior de la sincronización.

Próximos pasos

En esta página