Conectores e integraciones

Los conectores permiten que tus agentes lean y escriban en tus herramientas reales (correo, calendario, almacenamiento, chat y CRM) mediante OAuth, API key o webhook. El flujo de conexión, el cifrado por tenant y los endpoints son idénticos en todos los planes desde First: el diferencial entre planes está en los agentes departamentales, el orquestador Amadeus, la cuota STU y el soporte, no en los conectores.

Cómo funcionan los conectores

Cada conector declara un flujo de conexión (connectFlow) que determina cómo se obtienen las credenciales. Hay tres tipos:

• oauth: el usuario autoriza el acceso desde la pantalla de login del propio proveedor. Shara nunca ve la contraseña; recibe un token de acceso (y, cuando aplica, uno de refresco) con los permisos que el usuario consintió.
• api-key: pegas una clave generada en el panel del servicio. La clave se cifra antes de persistirse y se asocia únicamente a tu tenant.
• webhook: Shara provisiona un endpoint y un secreto por tenant para recibir eventos entrantes de sistemas externos. El secreto nunca se comparte entre tenants.

Una vez conectado, el agente que necesite la herramienta detecta la integración activa y la añade a sus capacidades automáticamente. Cada conector publica un conjunto de tools nativas (acciones concretas como «enviar correo» o «crear evento») que los agentes pueden invocar.

Catálogo de conectores OAuth

Conectores que se autentican mediante OAuth (consentimiento del usuario en el proveedor). La columna Tools nativas indica las acciones que el conector expone a los agentes.

Conector	Slug	Categoría	Tools nativas
Gmail	gmail	Comunicación	send_email, list_inbox, search_mail
Google Calendar	google-calendar	Productividad	create_event, list_events, check_availability
Google Drive	google-drive	Almacenamiento	list_files, upload_file, download_file
Outlook Mail	outlook-mail	Comunicación	send_mail, list_inbox
Microsoft Calendar	microsoft-calendar	Productividad	create_event, list_events
Microsoft Teams	microsoft-teams	Comunicación	send_message, list_channels, list_chats, search_messages
OneDrive	onedrive	Almacenamiento	list_files, download_file
Slack	slack	Comunicación	send_message, list_channels, search_messages
HubSpot	hubspot	CRM y ventas	get_contact, create_deal, log_activity
Pipedrive	pipedrive	CRM y ventas	Deals, personas y organizaciones
Notion	notion	Productividad	get_page, create_page, search
Holded	holded	CRM y ERP	Contactos, facturas y documentos

Este catálogo crece: incorporamos nuevos conectores cada mes. Además, cualquier sistema sin conector nativo se integra ya mismo con el conector genérico OAuth, los webhooks HTTP, el MCP gateway o el Server Agent (más abajo).

Catálogo de conectores con API key o webhook

Conectores que no usan OAuth. La clave o el secreto es siempre por tenant y se cifra con el mismo almacén seguro que los tokens OAuth.

Conector	Slug	Flujo	Categoría
Resend	resend	api-key	Email transaccional
Mixpanel	mixpanel	api-key	Analítica
Segment	segment	api-key	Analítica
Discord	discord	api-key	Comunicación
Automatización externa	webhook	webhook	Recibe eventos de tu propia herramienta de automatización

Conectores universales

Además del catálogo, todos los planes desde First disponen de mecanismos para conectar sistemas que no tienen un conector específico:

• Desktop Agent: app instalable para Windows, macOS y Linux que expone tus apps locales (hoja de cálculo, contabilidad, ERP propietario) como herramientas del equipo.
• Server Agent: agente residente en tu servidor para exponer servicios internos a los agentes.
• HTTP webhooks: recibe eventos de cualquier sistema y dispara flujos en Shara.
• MCP gateway: protocolo Model Context Protocol para integraciones bidireccionales con tus propias herramientas.
• Conector genérico OAuth: conecta cualquier API que hable OAuth 2.0 aunque no tenga aún un conector dedicado en el catálogo.

Las acciones del Desktop Agent y del Server Agent fuera de la allowlist requieren aprobación humana antes de ejecutarse. Lee Qué es Shara.

Tabla de permisos OAuth por conector

La columna Preset por defecto es el conjunto de scopes que Shara solicita cuando no especificas ninguno al iniciar la conexión. Puedes pedir un subconjunto del preset para ajustarte al mínimo privilegio: cualquier scope fuera del catálogo declarado se rechaza con 400 unknown_scopes, y una lista vacía con 400 empty_scopes.

Google: Gmail, Calendar, Drive

