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

# Démarrer

> Apprenez à vous authentifier et à commencer à utiliser l'API d'automatisation Kameleoon.

L'**Automation API** est un service conforme à REST qui vous permet d'effectuer de manière programmatique la plupart des actions disponibles dans l'interface web de Kameleoon. Utilisez l'Automation API pour créer des logiciels personnalisés qui interagissent avec la plateforme Kameleoon et ses fonctionnalités principales.

Par exemple, vous pouvez utiliser l'Automation API pour :

* Connecter Kameleoon à des dépôts Git pour gérer le code des variations.
* Concevoir des dashboards personnalisés alimentés par des résultats d'expériences en temps réel.
* Automatiser la création d'objectifs et de segments sur plusieurs projets.

<Warning>
  Kameleoon peut modifier les endpoints et les paramètres dans les nouvelles versions de l'Automation API. Abonnez-vous aux mises à jour sur le [changelog Kameleoon](https://changelog.kameleoon.com/en/) pour être notifié des changements planifiés.
</Warning>

<Warning>
  L'Automation API ne prend pas en charge des volumes de requêtes élevés. Limitez les appels à **12 fois par minute** par compte ou utilisateur. N'utilisez pas l'Automation API pour le suivi à haute fréquence de chaque visiteur de site Web. Pour des volumes de requêtes plus importants, utilisez la [Data API](../../data-api-rest/overview).
</Warning>

<Note>
  Contactez l'équipe Kameleoon pour demander une amélioration de l'Automation API. Nous apprécions vos retours et pouvons rapidement ajouter à l'API les fonctionnalités existantes de l'UI.
</Note>

## Tutoriels

### Créer une expérience

Ce tutoriel fournit des instructions étape par étape pour effectuer des tâches clés sur la plateforme Kameleoon. Vous apprendrez à :

* [Créer une nouvelle expérience](../tutorials/experiments/create-a-new-experiment)
* [Pousser et modifier du code JavaScript dans une variation](../tutorials/experiments/add-and-edit-javascript-in-the-variant-of-your-new-experiment)
* [Créer un nouveau segment](../tutorials/experiments/create-a-segment-to-target-visitors-by-page-url)
* [Créer un nouvel objectif](../tutorials/experiments/create-a-new-goal-for-an-experiment)
* [Mettre à jour et lancer une expérience](../tutorials/experiments/add-a-goal-and-segment-to-your-experiment-before-launching)

### Récupérer les résultats d'une expérience

Une fois que vous avez lancé une expérience, elle génère des résultats qui fournissent des informations permettant de déterminer la variation la plus performante. Apprenez à demander les résultats et à identifier la variation gagnante dans le tutoriel [Récupération des résultats d'expériences](../tutorials/experiments/retrieving-experiment-results-using-the-automation-api).

## Authentification

L'Automation API utilise le framework OAuth 2.0 pour l'autorisation. Kameleoon prend en charge deux flux principaux selon votre cas d'utilisation :

* **Client Credentials Flow** : Utilisez ce flux si vous êtes un client Kameleoon utilisant l'API à des fins internes. Ce flux vous permet de gérer de manière programmatique votre propre compte et vos propriétés Web.
* **Authorization Code Flow** : Utilisez ce flux si vous êtes un partenaire technologique intégrant une application avec Kameleoon. Ce flux vous permet d'accéder en toute sécurité aux données au nom d'autres utilisateurs Kameleoon.

### Flux Client Credentials

Le flux Client Credentials est la méthode d'authentification la plus simple. Pour utiliser ce flux, échangez vos identifiants client contre un token d'accès.

<Tip>
  Vous pouvez trouver vos `client_id` et `client_secret` sur la plateforme Kameleoon. Accédez à **Compte > Mon profil** et cliquez sur **Voir mes identifiants API**.
</Tip>

#### 1. Obtenir un token d'accès

Envoyez une requête POST à l'endpoint de token avec vos identifiants.

```bash curl theme={null}
curl -X POST "https://api.kameleoon.com/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET"
```

Le serveur d'autorisation répond avec un objet JSON contenant l'`access_token` :

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
}
```

#### 2. Accéder à l'API

Incluez le token d'accès en tant que token Bearer dans l'en-tête HTTP `Authorization` de vos requêtes.

```bash curl theme={null}
curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     "https://api.kameleoon.com/experiments"
```

* Les tokens d'accès restent valides pendant **2 heures** par défaut.
* Le flux Client Credentials n'utilise pas de refresh tokens.
* Vous devez utiliser **HTTPS** pour toutes les requêtes API. Les requêtes effectuées via HTTP en clair échoueront.

### Flux Authorization Code

Le flux Authorization Code permet aux développeurs tiers d'intégrer leurs applications avec les données Kameleoon. Vous devez obtenir l'autorisation explicite d'un utilisateur pour accéder aux ressources de son compte.

<Note>
  Contactez votre Kameleoon Technical Account Manager pour demander une application OAuth. Vous devez fournir une URL de redirection pour votre application. Kameleoon fournira ensuite un `client_id` et un `client_secret`.
</Note>

#### 1. Rediriger l'utilisateur pour l'autorisation

Redirigez les utilisateurs de votre application vers l'URL d'autorisation :

```https theme={null}
https://api.kameleoon.com/oauth/authorize?client_id=my-application-name&response_type=code&redirect_uri=https://application.company.com/
```

Une fois que l'utilisateur a accordé l'autorisation, Kameleoon redirige l'utilisateur vers l'URL de votre application avec un code d'autorisation :

```https theme={null}
https://application.company.com/?code=AUTHORIZATION_CODE
```

#### 2. Obtenir des tokens d'accès et de rafraîchissement

Échangez le code d'autorisation contre des tokens. Encodez la chaîne `client_id:client_secret` en Base64 et incluez-la dans l'en-tête `Authorization: Basic`.

```bash curl theme={null}
curl -X POST "https://api.kameleoon.com/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic <BASE64_ENCODED_CREDENTIALS>" \
     -d "grant_type=authorization_code" \
     -d "code=AUTHORIZATION_CODE" \
     -d "redirect_uri=https://application.company.com/"
