> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction à l'API
> Authentification, URL de base, codes d'erreur, pagination, limites de débit et clés d'idempotence pour l'API REST v1 de Flowella — tout ce qu'il vous faut avant votre premier appel.
L'API REST Flowella vous permet d'envoyer des messages WhatsApp, de gérer les contacts et les opt-outs, d'établir des listes et des modèles d'envoi en masse, et d'obtenir des analyses - de manière programmatique. Cette page couvre tout ce que vous devez savoir avant d'appeler un point de terminaison.
La référence complète du point de terminaison se trouve dans la barre latérale **Référence API** (générée automatiquement à partir de la [spécification OpenAPI](/api-reference/openapi.json)).
## URL de base
```
https://app.flowella.io
```
Tous les points de terminaison v1 sont sous `/api/v1`.
## Authentification
Chaque requête nécessite une clé API dans l'en-tête `Authorization` :
```http theme={null}
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
```
Les clés sont liées à l'organisation - elles agissent sur une seule organisation Flowella et héritent des permissions d'un administrateur de cette organisation.
Traitez les clés comme des mots de passe. Ne les livrez jamais au contrôle de source, ne les collez jamais dans le chat ou les documents partagés, et faites-en la rotation lorsque les coéquipiers quittent l'organisation. Voir [Settings → API keys](/fr/settings/api-keys) pour les étapes de rotation.
### Création d'une clé
Vous devez avoir le rôle **Owner** ou **Admin** pour gérer les clés API.
1. Allez dans **Réglages → Clés API** dans l'application Flowella.
2. Cliquez sur **Créer une clé** et donnez-lui un nom mémorable.
3. Copiez la clé une fois - elle n'est affichée qu'au moment de la création.
Traitez les clés comme des mots de passe : ne les soumettez jamais au contrôle de source, ne les collez jamais dans le chat et faites-en la rotation lorsque les coéquipiers quittent l'organisation.
### Vérification d'une clé
Appuyez sur le point de terminaison ping pour confirmer qu'une clé est valide :
```bash cURL theme={null}
curl https://app.flowella.io/api/v1/ping \
-H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
```
```js Node.js theme={null}
await fetch("https://app.flowella.io/api/v1/ping", {
headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});
```
```python Python theme={null}
import os, requests
requests.get(
"https://app.flowella.io/api/v1/ping",
headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)
```
Un `200 OK` avec un `{ "ok": true, "organizationId": "…" }` signifie que vous êtes authentifié.
## Erreurs
Toutes les erreurs sont renvoyées dans une enveloppe cohérente :
```json theme={null}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}
```
| Statut HTTP | Quand vous le verrez | | |
| ------------------------------------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------------------- |
| `400` | Validation failed, malformed body, or upstream Meta rejection | `400` | Validation failed, malformed body, or upstream Meta rejection |
| `401` | Clé API manquante ou invalide | | |
| `402` | Paiement requis - votre abonnement ne couvre pas l'action. | | |
| `403` | Interdit - par exemple, envoi à un contact exclu, ou Meta n'est pas connecté. | | |
| `404` | Le canal ou la ressource demandée n'existe pas. | | |
| `429` - Le canal ou la ressource demandée n'existe pas. | | | |
Le champ `error.code` est stable et peut être activé en toute sécurité par programmation. Le champ `error.message` est lisible par l'homme et peut changer.
## Limites de débit
Les clés API sont limitées par organisation. Si vous dépassez la limite, vous recevrez un `429` avec le code `RATE_LIMITED` et le message `Too many requests`. Revenez en arrière et réessayez avec un délai exponentiel.
Si vous effectuez des envois massifs, préférez **`POST /api/v1/templates/send`** avec le paramètre `throttlePerHour` - Flowella applique la limitation côté serveur, de sorte que vous n'avez pas besoin de rythmer les demandes vous-même.
## Pagination
Les points de terminaison de la liste (`/conversations`, `/contacts`, `/templates`) utilisent la **pagination du curseur** :
* Passez `limit` (1-100, par défaut 25) et un `cursor` optionnel.
* La réponse contient `items` et, s'il y a plus de résultats, `nextCursor`.
* Renvoyez `nextCursor` en tant que paramètre `cursor` pour récupérer la page suivante.
* Lorsque `nextCursor` est manquant, vous avez atteint la fin.
```bash theme={null}
curl "https://app.flowella.io/api/v1/conversations?limit=50" \
-H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
```
## Date et heure
Tous les horodatages sont des chaînes ISO 8601 en UTC (par exemple `2025-01-15T14:30:00.000Z`). Lorsque l'API accepte des dates, la date seule (`2025-01-15`) et la chaîne ISO 8601 complète sont forcées côté serveur.
## Numéros de téléphone
Transmettez les numéros de téléphone sous la forme **E.164** (`+15551234567`) dans la mesure du possible. Flowella normalisera les variations courantes côté serveur, mais E.164 est la forme la plus sûre.
## Canaux
De nombreux points d'accès acceptent un `whatsappChannelId`. Si votre organisation n'a qu'un seul canal et que vous l'omettez, Flowella utilise votre canal par défaut. Si vous avez plusieurs canaux, passez l'ID explicitement pour éviter d'envoyer à partir du mauvais expéditeur.
Pour le modèle d'URL complet et le changement de canal, voir [Multicanal](/fr/essentials/multi-channel).
## OpenAPI spec
La spécification lisible en machine se trouve à l'adresse suivante :
```
/api-reference/openapi.json
```
Déposez-la dans Postman, Insomnia, ou le générateur de code de votre choix.
Vous construisez une intégration ? Associez cette page à [Webhooks](/fr/api-reference/webhooks) pour réagir aux événements au lieu d'interroger l'état.