Servicio	Preset por defecto	Scopes disponibles
Gmail	gmail.readonly + gmail.send + gmail.modify + userinfo.email	gmail.readonly, gmail.send, gmail.modify, userinfo.email, userinfo.profile
Google Calendar	calendar + calendar.events	calendar, calendar.events, calendar.readonly
Google Drive	drive.readonly + drive.metadata.readonly	drive, drive.readonly, drive.metadata.readonly, drive.file

Los scopes de Gmail, Calendar y Drive son sensibles: el proveedor exige superar su proceso de verificación de la app antes de habilitarlos para cuentas externas. El scope drive.file (acceso solo a archivos creados por la app) es la opción menos invasiva para Drive.

Microsoft 365 / Entra ID: Outlook, Calendar, Teams, OneDrive

Todos los flujos de Microsoft añaden siempre offline_access (para emitir token de refresco) y User.Read (identidad básica). El refresco de token rota el token de refresco en cada renovación; Shara lo contempla de forma transparente.

Servicio	Preset por defecto	Scopes disponibles
Outlook Mail	Mail.Read + Mail.Send + Mail.ReadWrite	Mail.Read, Mail.ReadWrite, Mail.Send
Microsoft Calendar	Calendars.ReadWrite	Calendars.Read, Calendars.ReadWrite
Microsoft Teams	Chat.ReadWrite + ChannelMessage.Send + Channel.ReadBasic.All + Team.ReadBasic.All	Chat.ReadWrite, ChannelMessage.Send, Channel.ReadBasic.All, Team.ReadBasic.All
OneDrive	Files.Read.All	Files.Read.All, Files.ReadWrite.All

Algunos scopes de Microsoft (por ejemplo Files.ReadWrite.All) pueden requerir el consentimiento del administrador global del tenant del cliente. Esto está previsto en el onboarding empresarial.

Slack: token de bot y token de usuario

Slack distingue entre el token de bot (xoxb, el modo por defecto) y el token de usuario (xoxp, opcional). Por defecto Shara usa el token de bot; el de usuario solo se activa si necesitas búsqueda de mensajes.

Tipo	Preset por defecto	Scopes adicionales
Bot (xoxb)	chat:write + channels:read + users:read + app_mentions:read	chat:write.public, channels:history, groups:history, im:history, users:read.email, commands
Usuario (xoxp, opt-in)	(ninguno)	search:read (única capacidad que exige token de usuario)

CRM y ERP: HubSpot, Pipedrive y Holded

CRM / ERP	Preset por defecto	Scopes disponibles
HubSpot	oauth + crm.objects.contacts.read/write + crm.objects.deals.read/write + crm.objects.companies.read/write + crm.schemas.deals.read	crm.schemas.contacts.read, crm.schemas.companies.read. El scope oauth es obligatorio.
Pipedrive	base + deals:full + contacts:full + search:read + users:read	deals:read, contacts:read, activities:read, activities:full, admin
Holded	API key por tenant (contactos, facturas y documentos)	Alcance según la clave configurada en Holded; se cifra por tenant como el resto de credenciales.

Los CRM usan scopes por objeto/recurso. Concede permiso de escritura solo en los objetos donde el agente vaya a crear o actualizar registros (por ejemplo, solo deals si únicamente gestiona oportunidades).

Otros conectores OAuth

Conector	Preset por defecto	Notas de scopes
Notion	(vacío)	No usa scopes; el usuario elige workspace y páginas en su propio consentimiento.

Ampliamos el catálogo de conectores cada mes. Si el sistema que usas aún no aparece, el conector genérico OAuth cubre cualquier API OAuth 2.0 mientras preparamos el conector dedicado.

Flujo de conexión paso a paso

Para un cliente o desarrollador externo, el contrato público de integración se compone de dos endpoints principales y el callback del proveedor. El recorrido completo es:

1. El cliente consulta el catálogo y el estado de conexión: GET /v1/integrations devuelve cada conector con su connectFlow y si ya está conectado para tu tenant.
2. El cliente inicia la conexión: POST /v1/integrations/:slug/connect. Según el connectFlow, para oauth devuelve { authUrl, state }; para api-key recibe la clave y la cifra; para webhook provisiona el token por tenant.
3. El usuario abre authUrl y autoriza en el proveedor. Tras consentir, el proveedor redirige al callback público de Shara con un code y el state.
4. Shara valida el state, intercambia el code por los tokens, los cifra y los persiste asociados a tu tenant. La integración pasa a estado conectado.
5. A partir de ahí, los agentes que necesiten ese conector lo usan automáticamente. Los tokens nunca se devuelven al cliente.

