> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookivox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégrations (API)

> Connecter et utiliser les intégrations via l'API : exemple Calendly (OAuth, event types, toolset) et découverte des intégrations disponibles.

## Vue d'ensemble

Les intégrations se **configurent** et se **pilotent** via l'API (clé API), sous
`/api/v1/api`.

## Calendly

### Objectif

1. Connecter Calendly (OAuth)
2. Choisir un `event_type` (type de RDV)
3. Générer les outils Bookivox associés (toolset)
4. Utiliser ces outils dans l'agent

### Endpoints (clé API)

| Action | Endpoint |
| - | - |
| Démarrer l'OAuth | `GET /integrations/calendly/oauth/start` |
| Lister les connexions | `GET /integrations/calendly/connections` |
| Lister les event types | `GET /integrations/calendly/event-types` |
| Sélectionner un event type | `POST /integrations/calendly/select-event-type` |
| Créer le toolset | `POST /integrations/calendly/toolset` |
| État de la connexion | `GET /integrations/calendly/smoke` |

### Étape 1 : Démarrer l'OAuth

`GET /api/v1/api/integrations/calendly/oauth/start`

Query params (optionnels) : `return_to`, `credential_uuid`, `connection_name`.

* Si l'en-tête `Accept: application/json` est présent, la réponse est JSON :

```json theme={null}
{ "authorize_url": "https://auth.calendly.com/oauth/authorize?..." }
```

* Sinon, le backend renvoie une redirection `302` vers `authorize_url`.

Erreurs : `400` `Organization not selected`, `500` `Calendly OAuth not configured`.

### Étape 2 : Autorisation utilisateur

Le navigateur va sur Calendly, puis revient automatiquement à la documentation
une fois l'autorisation accordée.

### Étape 3 : Vérifier la connexion

`GET /api/v1/api/integrations/calendly/connections`

```json theme={null}
{
  "connections": [
    {
      "credential_uuid": "...",
      "name": "Calendly",
      "calendly_email": "...",
      "calendly_timezone": "Europe/Paris",
      "selected_event_type_uri": null,
      "selected_event_type_name": null,
      "ready": false
    }
  ]
}
```

`ready=false` signifie qu'il faut choisir un event type.

### Étape 4 : Lister les event types

`GET /api/v1/api/integrations/calendly/event-types`

* `400` s'il existe plusieurs connexions et que `credential_uuid` est absent.
* `404` si Calendly n'est pas connecté.

### Étape 5 : Sélectionner et générer les outils

`POST /api/v1/api/integrations/calendly/select-event-type`

```json theme={null}
{
  "credential_uuid": "...",
  "event_type_uri": "https://api.calendly.com/event_types/...",
  "default_timezone": "Europe/Paris"
}
```

Réponse :

```json theme={null}
{ "tools": { "find_slots": "<tool_uuid>", "book": "<tool_uuid>" } }
```

### Étape 6 : Utiliser les outils dans l'agent

Les outils sont des ressources Bookivox :

* récupérer un outil : `GET /api/v1/api/tools/{tool_uuid}`
* associer/activer les outils dans la configuration du workflow.

## Découvrir toutes les intégrations

Utilisez le **catalogue node-types** : `GET /api/v1/api/node-types`, qui décrit
les intégrations disponibles et leurs champs.

## Voir aussi

* Guide produit : [Calendly](https://docs.bookivox.com/integrations/calendly.md)
* [MCP](https://docs.bookivox.com/mcp/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.