---
title: "API publique : le guide du développeur"
description: "Adresse, authentification, droits, enveloppe des réponses, codes d'erreur, limites et pagination de l'API publique d'Illizeo, et la documentation OpenAPI."
url: "http://illizeo.com/centre-aide/api-guide-du-developpeur/"
updated: "2026-11-05"
category: Plateforme / API REST
---

# API publique : le guide du développeur

Cet article s'adresse aux développeurs qui branchent un système sur l'API publique d'Illizeo : où trouver la documentation, comment s'authentifier, ce que chaque droit ouvre, comment lire les réponses et les erreurs, et quelles limites respecter. Le contrat complet, opération par opération, est publié au format OpenAPI 3.1.

## Avant de commencer

- Il vous faut un jeton créé par un administrateur de l'entreprise, avec les droits nécessaires (voir [Créer et gérer les jetons API](https://illizeo.com/centre-aide/api-gerer-les-jetons/)). Sa valeur commence par `illz_`.
- La page de documentation dans l'application s'ouvre avec le droit « Voir les tokens API ». Le contrat brut, lui, est public.

## La page Documentation

Dans **Paramètres › Gérer Illizeo › Jetons API**, le bouton **Documentation** ouvre la page **Documentation de l'API**. Elle se lit de haut en bas :

- la présentation de l'API, l'**URL de base** et un **Premier appel** prêt à copier ;
- la carte **Droits** : chaque ressource et les droits qui la gouvernent, par exemple `employees:read` ;
- une carte par domaine (collaborateurs, paie, absences…) : chaque opération avec sa méthode, son adresse, son résumé et le droit qu'elle exige, ou la mention **sans jeton** ;
- la carte **Événements webhook** : ce qu'Illizeo peut envoyer à vos systèmes.

Le bouton **openapi.json** ouvre le contrat brut, à importer dans un outil comme Postman ou un générateur de client. Si la page affiche « L'hôte de l'API n'a pas répondu », vérifiez que l'adresse de l'API est joignable depuis votre réseau.

![La page Documentation de l'API, version v1.0.0 : présentation de l'API publique, authentification par l'en-tête Authorization: Bearer, hôte unique https://api.illizeo.app, scopes, identité du jeton, enveloppes d'erreur, webhooks et limites de débit, bouton openapi.json en haut à droite](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/api-guide-du-developpeur-01.fr_.png?resize=800%2C500&quality=80&ssl=1)
La documentation de l'API dans l'application.

## Adresse et authentification

- Tous les appels partent vers `https://api.illizeo.app`, sous `/v1`. L'entreprise n'apparaît pas dans l'adresse : c'est le jeton qui la désigne.
- Le jeton se transmet dans l'en-tête `Authorization: Bearer illz_…`. Aucun autre mode d'authentification n'est accepté.
- Exemple : `curl https://api.illizeo.app/v1/employees -H "Authorization: Bearer illz_votre_jeton"`
- Deux adresses répondent sans jeton : `GET /openapi.json` (le contrat) et `GET /v1/ping` (une sonde de disponibilité).
- Les réponses sont en JSON, sauf les téléchargements de fichiers (documents de paie, exports, fiches de paie), qui renvoient le fichier.

## Les droits et ce qu'ils ouvrent

Chaque opération exige un droit de la forme `ressource:action`, coché sur le jeton. Une ressource liée à un module n'est proposée que si le module est activé dans l'espace.

| Droit (écran de création) | Codes | Adresses |
| --- | --- | --- |
| Collaborateurs | `employees:read`, `employees:write` | `/v1/employees` |
| Absences | `absences:read`, `absences:write` | `/v1/absences` |
| Temps et présences | `attendance:read`, `attendance:write` | `/v1/attendance` |
| Planification | `scheduling:read`, `scheduling:write` | `/v1/scheduling` |
| Annualisation du temps de travail | `annualisation:read`, `annualisation:write` | `/v1/annualisation` |
| Budget & masse salariale | `budget:read`, `budget:write` | `/v1/budget` |
| BDESE | `bdese:read` | `/v1/bdese` |
| Documents | `documents:read`, `documents:write` | `/v1/documents` |
| Signatures électroniques | `signatures:read`, `signatures:write` | `/v1/signatures` |
| Paie (export) | `payroll:read` | `/v1/payroll` |
| Paie suisse | `swiss_payroll:read` | `/v1/swiss-payroll` |
| Exports planifiés | `reports:read` | `/v1/exports` |
| Flex Office (lecture de tout le module) | `flex_office:read` | `/v1/flex-office` |
| Flex Office : réservations de bureau, parking, restauration, visites et visiteurs, réunions | `office_bookings:write`, `office_parking:write`, `office_meals:write`, `office_visits:write`, `office_rooms:write` | `/v1/flex-office` |
| Organisation (groupe Référentiel) | `org:read`, `org:write` | `/v1/org` |
| Flex Office : postes de travail, salles de réunion (groupe Référentiel) | `office_desks:write`, `office_rooms_config:write` | `/v1/flex-office/desks`, `/v1/flex-office/rooms` |

![La carte Droits de la documentation : groupes Données et Référentiel, chaque ressource avec ses codes de droit, par exemple employees:read et employees:write](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/api-guide-du-developpeur-02.fr_.png?resize=800%2C365&quality=80&ssl=1)
Les droits de l'API et leurs codes.

## Identité et périmètre

