# Vue d'ensemble

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

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.

<Callout type="tip" title="Essayer en direct">
La console interactive de l'API (`/api/docs`) permet d'appeler chaque route depuis le navigateur : cliquez sur « Authorize » et collez une clé **de sandbox**. La spécification brute est sur [`/openapi.json`](/openapi.json).
</Callout>

## Adresse et version

```text
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](/docs/changelog).

## 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](/docs/authentication). 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](/docs/errors).

## 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](/docs/api/logs).

## Idempotence

`POST /messages` accepte un en-tête `Idempotency-Key`. Voir [Fiabilité](/docs/guides/reliability).

## 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.