---
title: API publique et webhooks de la Planification
description: "Lire et écrire le planning par l'API publique v1 d'Illizeo, et recevoir les changements de shifts par webhooks."
url: "https://illizeo.com/centre-aide/planification-api-et-webhooks/"
updated: "2026-11-01"
category: Planification
---

# 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**.

![Page Jetons API : consommation de l'API, Documentation et Nouveau jeton](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/planification-api-et-webhooks-01.fr_.png?resize=800%2C500&quality=80&ssl=1)
La page « Jetons API » de Gérer Illizeo.

## 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](https://illizeo.com/centre-aide/planification-creer-et-publier/).

## Les webhooks

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

![Page Webhooks avec les boutons Documentation et Nouveau webhook](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/planification-api-et-webhooks-02.fr_.png?resize=800%2C500&quality=80&ssl=1)
La page « Webhooks » de Gérer Illizeo.

- `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é.

### *Similaire*