# Conventions de l'API

> Format des requêtes et des erreurs, validation stricte, identifiants, pagination, filtres, idempotence, CORS, tailles, délais et évolution de l'API.

Ces règles valent pour tous les endpoints de l'API publique `https://api.wakastart.app/api`. Les pages de domaine ne signalent que ce qui s'en écarte.

## Format des requêtes et des réponses

- Les corps de requête et de réponse sont en JSON, encodés en UTF-8. Envoyez `Content-Type: application/json`.
- Les envois de fichiers utilisent `multipart/form-data`, avec le fichier dans le champ `file`.
- Les dates sont au format ISO 8601, en UTC : `2026-10-23T09:12:44.512Z`.
- Les montants de paiement sont en centimes, dans des champs suffixés `Cents` : `unitAmountCents: 4900` vaut 49,00.

## Identifiants

La plupart des objets ont deux identifiants :

| Identifiant | Format | Exemple | Usage |
|---|---|---|---|
| UUID | 36 caractères | `3f9a6c2e-1b7d-4c55-9e0a-6b2f4d8a1c01` | Identifiant technique, attendu dans les champs nommés `…Id` |
| [WID](/v1.0/glossaire#wid) | 6 caractères alphanumériques | `EXCLI1` | Identifiant court, attendu dans les champs et chemins nommés `…Wid` ou `:wid` |

Chaque paramètre indique lequel il attend. Quelques chemins acceptent l'un ou l'autre ; ils le signalent.

## Validation des champs

L'API valide chaque corps de requête et chaque paramètre de requête contre la liste des champs déclarés :

- un champ inconnu est **refusé**, avec `400` et le message `property <nom> should not exist` ;
- un champ obligatoire absent, un type incorrect ou une contrainte non respectée donnent `400` ;
- les paramètres de requête sont convertis vers le type attendu : `?limit=20` est lu comme le nombre 20, `?isActive=true` comme un booléen.

N'envoyez donc que les champs documentés. Un client qui recopie un objet lu par l'API pour le renvoyer tel quel en modification sera refusé : construisez le corps de la modification champ par champ.

## Erreurs

Toute erreur est renvoyée avec un statut HTTP 4xx ou 5xx et ce corps :

```json
{
  "statusCode": 403,
  "message": "Droit applicatif requis : users.read",
  "error": "Forbidden",
  "timestamp": "2026-10-23T09:12:44.512Z",
  "path": "/api/config/users"
}
```

| Champ | Type | Description |
|---|---|---|
| `statusCode` | entier | Statut HTTP, identique à celui de la réponse |
| `message` | chaîne ou tableau de chaînes | Cause de l'erreur. Pour une erreur de validation, un tableau avec un message par champ en défaut |
| `error` | chaîne | Libellé générique de l'erreur. Indicatif : fondez votre traitement sur `statusCode` et `message` |
| `timestamp` | chaîne ISO 8601 | Date de l'erreur |
| `path` | chaîne | Chemin appelé, paramètres de requête compris |

Exemple d'erreur de validation :

```json
{
  "statusCode": 400,
  "message": ["property nickname should not exist", "email must be an email"],
  "error": "Bad Request",
  "timestamp": "2026-10-23T09:12:44.512Z",
  "path": "/api/config/users"
}
```

Une erreur produite par un service interne de Wakastart vous est transmise avec son statut et son message d'origine. Une erreur inattendue donne `500` avec le message générique `Internal server error`, sans détail technique. Chaque statut est détaillé dans [Codes d'erreur](/v1.0/codes-d-erreur).

## Pagination

Plusieurs formats de pagination coexistent selon le domaine. Chaque endpoint de liste indique le sien.

| Format | Paramètres | Réponse | Utilisé par |
|---|---|---|---|
| Page et taille | `page` (≥ 1, défaut 1), `limit` (1 à 100, défaut 20) | `{ "data": [...], "meta": { "page", "limit", "total", "totalPages" } }` | Utilisateurs, clients, réseaux, équipes, profils, invitations |
| Page et taille, réponse à plat | `page` (défaut 1), `limit` (1 à 100, défaut 20) | `{ "data": [...], "total", "page", "limit", "totalPages" }` | Journal d'audit |
| Page et taille par page | `page` (défaut 1), `perPage` (1 à 100, défaut 20) | `{ "items": [...], "total", "page", "perPage" }` | Membres d'une organisation |
| Curseur | `startingAfter` (identifiant du dernier élément reçu), `limit` (1 à 100) | `{ "data": [...], "hasMore", "nextCursor" }` | Factures et abonnements de l'utilisateur final |
| Aucune | — | Liste complète | Thèmes, langues et traductions d'une application, membres d'une équipe, droits d'un profil |

Pour parcourir une liste paginée par page, incrémentez `page` jusqu'à `totalPages`. Pour une liste à curseur, rappelez l'endpoint avec `startingAfter` égal à `nextCursor` tant que `hasMore` vaut `true`.

