Passer au contenu principal
Si vous tenez déjà vos plannings de permanence dans votre outil, vous pouvez les pousser dans Avest au lieu de les ressaisir. Deux routes : une pour écrire une semaine, une pour la relire.
Le planning de permanence pilote l’attribution des leads entrants. Un créneau sans personne de permanence envoie les leads de ce créneau à la pioche, au lieu du négociateur attendu. Traitez ces routes comme une écriture sensible, pas comme un réglage d’affichage.

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 :
Tout champ de corps non listé → 400.

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 nos id de votre côté.
Le rapprochement sur prénom + nom n’est pas supporté, et pour de bonnes raisons : il casse au premier homonyme, au premier départ, au premier nom composé — et il vous ferait affecter les leads à la mauvaise personne sans aucune erreur visible.

Une semaine vide, c’est explicite

Une agence fermée toute une semaine est un cas légitime. Un shifts 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.
Le 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 en 400, 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.
Corollaire, une fois l’agence en semaine par semaine : une semaine que vous n’alimentez pas n’a aucun collaborateur de permanence. Poussez vos semaines à l’avance, et surveillez votre propre synchronisation.

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).
Headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. Dépassement → 429 avec Retry-After.