API publique et webhooks de la Planification

Vos outils peuvent lire le planning, y poser des brouillons et publier, par l’API publique v1 d’Illizeo. Les webhooks les préviennent quand un shift change. Cet article s’adresse aux personnes qui intègrent Illizeo à un autre logiciel.

Avant de commencer #

• Le module Planification doit être actif, pour l’espace et pour les employés concernés.
• L’API publique doit être comprise dans votre abonnement.
• Les jetons se créent dans Gérer Illizeo › Jetons API. La documentation de l’API y est accessible.
• Les webhooks se créent dans Gérer Illizeo › Webhooks.

Les portées du jeton #

Deux portées concernent la Planification :

• scheduling:read : lire les shifts, les offres et leurs candidatures, les disponibilités ;
• scheduling:write : poser, modifier et supprimer des brouillons, et publier.

Un jeton agit sous l’identité de la personne qui l’a créé. Il a ses droits et sa population, au même palier que dans l’écran :

• lire demande le droit « Planning : lire (Accès), poser et modifier les shifts (Exécuter) de sa population » (sch_planning) au palier Accès ;
• écrire un brouillon demande le palier Exécuter ;
• publier demande le palier Admin.

Un employé hors de cette population répond comme introuvable (404).

Les routes #

Lecture (scheduling:read) :

• GET /v1/scheduling/shifts : les shifts d’une période ;
• GET /v1/scheduling/shifts/{shift} : un shift ou une offre ;
• GET /v1/scheduling/open-shifts : les offres et leurs candidatures ;
• GET /v1/scheduling/availabilities : les disponibilités déclarées.

Écriture (scheduling:write) :

• POST /v1/scheduling/shifts : poser un brouillon ;
• PUT /v1/scheduling/shifts/{shift} : modifier un brouillon ;
• DELETE /v1/scheduling/shifts/{shift} : supprimer un brouillon ;
• POST /v1/scheduling/publications : publier un lot de brouillons.

Lire le planning #

Chaque lecture porte sur une période : from et to, au format AAAA-MM-JJ. La période compte au plus 43 jours, bornes comprises. Au-delà, l’API répond 422 (PERIODE_TROP_LONGUE).

GET /v1/scheduling/shifts accepte aussi des filtres : employee_id, employment_id (le contrat), office_id (le lieu), status et published. Les statuts sont draft, published, confirmed, rejected et cancelled. Les résultats sont paginés : 100 par page par défaut, 500 au plus (per_page, page).

Écrire : des brouillons seulement #

L’API passe par les mêmes contrôles que l’application : conflits, préavis court, droits, population.

• Brouillons seulement. Un intégrateur crée, modifie et supprime des brouillons. Un shift déjà diffusé se change dans Illizeo : l’API répond 409 (SHIFT_NON_BROUILLON).
• Pas de récurrence en v1. Une règle de récurrence (recurrence) ou une portée de série (scope) est refusée (422).
• Préavis court. Si la semaine commence bientôt, l’API répond 409 (PREAVIS_COURT). Renvoyez la requête avec confirm_short_notice: true pour confirmer.
• Dates du contrat. Un shift hors des dates du contrat est refusé (422), comme dans l’écran.

Publier #

POST /v1/scheduling/publications reçoit un nom de lot (name), une note facultative (note) et la liste des brouillons (shift_ids).

Si un circuit actif sur le déclencheur « Publication du planning » couvre la personne qui a créé le jeton, le lot attend sa décision : la réponse porte status = pending_approval. Sinon, le lot est publié aussitôt et les employés sont prévenus. C’est le cas par défaut : le circuit livré par Illizeo est inactif. Un circuit dont personne ne peut approuver le lot est annulé, et le lot publié directement. Voir Créer et publier un planning.

Les webhooks #

Abonnez un webhook à toute la famille Planification, ou à des événements précis.

• shift.published : un shift est publié, directement ou par le circuit. Un événement par shift du lot.
• shift.updated : un shift diffusé change (date, heures, contrat, lieu, poste ou statut, annulation comprise). Le champ changed dit lesquels.
• shift.unpublished : un shift diffusé redevient brouillon, par dépublication ou retrait du lot.
• shift.deleted : un shift diffusé est supprimé, ou rendu par l’employé.
• shift.confirmed et shift.rejected : la réponse de l’employé.
• open_shift.claimed : un shift naît d’une offre pour un employé (réclamation, candidature acceptée, attribution).
• shift.replacement_completed : un shift change de titulaire après une cession ou un échange. Un événement par shift transféré.
• shift.checked_in : le titulaire commence le shift.
• shift.completed : le titulaire termine le shift. Cet événement part une seule fois par shift.

shift.checked_in et shift.completed indiquent aussi outside_zone (geste hors de la zone du lieu) et mode (statut du shift ou pointage des Présences).

Ce que contient un événement #

Chaque événement porte le socle du shift : shift_id, employee_id, employment_id, date, start_time, end_time (HH:MM, dans le fuseau du planning), all_day, office_id, status, is_open et open_shift_id. Une offre (is_open) n’a ni employé ni contrat.

S’y ajoutent les champs propres à l’événement : publication_id, changed, responded_at, application_id et source, replacement_id, replacement_type et le titulaire précédent, checked_in_at ou completed_at.

À savoir #

Un événement ne contient rien de personnel : ni nom, ni note de réponse, ni position GPS. Pour le détail, relisez le shift avec GET /v1/scheduling/shifts/{shift_id}, avec les droits de votre jeton.

Quand rien ne part #

• Brouillons : ils n’émettent rien. Ce que reçoit un intégrateur est ce que voient les employés.
• Module coupé : si la Planification est désactivée pour l’espace, ou retirée à l’employé du shift, aucun événement ne part.
• Après l’enregistrement : un événement part seulement une fois le geste enregistré. Si l’envoi échoue, le geste n’échoue pas : l’échec est journalisé.