Utiliser l'API REST

L'API REST permet à vos propres systèmes de dialoguer avec Bueggio HR : lire les personnes, les équipes, les absences et les soldes, voir qui est absent, simuler une réservation avant de la créer et — avec une clé en lecture-écriture — réserver, approuver, refuser ou annuler, chaque action étant tracée. C'est le même moteur que l'app, exposé en JSON propre.

Créer une clé API

Les clés sont gérées par les admins et appartiennent à l'organisation, pas à une personne :

1. Allez dans Réglages → Intégrations → API.
2. Donnez à la clé un nom qui dit où elle servira (« Zapier », « Export paie »…).
3. Choisissez les permissions : Lecture seule ou Lecture et écriture. Commencez par la lecture seule, sauf besoin d'écrire.
4. Cliquez sur Créer la clé et copiez-la immédiatement — elle n'est affichée qu'une fois et stockée uniquement sous forme de hachage. Si vous la perdez, révoquez-la et créez-en une nouvelle.

Votre première requête

Authentifiez chaque appel avec la clé en jeton Bearer :

curl https://www.bueggiohr.eu/api/v1/whos_off \
  --header "Authorization: Bearer bhr_..."

Trois endroits pour découvrir la surface :

• Documentation API — la référence lisible de chaque endpoint.
• /api/v1/openapi.json — la spécification OpenAPI, pour générer des clients et outils de test.
• /api/docs.md — toute la référence en un seul fichier Markdown, pratique à coller dans un assistant IA.

Ce qu'il y a dans l'API

• Lecture — organisation, personnes, équipes, types d'absence, jours fériés, absences, soldes par personne, qui est absent sur une plage de dates.
• Devis — la répétition générale d'une réservation : combien de jours elle déduirait et les conflits éventuels, sans rien créer.
• Écriture (permissions lecture et écriture) — créer des demandes, approuver, refuser, annuler. Les réservations suivent les mêmes règles que l'app : flux de validation, périodes verrouillées et plafonds d'absence s'appliquent, et tout atterrit dans l'historique de la demande.
• Gestion des webhooks — enregistrer et retirer des endpoints webhook par programme.

Gardez vos clés en sécurité

• Traitez une clé comme un mot de passe : elle donne accès aux données d'absence de toute votre organisation.
• Utilisez une clé par système, nommée clairement — la liste montre la dernière utilisation de chaque clé, les clés dormantes se repèrent et se révoquent facilement.
• Révoquez immédiatement si une clé fuite ; les intégrations qui l'utilisent s'arrêtent à l'instant même.

Dépannage

• 401 invalid_api_key — l'en-tête doit être exactement Authorization: Bearer bhr_... ; vérifiez que la clé n'a pas été révoquée.
• 403 sur une écriture — la clé est en lecture seule ; créez une clé en lecture-écriture.
• Une réservation est rejetée — l'API applique les mêmes règles que l'app (périodes verrouillées, plafonds d'absence, soldes). Le message d'erreur indique quelle règle l'a refusée.