El catálogo y el estado de conexión se consultan así:

# Listar el catálogo de conectores y su estado para tu tenant
curl -s https://api.sharasaas.com/v1/integrations \
  -H "Authorization: Bearer $SHARA_TOKEN"

La respuesta describe cada conector y su disponibilidad:

{
  "integrations": [
    {
      "slug": "gmail",
      "name": "Gmail",
      "category": "communication",
      "connectFlow": "oauth",
      "connected": false,
      "scopes": ["gmail.readonly", "gmail.send", "gmail.modify", "userinfo.email"]
    },
    {
      "slug": "resend",
      "name": "Resend",
      "category": "productivity",
      "connectFlow": "api-key",
      "connected": true
    }
  ]
}

Para iniciar una conexión OAuth pidiendo un subconjunto de scopes (mínimo privilegio):

# Conectar Gmail solo en modo lectura (subconjunto del preset)
curl -s -X POST https://api.sharasaas.com/v1/integrations/gmail/connect \
  -H "Authorization: Bearer $SHARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["gmail.readonly", "userinfo.email"] }'

La respuesta para un flujo oauth devuelve la URL de autorización y el state de un solo uso:

{
  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&state=...",
  "state": "9f3c1a7e-...-single-use",
  "expiresIn": 600
}

Para conectores api-key, el mismo endpoint recibe la clave en el cuerpo y la cifra antes de persistirla:

# Conectar un servicio de tipo api-key
curl -s -X POST https://api.sharasaas.com/v1/integrations/resend/connect \
  -H "Authorization: Bearer $SHARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "re_live_..." }'

Garantías de seguridad del flujo OAuth

El flujo de conexión incorpora varias protecciones por diseño, aplicadas de forma uniforme a todos los proveedores:

• PKCE en todos los proveedores. Cada conexión genera un code_verifier y su code_challenge, incluso para clientes confidenciales. Esto protege el intercambio de código frente a interceptación.
• state de un solo uso (delete-on-read). El state se elimina del almacén en el instante en que se lee, antes de validar su caducidad. Reutilizar el mismo state falla con 400 state_mismatch. TTL de 10 minutos.
• Autoridad ligada al token. El inicio de la conexión exige un JWT autenticado; la identidad y el tenantId se derivan del token, nunca de la query ni del body. El callback no necesita JWT: su autoridad es el state validado, atado al tenant en el arranque.
• Tokens cifrados antes de persistir. Los tokens de acceso y de refresco se cifran con cifrado autenticado en un almacén seguro, con el material criptográfico aislado por tenant, y nunca se devuelven al cliente.
• Validación de scopes contra el manifest. Los scopes solicitados deben ser un subconjunto de los declarados; en caso contrario, 400 unknown_scopes (o 400 empty_scopes si la lista está vacía).
• Errores del proveedor redactados. Los mensajes de error del SDK del proveedor se redactan antes de registrarse o devolverse, para no filtrar datos sensibles.
• Refresco automático. Un proceso periódico renueva los tokens próximos a expirar. Si el proveedor revoca el acceso, la integración pasa a estado revoked y deja de utilizarse hasta que se reconecte.

Buenas prácticas de configuración

• Pide el mínimo scope necesario. El preset por defecto es amplio por comodidad. Si tu caso de uso es solo lectura, solicita el subconjunto (por ejemplo gmail.readonly sin gmail.send, o Calendars.Read en lugar de Calendars.ReadWrite). Menos scope = menor superficie y menos fricción de verificación.
• Registra el redirect_uri exacto en la consola del proveedor: debe coincidir carácter a carácter con el callback público de la API.
• Google: los scopes de Gmail, Calendar y Drive son sensibles; prepara la verificación de la app antes de exponerlos a cuentas externas.
• Microsoft: algunos scopes exigen consentimiento del administrador global del tenant del cliente. El token de refresco rota en cada renovación.
• Slack: usa el token de bot por defecto; activa el token de usuario solo si necesitas search:read.
• CRM (HubSpot / Pipedrive): concede escritura únicamente en los objetos que el agente vaya a modificar.
• API key y webhook: la clave o el secreto es siempre por tenant, nunca compartido, y se cifra con el mismo almacén seguro que los tokens OAuth.

¿Falta tu herramienta?

Si usas un sistema que aún no tiene conector nativo, casi siempre se puede integrar vía webhooks, MCP gateway o el Server Agent. Cuéntanos tu caso en [email protected] y valoramos añadirlo.