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). 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.

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.

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).

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à).

À 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.
• 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).
• 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.