Endpoints
Clé requise :
GET avec toutes les clés ; POST en lecture-écriture (une clé en lecture seule reçoit 403 Not authorized to access this resource). Voir Types de clé.
Le modèle : une semaine à la fois
Avest raisonne en semaine ISO (year + weekNumber), du lundi au dimanche,
en matin / après-midi / journée. Si votre outil raisonne en mois et en dates,
c’est à vous de convertir avant d’appeler.
Un appel = une semaine. Le corps décrit l’état complet de cette semaine :
tout créneau que vous n’envoyez pas est supprimé. Rejouer le même corps donne le
même résultat — la route est idempotente.
L’écriture ne touche que la semaine visée. Les autres semaines, et les
plannings récurrents (« semaine type »), ne sont jamais modifiés.
Écrire une semaine
Corps de la requête
Chaque entrée de
shifts :
Réponse
Désigner un collaborateur
Par son identifiant Avest, jamais par son nom. Récupérez l’annuaire une fois via GET Users et conservez nosid de votre côté.
Une semaine vide, c’est explicite
Une agence fermée toute une semaine est un cas légitime. Unshifts vide par
bug de votre côté ne l’est pas — et les deux se ressemblent.
Une semaine vide est donc refusée, sauf si vous le dites :
Vérifier avant que ça compte
Deux outils, à utiliser dans cet ordre lors de votre mise en service.1
Simuler
dryRun: true fait passer toutes les validations et renvoie les
compteurs, sans rien écrire. Les mêmes erreurs qu’un vrai appel, sans le
risque.2
Relire
Le
GET renvoie ce qui est réellement enregistré pour la semaine, avec le
nom des collaborateurs — de quoi comparer à votre écran avant de brancher
l’automatisation.GET ne renvoie que les créneaux datés de la semaine demandée — pas ceux
d’une semaine type.
Warnings
Un warning ne fait pas échouer l’appel : l’écriture a bien eu lieu. Il signale un créneau qui ne servira à rien.Erreurs
L’appel est tout ou rien par semaine : en cas d’erreur, rien n’est écrit. Toutes en400, sauf mention contraire.
« Agency runs on a recurring planning »
Une agence est paramétrée soit sur un planning qui se répète (semaine type), soit sur un planning saisi semaine par semaine. Les deux régimes sont exclusifs. Si l’agence est en semaine type, un planning daté serait enregistré puis ignoré par l’attribution : la route refuse plutôt que de vous laisser pousser dans le vide. Le régime se change dans les réglages de l’agence, dans Avest.Rate limits
POST: 100 req / minute par groupe d’agences (bucket d’écriture commun).GET: 500 req / minute par groupe d’agences (bucket de lecture commun).
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. Dépassement
→ 429 avec Retry-After.