Un jeton agit sous l'identité de la personne qui l'a créé. En plus du droit coché sur le jeton, chaque opération exige chez cette personne le droit de l'écran équivalent de l'application et, le cas échéant, l'accès au module : sans eux, la réponse est 403. Un collaborateur ou un objet hors de son périmètre répond 404. La paie est en lecture seule et ne sort que des périodes approuvées par les RH : une période non validée répond 404 avec le code `PERIODE_NON_APPROUVEE`.

## Réponses et erreurs

Les refus du contrôle d'accès et les ressources récentes répondent avec la même enveloppe : `status` (`Success` ou `Error`), `code` (le code HTTP), `message`, `request_id`, `error_code` pour une erreur, et `data`. Par exemple : `{"status":"Error","code":403,"request_id":"req_…","error_code":"SCOPE_MANQUANT","data":{"required_scope":"employees:read"}}`. Les ressources héritées de la première version de l'API (collaborateurs, absences, présences, documents, signatures, organisation) gardent leur enveloppe d'origine : `status` booléen, `data` ou `message`, et `errors` par champ sur une validation refusée (400).

| Statut | `error_code` | Sens |
| --- | --- | --- |
| 401 | `JETON_ABSENT` | En-tête `Authorization` absent, ou valeur qui ne commence pas par `illz_`. |
| 401 | `JETON_INVALIDE` | Valeur inconnue : erreur de copie, jeton régénéré ou révoqué. |
| 401 | `JETON_EXPIRE` | Date d'expiration passée. |
| 403 | `JETON_DESACTIVE` | Jeton désactivé (y compris un jeton expiré, après le passage de nuit). |
| 403 | `CREATEUR_INDISPONIBLE` | Le créateur du jeton n'est plus actif. |
| 403 | `SCOPE_MANQUANT` | Droit absent du jeton ; `data.required_scope` le nomme. |
| 403 | `FONCTIONNALITE_NON_INCLUSE` | L'abonnement ne comprend pas l'accès à l'API. |
| 413 | `TAILLE_DE_REQUETE` | Requête de plus de 5 Mo ; `data.max_bytes` donne la limite. |
| 429 | `LIMITE_DE_DEBIT` | Limite par minute du jeton atteinte. |
| 429 | `LIMITE_JOURNALIERE` | 10 000 requêtes du jour atteintes ; `data.reset_at` donne la remise à zéro. |
| 429 | `LIMITE_DE_DEBIT_TENANT` | 600 requêtes par minute de l'entreprise atteintes, tous jetons confondus. |
| 429 | `PLAFOND_DE_CONSOMMATION` | Plafond de sécurité de la période atteint, jusqu'à la période suivante. |

Un refus métier (404, 409, 422…) porte son propre `error_code`, listé dans le contrat, et un message dans la langue demandée par l'en-tête `X-Locale` ou `Accept-Language`. Toute réponse porte aussi un en-tête `X-Request-Id` (le `request_id` de l'enveloppe) : citez-le toujours dans une demande de support.

## Limites et en-têtes de réponse

- **Par jeton** : la limite par minute réglée sur le jeton, sinon 60 ; et 10 000 requêtes par jour civil UTC.
- **Par entreprise** : 600 requêtes par minute, tous jetons confondus. Chaque réponse l'annonce par `X-RateLimit-Limit` et `X-RateLimit-Remaining`.
- **Après un 429** : attendez le nombre de secondes donné par `Retry-After` avant de recommencer.
- **Quota** : quand l'abonnement inclut un quota mensuel, chaque réponse porte `X-Quota-Limit`, `X-Quota-Remaining` et `X-Quota-Reset`.
- **Taille** : 5 Mo au plus par requête, corps et fichiers compris.

## Pagination et volumes

- Les listes paginées acceptent `page` (à partir de 1) et `per_page` ; le contrat indique, pour chaque opération, la valeur par défaut et le maximum (10 et 100 pour les onglets de paie et les exports, 100 et 200 pour le Flex Office, dont la réponse porte `meta` avec `page`, `per_page`, `total` et `last_page`).
- `GET /v1/attendance` exige une fenêtre `from` / `to` de 31 jours au plus.
- `GET /v1/absences` renvoie encore toutes les absences de l'entreprise, sans pagination : filtrez par collaborateur.
- Les lectures datées de la Planification couvrent 43 jours au plus, celles du Flex Office 93 jours (`422 PERIODE_TROP_LONGUE` au-delà).

![La carte Collaborateurs de la documentation : chaque opération avec sa méthode GET, POST, PUT ou DELETE, son adresse sous /v1/employees, son résumé et le droit exigé](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/api-guide-du-developpeur-03.fr_.png?resize=800%2C287&quality=80&ssl=1)
Les opérations d'un domaine, avec le droit exigé.

## À savoir

- Pour être prévenu d'un changement plutôt que de le chercher, abonnez votre système aux webhooks : voir [Recevoir et vérifier un webhook](https://illizeo.com/centre-aide/webhooks-recevoir-et-verifier/).
- Les fichiers des rapports planifiés au canal « Retrait par l'API » se récupèrent par `/v1/exports` pendant 30 jours (voir [Planifier l'envoi d'un rapport](https://illizeo.com/centre-aide/people-analytics-planifier-l-envoi-d-un-rapport/)).
- Un appel refusé par le contrôle du jeton (jeton inconnu, droit manquant, limite atteinte) n'apparaît pas dans le journal d'utilisation du jeton : seule la réponse en garde la trace.

### *Similaire*