Référence API

Vue d'ensemble

Conventions de l'API REST : adresse, versions, authentification, format des erreurs, pagination, identifiants et dates.

Mis à jour le 12 novembre 2026Voir en Markdown

La référence complète est générée à partir de la spécification OpenAPI réelle de l'API : elle ne peut pas en diverger. Chaque opération est accompagnée d'un exemple d'appel (curl, Node.js, Python, PHP) et de la réponse réelle enregistrée depuis l'API.

Adresse et version#

texte

https://VOTRE-HOTE/api/v1

La version majeure est dans l'adresse (/v1). Les changements qui ne cassent pas les intégrations (nouveaux champs, nouvelles routes, nouveaux événements) sont ajoutés à /v1 : ignorez les champs inconnus dans vos réponses. Un changement incompatible donnerait une nouvelle version. Voir le journal des changements.

Authentification#

Authorization: Bearer <jeton>. Deux sortes de jetons : la session de la console (ses_…) et la clé API (pk_test_…, pk_live_…). Voir Authentification et clés. Chaque opération indique celle qu'elle exige et la portée requise. Les routes à clé acceptent aussi la session de la console, avec un en-tête X-Environment-Id.

Format des requêtes et des réponses#

Corps en JSON (Content-Type: application/json), en UTF-8.
Identifiants : UUID, sauf les identifiants Meta (wabaId, phoneNumberId à la connexion), qui sont des chaînes de chiffres.
Dates : ISO 8601, en UTC (2026-11-12T06:09:17.388Z).
Champs inconnus dans une requête : rejetés (400 validation_error), pour détecter vite une faute de frappe.
Les ressources d'un autre compte ou d'un autre environnement répondent 404, comme si elles n'existaient pas.

Erreurs#

Toutes les erreurs ont le même format, quelle que soit leur origine :

json

{
  "error": {
    "code": "validation_error",
    "message": "Requête invalide : voir details",
    "details": ["email must be an email"],
    "requestId": "req_0a1b2c3d-…"
  }
}

Champ	Description
`code`	Identifiant stable, à utiliser dans votre code.
`message`	Explication lisible, en français. Ne pas analyser son texte.
`details`	(validation) La liste des champs en cause.
`requestId`	À communiquer au support. Identique à l'en-tête `X-Request-Id` de la réponse.

Liste complète : Codes d'erreur.

Pagination#

Les listes longues sont paginées par curseur, du plus récent au plus ancien.

json

{ "data": [ … ], "nextCursor": "MjAyNi0xMS0xMlQw…" }

Tant que nextCursor n'est pas null, passez-le dans ?cursor= pour obtenir la page suivante. ?limit= fixe la taille de page (1 à 100 ; 1 à 200 pour les journaux). Ne construisez jamais un curseur vous-même.

Identifiant de requête#

Chaque réponse porte un en-tête X-Request-Id. Vous pouvez fournir le vôtre (8 à 64 caractères : lettres, chiffres, ., _, -) pour corréler vos journaux avec les nôtres. Il apparaît dans le journal des appels.

Idempotence#

POST /messages accepte un en-tête Idempotency-Key. Voir Fiabilité.

Appels depuis un navigateur#

L'API est faite pour être appelée depuis votre serveur. Les appels depuis un navigateur (CORS) ne sont pas autorisés : une clé API placée dans une page web serait publique.