```

La réponse contient à la fois des tokens d'accès et de rafraîchissement :

```json theme={null}
{
  "access_token": "...",
  "refresh_token": "..."
}
```

#### 3. Rafraîchir un token expiré

Pour obtenir un nouveau token d'accès sans ré-autoriser l'utilisateur :

```bash curl theme={null}
curl -X POST "https://api.kameleoon.com/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic <BASE64_ENCODED_CREDENTIALS>" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=YOUR_REFRESH_TOKEN"
```

## Limitation de débit

La limitation de débit pour l'Automation API s'applique par token d'accès utilisateur. Kameleoon utilise deux fenêtres de limitation de débit :

* **Intervalle de 10 secondes** : Jusqu'à 50 requêtes.
* **Intervalle d'1 heure** : Jusqu'à 1 000 requêtes.

Si vous dépassez ces limites, l'API renvoie une erreur `HTTP 429 Too Many Requests`. Pour minimiser la limitation de débit :

* **Implémentez la mise en cache** : Stockez les réponses API localement et évitez d'appeler l'API à chaque chargement de page.
* **Utilisez la Data API** : Si votre application nécessite un suivi en temps réel à grande échelle, utilisez la [Data API](../../data-api-rest/overview).

## Codes d'état HTTP

| Code | Statut            | Description                                                                                                   |
| :--- | :---------------- | :------------------------------------------------------------------------------------------------------------ |
| 200  | OK                | La requête a réussi.                                                                                          |
| 201  | Created           | La ressource a été créée avec succès.                                                                         |
| 400  | Bad Request       | Le corps de la requête est invalide. Assurez-vous que l'en-tête `Content-Type: application/json` est présent. |
| 401  | Unauthorized      | Le token API est manquant ou mal formé.                                                                       |
| 403  | Forbidden         | Vous manquez d'autorisations requises ou le token est révoqué.                                                |
| 429  | Too Many Requests | Vous avez dépassé la limite de débit.                                                                         |
| 5xx  | Server Error      | Une erreur interne s'est produite. Contactez le support Kameleoon si le problème persiste.                    |

## Paramètres de requête

Pour les endpoints qui récupèrent plusieurs objets, utilisez les paramètres de requête pour paginer, filtrer ou trier les données.

### Pagination

Les requêtes renvoient **20 éléments par page** par défaut (maximum 200). Utilisez `perPage=-1` pour récupérer la limite maximale.

| Paramètre | Type    | Description                                 |
| :-------- | :------ | :------------------------------------------ |
| `page`    | integer | Le numéro de page à récupérer.              |
| `perPage` | integer | Éléments par page (par défaut 20, max 200). |
| `filter`  | array   | Paramètres de filtrage.                     |
| `sort`    | array   | Paramètres de tri.                          |

### Filtrage

Vous devez encoder en pourcentage les filtres lors de leur envoi dans une URL.
**Exemple** : `filter=[{"field":"name","operator":"EQUAL","parameters":["Test"]}]`

| Champ        | Type   | Description                                                                                   |
| :----------- | :----- | :-------------------------------------------------------------------------------------------- |
| `field`      | string | Le champ par lequel filtrer.                                                                  |
| `operator`   | enum   | Les options incluent : `EQUAL`, `NOT_EQUAL`, `LESS`, `GREATER`, `LIKE`, `IN`, `IS_NULL`, etc. |
| `parameters` | array  | Les valeurs spécifiques à faire correspondre.                                                 |

### Tri

| Champ       | Type   | Description                                |
| :---------- | :----- | :----------------------------------------- |
| `field`     | string | Le champ par lequel trier.                 |
| `direction` | enum   | `ASC` (croissant) ou `DESC` (décroissant). |