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.