Conexiones

Una conexión (id conn_…) une tu organización con un sistema concreto usando la credencial de una empresa: el SII de Comercial Aurora SpA, la cuenta bancaria de esa misma empresa. 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: dos conexiones del SII son dos RUT distintos, cada una con su 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.

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 o 6h. Se configura en los ajustes de la conexión, y apagarla (off) está permitido siempre. Cuando el auto-pause de credencial la apaga, la cadencia anterior queda recordada: arreglar la clave la restaura sola, sin reconfigurar 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.

Eliminar borra de verdad. Se destruyen la credencial cifrada, los datos sincronizados de esa conexión, sus programaciones y trabajos de sincronización y sus webhooks. Sobreviven dos cosas, y con razón: la bitácora y el registro de cambios de configuración son append-only y son la fuente de verdad de la facturación, así que sus filas quedan con el connection_id apuntando a una conexión que ya no existe.

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.