API, webhooks et callbacks

Cette section s’adresse aux équipes techniques qui font communiquer Beedeez avec un autre outil. Plusieurs mécanismes coexistent et ne sont pas interchangeables : ils diffèrent par le sens de l’appel, par l’authentification et par ce qu’ils transportent. Identifiez d’abord celui qui correspond à votre besoin, puis ouvrez la page qui le décrit.

L’API publique est un service distinct du reste de la plateforme : elle répond sur son propre domaine, api.developers.beedeez.com, et la référence publiée à cette adresse décrit ce service seul. Les appels que le back-office et l’application font au serveur Beedeez n’y figurent pas.

⚠️ La référence et l’API sont deux adresses différentes. La référence OpenAPI est publiée sur doc.developers.beedeez.com . api.developers.beedeez.com est le serveur que votre intégration appelle, et sa racine répond 404.

Qui appelle qui

Mécanisme	Sens de l’appel	Authentification	Ce qu’il permet
API publique	Vous appelez Beedeez	Un jeton obtenu à partir de votre clé d’API	Aller chercher une donnée au moment où vous en avez besoin
Webhooks	Beedeez appelle votre URL	Le mode que vous déclarez sur votre point de terminaison	Être prévenu quand un événement se produit
Callback de complétion	Un outil tiers appelle Beedeez	Un jeton porté dans l’URL, sans clé d’API	Faire revenir dans Beedeez la complétion d’un contenu suivi ailleurs
Webhook Persona	Persona appelle Beedeez	Une signature calculée avec le secret que vous enregistrez	Rendre à Beedeez le résultat d’une vérification d’identité

Vérifier qu’un connecteur existant ne suffit pas

ℹ️ À savoir. Beaucoup de besoins formulés en « il nous faut l’API » sont déjà couverts par un connecteur existant. Un développement sur l’API ne se justifie que si aucun des trois chemins ci-dessous ne convient.

• Automatiser l’export de l’activité vers votre SFTP : pour recevoir régulièrement un fichier de l’activité.
• Quelle brique pour quel besoin : SSO, SCIM, fichier SIRH, Lucca : pour créer, mettre à jour ou désactiver les comptes depuis votre SIRH.
• Configurer une source de contenu externe : pour faire apparaître dans Beedeez des contenus hébergés ailleurs.

Appeler l’API

⚠️ Prérequis : une clé d’API, générée dans Configuration > Intégration > Developers API avec le bouton Générer la clé. Cette sous-page n’apparaît que si l’option correspondante est ouverte sur votre compte : sinon, demandez-la à votre interlocuteur Beedeez.

• Générer et gérer vos clés d’API : créer la clé, la ranger avant de fermer l’écran, la faire supprimer le jour où il le faut.
• S’authentifier sur l’API : échanger la clé contre un jeton, et les erreurs qui font tomber une intégration en production.
• Les ressources disponibles : ce que l’API expose, et où lire la référence à jour plutôt qu’une copie.

Être appelé par Beedeez

⚠️ Prérequis : les webhooks disposent de leur propre option de compte et de leur propre sous-page, Configuration > Intégration > Webhooks.

• Les événements webhook disponibles : à lire avant de concevoir, car la liste réellement émise est plus courte que celle configurable.
• Configurer un endpoint webhook : déclarer l’URL, choisir le mode d’authentification, tenir le délai de réponse.

Les deux intégrations à part

Ces deux mécanismes sont les seuls où un outil tiers appelle Beedeez. Ils ne s’authentifient pas avec une clé d’API et se configurent en dehors de la page Developers API.

• Faire remonter une complétion depuis un outil tiers : quand un contenu est suivi ailleurs et que sa complétion doit revenir dans Beedeez.
• Vérification d’identité Persona : quand une capsule certifiante exige de prouver qui la suit. Cela suppose un contrat chez Persona.

Quand une intégration ne se comporte pas comme prévu, commencez par Problèmes fréquents.