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 scopesconexiones:write,conexiones:readysii: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
queuedorunning, espera unos segundos y repite esta consulta, no el POST de sincronización. - Con
succeeded, comprueba el período y el resultado dercvenoutcomes. Un trabajo puede terminar con alcances parciales o fallidos: no basta el estado general para dar el mes por completo. Para RCV exigecompleto: true,reconMismatches: 0yfilasDescartadas: 0; si falta alguna señal o un contador es distinto de cero, detén el informe.completono detecta esas pérdidas por sí solo. - Con
failed, revisalast_errory el catálogo de errores. Sircvestápartial,failedo traecompleto: 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
- Sincronizar y consultar: el modelo de dos pasos que acabas de usar, explicado entero.
- Guía del SII: sus 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.
Con tu asistente de IA
El texto que le entregas a ChatGPT, Claude o Cursor para que arme tu software sobre Emisso sin pedirte nunca la clave. Pensado para quien no programa.
Todos los sistemas
Qué se puede conectar hoy, qué credencial pide cada sistema y qué conviene saber de cada portal antes de la primera sincronización.