# Conexiones > La conexión es la empresa: la unidad con la que Connect autoriza, sincroniza y factura cada sistema externo. 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 [#el-ciclo-de-vida] `conexiones.estado.consultar` (y la pantalla [Conexiones](https://connect.emisso.ai/connections) 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 | Qué significa | Cómo se sale | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `active` | Operativa: sus tools autorizan y la sincronización programada corre. Una conexión creada desde el dashboard o el flujo hosted nace en este estado. | Deshabilitándola o eliminándola. | | `disabled` | Apagada a mano. Toda tool de la conexión responde `403 connection_disabled`, y la conexión deja de devengar facturación desde ese momento. Los datos ya sincronizados no se tocan. | Reactivándola en el dashboard. Ambos cambios quedan auditados (`connection.enabled` / `connection.disabled`). | | `pending` | Creada pero todavía no operativa. En la práctica es raro verla: los flujos de alta dejan la conexión activa de inmediato. | Completando el alta (entregar la credencial) o eliminándola. | **Estado de la credencial:** | Credencial | Qué significa | Cómo se sale | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `linked` | Vinculada y utilizable. `verificadaEn` registra la última verificación exitosa contra el sistema. | Es el estado normal. | | `invalid` | El sistema rechazó el último login: la clave cambió o venció. A la tercera falla consecutiva, la sincronización programada se pausa sola. | Reconectando (abajo). Un login posterior que funciona también la devuelve a `linked`. | | `revoked` | Anulada de forma explícita: el vault se niega a entregarla aunque siga cifrada en la base. | Entregando la credencial de nuevo. | | `ausente` | La conexión no tiene credencial guardada. | Entregándola: por enlace de conexión o en los ajustes del dashboard. | **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 [#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: ```bash 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`): ```json { "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 [#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](/docs/operar/enlace-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-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](/docs/conceptos/bitacora) 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. Recrear la conexión, incluso con el mismo nombre y la misma credencial, produce un `conn_` nuevo al que no se le puede re-adosar nada de lo anterior: el cifrado de los datos ata cada fila a la conexión original. Por eso la confirmación exige escribir el nombre exacto de la conexión, y solo un owner o admin puede hacerlo. Si hay una sincronización en vuelo, la operación responde `connection_busy` (reintentable) en vez de borrar debajo de un trabajo corriendo. ## Próximos pasos [#próximos-pasos] * [Conectar un sistema](/docs/empezar/conectar): crear tu primera conexión de punta a punta. * [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar): qué hacer con la conexión ya activa. * [El flujo hosted](/docs/operar/enlace-hosted): pedirle la credencial a quien de verdad la tiene.