```ts
async function* allUsers(token: string) {
  for (let page = 1; ; page++) {
    const res = await fetch(`https://api.wakastart.app/api/config/users?page=${page}&limit=100`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    if (!res.ok) throw new Error(`API ${res.status}`);
    const { data, meta } = await res.json();
    yield* data;
    if (page >= meta.totalPages) return;
  }
}
```

## Filtres et tri

- Les listes de l'organisation acceptent des filtres de portée : `partnerWid`, `networkWid`, `customerWid` (6 caractères au plus) ou leurs équivalents UUID `partnerId`, `networkId`, `customerId`.
- Pour un appel par [clé API](/v1.0/reference-api/cles-api), ces filtres sont **remplacés** par la portée de la clé : son client, sinon son réseau, sinon son application.
- Les filtres propres à chaque liste (`isActive`, `status`, `action`…) sont décrits avec l'endpoint.
- L'API n'expose **aucun paramètre de tri**.

## Idempotence

- Les créations de paiement (sessions Checkout, achat de pack de crédits) exigent un champ `idempotencyKey` dans le corps, de 180 caractères au plus. Rejouer la même clé ne crée pas de seconde session. Générez une clé par intention d'achat, par exemple un UUID stocké avec la commande.
- Les endpoints du module [HDS](/v1.0/reference-api/hds) acceptent l'en-tête `Idempotency-Key` sur `POST`, `PUT` et `PATCH` : la réponse est rejouée pendant 24 heures, avec l'en-tête `X-Idempotency-Replayed: true`.
- Ailleurs, l'API n'offre pas d'idempotence : rejouer une création peut produire un doublon ou une erreur `409` (utilisateur ou invitation déjà existants). Avant de réessayer une création qui a échoué sur un délai dépassé, vérifiez par une lecture si l'objet existe.

## Limites de débit

L'API limite le nombre de requêtes **par adresse IP**, sur trois fenêtres simultanées :

| Fenêtre | Limite |
|---|---|
| 1 seconde | 10 requêtes |
| 1 minute | 100 requêtes |
| 1 heure | 1 000 requêtes |

Exceptions :

| Endpoint | Limite |
|---|---|
| `GET /api/invitations/verify/{token}`, `POST /api/invitations/accept/{token}` | 60 par seconde, 600 par minute, 5 000 par heure |
| `POST /api/token/enrich` | Aucune limite |

Au-delà, l'API répond `429` avec le message `ThrottlerException: Too Many Requests`. La réponse porte un en-tête par fenêtre dépassée, `Retry-After-short`, `Retry-After-medium` ou `Retry-After-long`, qui indique le nombre de secondes à attendre ; un navigateur ne peut pas les lire en appel croisé. Attendez ce délai, ou à défaut réessayez avec un délai croissant (1 s, 2 s, 4 s…). Si plusieurs instances de votre service sortent par la même adresse IP, elles partagent ces compteurs. Discovery a ses propres limites, décrites dans [Discovery](/v1.0/reference-api/discovery#limites-de-débit). Toutes les valeurs sont regroupées dans [Limites et quotas](/v1.0/limites).

## CORS et appels depuis un navigateur

L'API publique n'accepte les appels d'un navigateur que depuis les origines que Wakastart a déclarées pour elle. Les en-têtes acceptés en appel croisé sont `Content-Type`, `Authorization` et `x-api-key` ; `x-enriched-token` n'en fait pas partie.

Nous recommandons d'appeler l'API depuis le serveur de votre application, qui ajoute le jeton de l'utilisateur. Si votre front doit l'appeler directement, envoyez le jeton Keycloak dans `Authorization` et demandez à Wakastart d'autoriser l'origine de votre front.

## Tailles maximales

| Contenu | Taille maximale |
|---|---|
| Corps JSON ou formulaire | 1 Mo |
| Fichier envoyé à l'antivirus | 100 Mo |
| Fichier envoyé au module HDS | 100 Mo |
| Fichier CSV d'import d'utilisateurs | 2 Mo et 500 lignes |
| Jeton passé dans un corps de requête | 10 000 caractères |

Un fichier qui dépasse la taille maximale est refusé avec `413`.

## Délais d'attente

L'API relaie chaque requête vers un service interne de Wakastart et attend sa réponse 5 à 10 secondes pour la plupart des endpoints, 60 secondes pour le module HDS et 120 secondes pour l'envoi d'un fichier à l'antivirus ou la traduction par IA. Fixez le délai de votre client HTTP au-dessus de ces valeurs.

## Évolution de l'API

L'API publique n'a pas de numéro de version, ni dans l'URL, ni dans un en-tête. Les évolutions sont publiées dans les [notes de version](/v1.0/notes-de-version). Pour que votre intégration résiste aux ajouts :

- ignorez les champs de réponse que vous ne connaissez pas ;
- n'attendez pas un ordre précis des éléments d'une liste ;
- traitez une valeur d'énumération inconnue comme un cas par défaut.

## État de l'API

::endpoint{method="GET" path="/api/healthz"}

Public. Indique que l'API répond.

```bash
curl -s https://api.wakastart.app/api/healthz
```

```json
{
  "status": "ok",
  "timestamp": "2026-10-23T09:12:44.512Z",
  "uptime": 86400,
  "service": "ws-back-api",
  "version": "1.0.0"
}
```
