Conexiones

Una conexión (id conn_…) une tu organización con un sistema para un contribuyente o titular concreto: el SII de Comercial Aurora SpA, la cuenta bancaria de esa misma empresa o el acceso personal de alguien al Poder Judicial. Es la unidad de autorización (sus tools autorizan contra ella), de sincronización (los datos persistidos cuelgan de ella) y de facturación. Una organización puede tener varias conexiones del mismo sistema, por ejemplo al SII de dos contribuyentes distintos. Cada una conserva su propia credencial, sus datos y su historial.

Los conectores de referencia (core, indicadores) y el de plataforma (conexiones) no tienen conexión: sus datos son globales o son el plano de control de Connect sobre sí mismo, y por eso sus tools no piden connectionId. Todo lo demás (SII, bancos) existe únicamente a través de una conexión.

Reconocer una conexión en el panel

El menú lateral y la lista de Conexiones muestran el nombre de cada conexión y, cuando está disponible, su RUT como dato complementario. Ese RUT identifica al contribuyente o al titular del acceso, según el sistema. Así puedes distinguir conexiones con nombres como SII y SII 2. En el menú lateral, si todavía no hay un RUT guardado, aparece solo el nombre.

Puedes cambiar el nombre desde los Ajustes de la conexión para reconocerla con una etiqueta propia. El RUT se muestra por separado: al confirmar una eliminación, escribe el nombre exacto de la conexión.

El ciclo de vida

conexiones.estado.consultar (y la pantalla Conexiones del dashboard) muestra tres ejes por conexión: el estado de la conexión, el de su credencial y la cadencia de sincronización.

Estado de la conexión:

Estado de la credencial:

Cadencia: off, daily, 12h, 6h o 4h. No se configura en ninguna parte, ni por API ni desde el dashboard: la decide Connect por conector y toda conexión activa la tiene. Hoy es 4h en todos los conectores que sincronizan, sin importar el plan (la excepción es Previred, que no sincroniza solo entre el 10 y el 13 de cada mes). Si necesitas una frecuencia de actualización mayor, escríbenos a contacto@tryemisso.com y te preparamos una propuesta. El único camino a off es el auto-pause por credencial inválida, que recuerda la cadencia anterior: arreglar la clave la restaura sola, sin que nadie reconfigure nada.

connectionId es obligatorio, incluso con una sola conexión

Toda tool de un conector con conexión exige decir cuál: header X-Connect-Connection en REST, campo connectionId de execute en MCP, opts.connectionId en el SDK. No hay resolución implícita ni cuando existe exactamente una, y es deliberado: la conexión ES la empresa, y una elección implícita que hoy acierta porque hay una sola, mañana acierta distinto sin que nadie haya cambiado nada. Con dos conexiones de un banco, «la conexión» es ambigua entre dos RUT; con una, es una afirmación silenciosa que nadie escribió.

Omitirlo no cuesta una adivinanza, porque el error lo explica:

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

Respuesta (400):

{
  "error": {
    "code": "validation_error",
    "message": "'sii.rcv.consultar' requiere una conexión concreta.",
    "suggested_fix": "Pasa el connectionId de la conexión de 'sii' (MCP: campo 'connectionId' de execute; REST: header 'X-Connect-Connection'). Lístalos con la tool 'conexiones.estado.consultar'.",
    "request_id": "req_..."
  },
  "meta": {
    "request_id": "req_...",
    "tool_id": "sii.rcv.consultar",
    "plane": "action",
    "latency_ms": 2,
    "audit_status": "recorded"
  }
}

El id sale de conexiones.estado.consultar (o de GET /v1/connections). Para la historia que cuentan estas páginas, conn_9tKfR2mQx4Vb es la conexión SII de Comercial Aurora SpA (RUT 77.123.456-9).

Reconectar

Cuando la clave del sistema cambia o vence, la credencial queda invalid y el camino es rotarla sobre la misma conexión, nunca crear una segunda. Tres vías:

• Por agente: conexiones.enlace.crear con {"sistema": "sii", "modo": "reconectar", "conexionId": "conn_9tKfR2mQx4Vb"} devuelve un enlace de un solo uso para que la persona entregue la clave nueva. El enlace de reconexión vence en 1 hora: se emite con la persona presente.
• Por API: POST /v1/connect_sessions con mode: "reauth" y connection_id (flujo hosted).
• En el dashboard: los ajustes de la conexión piden la credencial completa de nuevo. No hay prefill: el secreto se guarda como un solo blob cifrado y el dashboard no tiene camino de descifrado.

La rotación reemplaza el cifrado sobre la misma conexión y dispara la verificación contra el sistema (conexion.verificar); si el auto-pause había apagado la cadencia, arreglar la clave la restaura. El historial, los datos sincronizados y el conn_… no cambian.

Deshabilitar y eliminar

Deshabilitar es el interruptor reversible: la conexión queda en disabled, sus tools responden 403 connection_disabled, deja de devengar facturación y nada se borra. Sirve para pausar un sistema sin perder nada de lo sincronizado.

Se pausa y se reanuda desde la fila de la conexión en el dashboard, o por agente o API:

• conexiones.conexion.deshabilitar con {"conexionId": "conn_9tKfR2mQx4Vb"} la pausa. Exige el permiso conexiones:disable.
• conexiones.conexion.habilitar con el mismo input la reanuda. Exige conexiones:enable. La conexión vuelve a sumarse al cobro: si la organización ya usa las conexiones que incluye su plan, la respuesta trae costoAdicional con lo que suma. Durante la prueba respeta el máximo de conexiones activas, y con la cobranza pendiente se rechaza como cualquier alta.

Las dos van por execute_write en MCP y por POST /v1/tools/<tool>/execute en REST. Pedir el estado que la conexión ya tiene no cambia nada y responde cambiada: false. Una conexión pending, que todavía no tiene credencial, no se habilita: se completa con conexiones.enlace.crear en modo reconectar.

Eliminar destruye la credencial cifrada, los datos sincronizados de esa conexión, sus programaciones y trabajos de sincronización y sus webhooks. La bitácora y el registro de cambios de configuración se conservan como registros inmutables de auditoría y facturación; sus filas mantienen el connection_id de la conexión eliminada.

Se elimina por dos vías, con las mismas reglas:

• En el dashboard: los ajustes de la conexión, escribiendo su nombre exacto para confirmar. Solo un owner o admin puede hacerlo.
• Por agente o API: conexiones.conexion.eliminar con {"conexionId": "conn_9tKfR2mQx4Vb", "confirmarNombre": "Comercial Aurora SpA"}. Por MCP va por execute_write; por REST, POST /v1/tools/conexiones.conexion.eliminar/execute. Exige el permiso conexiones:delete, que es aparte de conexiones:write: una clave que crea enlaces no puede borrar conexiones. Con un token OAuth, la persona que lo autorizó tiene que seguir siendo owner o admin. La respuesta dice cuántos registros, sincronizaciones y webhooks se borraron.

Próximos pasos

• Conectar un sistema: crear tu primera conexión de punta a punta.
• Sincronizar y consultar: qué hacer con la conexión ya activa.
• El flujo hosted: pedirle la credencial a quien de verdad la tiene.