Marketplace de Integraciones

Catálogo de Integraciones

El marketplace ofrece integraciones pre-construidas organizadas por categoría. Consulta el catálogo vía GET /api/v1/integrations/marketplace:

GET /api/v1/integrations/marketplace?search=slack&category=communication&protocol=rest

Parámetros de búsqueda:

• search — Búsqueda por nombre o descripción
• category — Filtrar por categoría (communication, monitoring, erp, crm, iot)
• protocol — Filtrar por protocolo (rest, graphql, mqtt, websocket, grpc)

Cada integración en el catálogo incluye:

{
  "id": "slack-notifications",
  "name": "Slack Notifications",
  "category": "communication",
  "protocol": "rest",
  "description": "Send alerts and reports to Slack channels",
  "config_schema": { ... },
  "tool_templates": [ ... ],
  "version": "1.2.0"
}

Instalar Integración

Para instalar una integración del marketplace:

POST /api/v1/integrations/marketplace/{integration_id}/install
{
  "config": {
    "webhook_url": "https://hooks.slack.com/services/...",
    "channel": "#alerts",
    "notify_on": ["critical", "warning"]
  }
}

El proceso de instalación:

1. Se valida la configuración contra el config_schema de la integración
2. Se crean las herramientas definidas en tool_templates
3. Se almacenan las credenciales en Secret Manager
4. Se activa la integración para el tenant
5. Se ejecuta un test de conectividad

Si la validación falla, se retorna HTTP 422 con los campos inválidos.

Desinstalación con Limpieza

La desinstalación elimina todos los recursos asociados:

DELETE /api/v1/integrations/marketplace/{integration_id}/uninstall

El proceso limpia:

• Herramientas creadas desde las plantillas
• Credenciales almacenadas
• Webhooks registrados
• Configuración de la integración

Las herramientas creadas manualmente por el usuario no se eliminan.

Webhooks Entrantes

Las integraciones pueden recibir datos externos vía webhooks:

POST /api/v1/integrations/webhooks/inbound/{webhook_id}
X-Webhook-Secret: {secret}

Validación de seguridad:

• Cada webhook tiene un secreto único generado al crear la integración
• El header X-Webhook-Secret se valida contra el secreto almacenado
• Opcionalmente se valida la firma HMAC del payload
• Los requests sin secreto válido reciben HTTP 401

El payload del webhook se procesa según las reglas definidas en la integración, pudiendo disparar eventos, crear tareas o ejecutar herramientas.

Interpolación de Plantillas

Las plantillas de herramientas usan interpolación para valores dinámicos:

{
  "url": "{{config.base_url}}/api/messages",
  "headers": {
    "Authorization": "Bearer {{secrets.api_token}}"
  },
  "body": {
    "channel": "{{config.channel}}",
    "text": "{{input.message}}"
  }
}

Variables disponibles:

• {{config.*}} — Valores de configuración de la integración
• {{secrets.*}} — Credenciales almacenadas de forma segura
• {{input.*}} — Parámetros proporcionados al ejecutar la herramienta
• {{tenant.*}} — Datos del tenant (nombre, ID)

La interpolación se resuelve en tiempo de ejecución, nunca exponiendo secretos en la configuración almacenada.