# Conectores

> Cuentas externas a las que el agente accede en tu nombre — Google Drive, Mercado Pago, Skydropx, Odoo, GitHub — y cómo se conectan.

URL: https://www.ghosty.studio/docs/conectores

Un conector es una cuenta externa que el agente puede usar **en tu nombre**. Se conecta una vez por persona y lo usan todos tus agentes.

## Cómo funciona

- **La cuenta conecta; cada agente recibe acceso.** La llave se guarda cifrada bajo `(tu usuario, proveedor)`. Como con las bases de datos, un agente sólo usa los conectores que le das en su ficha → **Conectores** (un agente nuevo nace sin ninguno). En canales de equipo lee y escribe; en canales de clientes sólo lee, salvo que lo permitas.
- **Actúa por quien invoca.** En Teams, si `@handle` manda un correo desde un canal, lo manda con la cuenta de la persona que lo mencionó, no con una cuenta compartida. En un canal público (WhatsApp) los conectores personales **no están disponibles**.
- **Desconectar revoca.** Quitar un conector borra la llave y revoca el permiso en el proveedor.

## Dónde se conectan

- **Studio**: el chip **Conectores** del chat (`/c`), y la ficha de cada agente dice cuáles tiene. Los de credenciales (Mercado Pago, Skydropx) se pegan en *Ajustes → Credenciales*.
- **Teams**: *Ajustes → Integraciones* del espacio, para lo que el agente usa dentro del espacio (GitHub, Calendly, Deník…).
- **App móvil**: *Ajustes → Integraciones* con la misma lista, vía la [API de conectores](#api).

## Catálogo

| Conector | Tipo | Qué puede hacer el agente |
|---|---|---|
| Google Drive | OAuth2 + selector | Leer las hojas, documentos y CSV que elijas; agregar filas y actualizar celdas. |
| Mercado Pago | Credenciales (access token) | Links de pago (Checkout Pro) a tu cuenta. |
| Skydropx | Credenciales (Client ID:Secret) | Cotizar, crear y rastrear envíos. |
| EasyBits | OAuth2 | Documentos, sitios, video e imágenes desde tu cuenta. |
| Odoo | Credenciales (URL, usuario, llave API) (Teams) | Leer y crear registros del ERP. |
| GitHub | OAuth2 (Teams) | Issues, PRs y código de los repos del espacio. |
| Calendly | OAuth2 (Teams) | Agenda y disponibilidad. |
| Google Calendar, Deník, Kommo, Mailmask | — | En camino. |

## Google Drive

El agente **sólo ve los archivos que tú eliges**. Al conectar, Google te pide permiso para «los archivos que uses con esta app» (`drive.file`) y enseguida se abre el selector de Google para elegir tu lista de precios, inventario o catálogo. Nada más de tu Drive queda a su alcance.

- **Qué lee**: hojas de cálculo de Google (todas las pestañas), documentos de Google y archivos CSV o de texto. PDF y `.xlsx` todavía no.
- **Tools**: `drive_archivos` (lo que elegiste), `drive_leer`, `hoja_agregar_fila` y `hoja_actualizar`.
- **Escribir** en una hoja vale desde canales de equipo (tu chat, Teams, programados). Para que un cliente (Messenger, WhatsApp) pueda anotar, por ejemplo, su pedido, marca «Puede escribir desde canales de clientes» en la ficha del agente → Conectores.
- **Agregar o quitar archivos**: *Conectores → Google Drive → Archivos*. Qué archivos ve **cada agente** se elige en su ficha → Conectores.
- **Desconectar** revoca el permiso en tu cuenta de Google.

## Odoo y otros conectores por credenciales

Los que no son OAuth se dan de alta con sus credenciales (URL de la instancia, usuario, llave). La URL pasa por un guard de red: sólo hosts públicos, sin IPs privadas ni `localhost`, para que un conector no sirva para alcanzar tu red interna desde la máquina del agente.

## API

Para clientes propios (la app móvil los usa):

| Ruta | Qué hace |
|---|---|
| `GET /api/v2/me/connectors` | Catálogo con `conectado: true/false` por conector. |
| `POST /api/v2/me/connectors/:id/start` | Devuelve la `url` de autorización para abrir en el navegador. |
| `DELETE /api/v2/me/connectors/:id` | Desconecta y revoca. |

Requieren bearer OAuth2; ver [Autenticación](/docs/api/autenticacion).

```bash
# catálogo con el estado de cada conector
curl https://www.ghosty.studio/api/v2/me/connectors -H "Authorization: Bearer $TOKEN"

# arrancar la autorización de uno (abre la url que devuelve en el navegador)
curl -X POST https://www.ghosty.studio/api/v2/me/connectors/easybits/start -H "Authorization: Bearer $TOKEN"

# desconectar (revoca en el proveedor)
curl -X DELETE https://www.ghosty.studio/api/v2/me/connectors/easybits -H "Authorization: Bearer $TOKEN"
```