> ## 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 Flowella v1 — tout ce qu'il faut savoir avant votre premier appel. L'API REST Flowella vous permet d'envoyer des messages WhatsApp, de gérer les contacts et les opt-outs, de lister et d'envoyer en masse des modèles, et d'extraire des analyses — par programmation. Cette page couvre tout ce que vous devez savoir avant d'appeler un point de terminaison. La référence complète des endpoints se trouve dans la barre latérale **Référence de l'API** (générée automatiquement à partir de la [spécification OpenAPI](/api-reference/openapi.json)). ## URL de base ``` https://api.flowella.io/v1 ``` Tous les endpoints v1 sont sous cette base canonique — par exemple `https://api.flowella.io/v1/messages`. L'API se trouvait auparavant sur l'hôte de l'application à l'adresse `https://app.flowella.io/api/v1/...`. Les requêtes legacy vers ce chemin sont redirigées de façon permanente (`308`) vers l'URL canonique `https://api.flowella.io/v1/...`, en préservant la méthode et le corps — ainsi, les intégrations existantes continuent de fonctionner. Mettez à jour votre URL de base quand vous en aurez l'occasion pour éviter le saut supplémentaire. ## Authentification Chaque requête a besoin d'une clé API dans l'en-tête `Authorization` : ```http theme={null} Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx ``` Les clés sont limitées à une organisation — elles agissent sur une seule organisation Flowella et héritent des permissions d'un Administrateur dans cette organisation. Traitez les clés comme des mots de passe. Ne les commitez jamais dans le contrôle de version, ne les collez jamais dans un chat ou dans des docs partagées, et faites-les tourner lorsque des coéquipiers quittent l'organisation. Voir [Réglages → Clés API](/fr/settings/api-keys) pour les étapes de rotation. ### Créer une clé Vous devez avoir le rôle **Propriétaire** ou **Administrateur** 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émorisable. 3. Copiez la clé une fois — elle n'est affichée qu'à la création. Traitez les clés comme des mots de passe : ne les commitez jamais dans le contrôle de version, ne les collez jamais dans un chat et faites-les tourner lorsque des coéquipiers quittent l'organisation. ### Vérifier une clé Appelez l'endpoint ping pour confirmer qu'une clé est valide : ```bash cURL theme={null} curl https://api.flowella.io/v1/ping \ -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" ``` ```js Node.js theme={null} await fetch("https://api.flowella.io/v1/ping", { headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` }, }); ``` ```python Python theme={null} import os, requests requests.get( "https://api.flowella.io/v1/ping", headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"}, ) ``` Un `200 OK` avec `{ "ok": true, "organizationId": "…" }` signifie que vous êtes authentifié. ## Erreurs Toutes les erreurs reviennent dans une enveloppe cohérente : ```json theme={null} { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" } } ``` | Statut HTTP | Quand vous le verrez | | - | - | | `400` | Échec de validation, corps mal formé ou rejet Meta en amont | | `401` | Clé API manquante ou invalide | | `402` | Paiement requis — votre abonnement ne couvre pas l'action | | `403` | Interdit — par exemple, envoi à un contact opté-out, ou Meta n'est pas connecté | | `404` | Le canal ou la ressource demandé n'existe pas | | `429` | Débit limité — ralentissez | Le champ `error.code` est stable et sûr pour être utilisé programmatiquement dans un `switch`. Le champ `error.message` est lisible et peut changer. ## Limites de débit Les clés API sont limitées en débit par organisation. Si vous dépassez la limite, vous obtiendrez un `429` avec le code `RATE_LIMITED` et le message `Too many requests`. Lorsqu'il est présent, l'en-tête de réponse `Retry-After` vous indique combien de secondes attendre. Faites du backoff et réessayez avec un délai exponentiel. Si vous exécutez de gros envois en masse, préférez **`POST /v1/templates/send`** avec le paramètre `throttlePerHour` — Flowella applique le throttling côté serveur, donc vous n'avez pas besoin de cadencer les requêtes vous-même. ## Clés d'idempotence Les envois de modèles en masse sont asynchrones. `POST /v1/templates/send` valide la requête, la met en file de manière durable et renvoie immédiatement `202 Accepted` : ```json theme={null} { "id": "v1ts-0123456789abcdef", "status": "accepted" } ``` Flowella délivre le lot en arrière-plan et réessaie automatiquement les erreurs WhatsApp temporaires. Les destinataires sont traités individuellement, donc un numéro invalide ne bloque pas le reste du lot. Suivez la progression de la livraison sur l'onglet **Statistiques** du modèle dans l'application. Comme la livraison se fait après la réponse, les réessais doivent être sûrs. Passez un en-tête `Idempotency-Key` (jusqu'à 200 caractères) qui identifie de manière unique chaque lot : ```bash theme={null} curl -X POST "https://api.flowella.io/v1/templates/send" \ -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Idempotency-Key: campaign-2026-08-31-launch" \ -H "Content-Type: application/json" \ -d '{ "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx", "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx", "recipients": [{ "phone": "+15551234567" }] }' ``` Les répétitions de la même clé dans les sept jours renvoient l'`id` de job original au lieu de créer un nouvel envoi. Vous pouvez réessayer une requête en toute sécurité après un timeout ou une erreur réseau sans envoyer de messages en double. Si vous omettez l'en-tête, Flowella dérive une clé à partir du corps de la requête. Un lot identique soumis deux fois en peu de temps n'est donc pas envoyé deux fois. Une clé explicite reste plus sûre, car toute modification du corps (même réordonner les destinataires) produit une nouvelle clé dérivée. ## Pagination Les endpoints de liste (`/conversations`, `/contacts`, `/templates`) utilisent une **pagination par curseur** : * Passez `limit` (1 à 100, défaut 25) et un `cursor` optionnel. * La réponse contient `items` et, s'il y a plus de résultats, un `nextCursor`. * Repassez `nextCursor` comme paramètre `cursor` pour récupérer la page suivante. * Lorsque `nextCursor` est absent, vous avez atteint la fin. ```bash theme={null} curl "https://api.flowella.io/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`). Là où l'API accepte des dates, à la fois le format date seule (`2025-01-15`) et l'ISO 8601 complet sont convertis côté serveur. ## Numéros de téléphone Passez les numéros de téléphone au format **E.164** (`+15551234567`) lorsque c'est possible. Flowella normalisera les variations courantes côté serveur, mais E.164 est le plus sûr. ## Canaux De nombreux endpoints acceptent un `whatsappChannelId`. Si votre organisation possède 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 depuis le mauvais expéditeur. Pour le modèle d'URL complet et le changement de canal, voir [Multi-canal](/fr/essentials/multi-channel). ## Spécification OpenAPI La spécification lisible par machine se trouve à : ``` /api-reference/openapi.json ``` Déposez-la dans Postman, Insomnia ou votre générateur de code préféré. Vous construisez une intégration ? Associez cette page à [Webhooks](/fr/api-reference/webhooks) pour réagir aux événements plutôt que de faire du polling. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.