# Authentification, erreurs et conventions REST

Les règles communes à respecter avant d’intégrer une ressource.

## Adresses et identités

Les ressources REST documentées utilisent `/api/v1`. La plateforme peut accepter l'hôte technique et l'hôte de l'organisation pour un jeton d'app ; utilisez la base fournie pour votre déploiement. Le jeton porte l'organisation : le client ne choisit pas une autre organisation par un paramètre arbitraire.

Deux principaux utilisent la surface REST : une app connectée avec scopes et périmètre, ou un utilisateur avec une session portée en Bearer et ses droits effectifs. Les jetons OAuth personnels `coa_` des assistants sont destinés au MCP ; ne les assimilez pas à des jetons REST.

## Formats

Les corps utilisent JSON UTF-8, les champs `camelCase` et les identifiants UUID. Les horodatages sont ISO 8601, les dates civiles `YYYY-MM-DD`. La représentation exacte d'un montant dépend du schéma de l'opération : de nombreuses ressources emploient des chaînes décimales, certains agrégats des nombres. Ne convertissez pas implicitement en centimes.

Un PATCH omet les champs à conserver. `null`, une chaîne vide et un champ absent n'ont pas nécessairement le même sens : consultez le schéma. Les champs calculés ou tenus par un référentiel ne s'écrivent pas librement.

## Pagination et filtres

Les listes courantes renvoient `data` et `nextCursor`. Le défaut REST est 50 et le plafond courant 200 ; certaines listes ont un contrat particulier. Repassez le curseur sans le décoder. Un curseur invalide ou périmé demande de repartir du début.

Les filtres sont propres à chaque route. Les conventions incluent `q`, `updatedSince`, `cycleId`, `businessUnitId` et `ids` répété. N'envoyez pas un filtre simplement parce qu'une autre ressource le connaît.

## Erreurs

L'API utilise `application/problem+json` avec `type`, `title`, `status`, éventuellement `detail`, `errors` et un identifiant `instance` pour la corrélation. Testez le type stable et le statut, pas la formulation humaine du message.

| Statut | Première vérification |
|---|---|
| 400 | Corps, paramètre ou curseur invalide |
| 401 | Jeton absent, expiré, révoqué ou incorrect |
| 403 | Scope, droit ou capacité insuffisants |
| 404 | Ressource absente ou hors visibilité |
| 409 | Conflit de version, d'état ou d'idempotence |
| 422 | Validation métier ou champ non modifiable |
| 429 | Limite atteinte ; respecter Retry-After |

L'endpoint de jeton répond au format d'erreur OAuth. Le MCP répond au format JSON-RPC : ne lui appliquez pas aveuglément le parseur REST.

## Idempotence et concurrence

Pour les POST pris en charge sous identité d'app, envoyez `Idempotency-Key` avec une valeur stable par opération logique. La même clé et le même corps rejouent la réponse ; un corps différent sous la même clé provoque un conflit. La mémoire dure 24 heures et est isolée par app. Le contexte de session utilisateur ignore ce header : le canal mobile dispose de son propre contrat de synchronisation.

Quand un schéma demande `expectedUpdatedAt`, lisez d'abord la fiche puis fournissez cette version. Sur conflit, relisez et décidez comment appliquer le changement ; ne remplacez pas aveuglément la valeur attendue pour écraser le travail d'un collègue.

## Limites et reprise

REST et MCP d'une même app partagent leur limite par identité. Des limites d'organisation et de consommation s'ajoutent. Respectez `Retry-After`, limitez la concurrence et espacez les reprises. Une réponse de validation n'est pas un incident transitoire à réessayer en boucle.