API d’approvisionnement (JSON) | Workleap Help Center

Utilisez l’API d’approvisionnement pour mettre à jour les membres, les équipes et les structures hiérarchiques dans Workleap à l’aide d’un processus unique et sécurisé. L’API envoie une charge utile JSON depuis votre SIRH via HTTPS afin d’automatiser les synchronisations récurrentes à l’échelle de l’organisation avec Workleap.

Remarque : L’API d’approvisionnement Workleap prend en charge les configurations en CSV et en JSON. Cet article décrit les configurations basées sur le format JSON. Pour les configurations en CSV, cliquez ici.

Spécifications de l’API

Trouvez nos spécifications de l’API ici.

Important : Assurez-vous de consulter la version la plus à jour des spécifications de l’API ci-dessus. Les anciennes versions font référence à des points terminaux obsolètes qui ne fonctionnent plus.

Préambule

Cette intégration nécessite des compétences en développement logiciel lié aux API.
Pour configurer une intégration, vous devez être Administrateur Workleap.
Pour extraire des données d’engagement ou de feedback Officevibe, visitez api.officevibe.com.
Vous avez déjà une intégration personnalisée utilisant notre ancienne API ? Consultez comment mettre à jour votre charge utile ici.

Important : Lors de la première configuration d’une API d’approvisionnement ou d’une intégration SIRH, assurez-vous que l’adresse courriel de tout utilisateur ajouté manuellement à Workleap correspond à celle dans votre source d’approvisionnement.

Lors de la première synchronisation, Workleap ne peut pas mettre à jour les adresses courriel des utilisateurs existants.
Après la première synchronisation, les adresses courriel des utilisateurs seront automatiquement mises à jour à chaque synchronisation quotidienne.

Étape 1 : Activer l’API d’approvisionnement

Allez dans Paramètres > Provisionnement.
Sélectionnez Connecter à côté de API d’approvisionnement.
Créez une clé API de gestion de l’organisation si aucune n’existe.
- Vous pouvez le faire à partir de Paramètres > API ou depuis l’écran de provisionnement.
Définissez un seuil de risque pour éviter les changements non souhaités si une synchronisation dépasse la limite choisie.
Utilisez l’interrupteur pour activer ou désactiver l’envoi automatique d’invitations, ce qui envoie une invitation Workleap aux nouveaux utilisateurs créés.
Sélectionnez Activer l’intégration.

Une seule méthode de provisionnement peut être active à la fois.

Remarque : Vous pouvez configurer l’API d’approvisionnement sans l’activer. Si désactivée, les appels de synchronisation échoueront.

Étape 2 : Authentification

Ajoutez toujours un en-tête workleap-subscription-key suivi de votre clé API. Cette clé est générée sur la page de configuration du provisionnement dans vos paramètres Workleap.

Exemple :

workleap-subscription-key: <votre-clé-api>

Étape 3 : Préparer la charge utile JSON

Préparez la charge utile de provisionnement au format JSON pour gérer et mettre à jour les utilisateurs, les équipes et les structures hiérarchiques. À chaque synchronisation, Workleap utilise cette charge utile pour refléter la structure organisationnelle actuelle. Assurez-vous d’ajuster les données pour éviter les changements inattendus dans votre organisation Workleap.

Détails des données utiles

`members`

Contient les données des membres.
Identifie les utilisateurs avec externalMemberId.
Utilise l’adresse courriel comme identifiant de secours si l’externalMemberId ne correspond à aucun membre existant.

Champs et valeurs facultatifs :

languagePreferences :
- en
- fr
productAssignations :
- Officevibe
- Skills
- LMS
- Pingboard
- Onboarding
- Performance
- Workleap AI
Propriétés personnalisées :
- Utilisez les noms exacts des propriétés tels que configurés dans Workleap.

`teams`

Crée des équipes en fonction des champs externalTeamId et teamName.
Inclut tous les niveaux hiérarchiques (ex. : marques, unités commerciales, départements, sous-équipes).
Inclut les subordonnés directs et les hiérarchies complètes.

Exemples :

Petites équipes dirigées par un seul gestionnaire immédiat.
Grandes équipes composées de plusieurs sous-équipes.

`teamMappings`

Attribue les membres et les gestionnaires aux équipes.

Pour attribuer les membres :

Faites correspondre l’externalTeamId (des équipes) à l’externalMemberId (des membres).

Pour créer une structure de sous-équipes :

Faites correspondre externalSubteamId à externalTeamId (à partir du fichier teams.json).
Construisez la hiérarchie du bas vers le haut (d’abord les sous-équipes).
Les gestionnaires obtiennent automatiquement l’accès à leurs sous-équipes.
En cas de gestionnaires multiples, les gestionnaires supérieurs peuvent voir les données de toute leur ligne hiérarchique.

Remarque : Tous les champs sont sensibles à la casse. Vous pouvez ajouter des champs supplémentaires (ex. : attributs personnalisés).

Conseil : Utilisez des identifiants génériques pour les externalTeamId au lieu des noms des gestionnaires pour réduire les perturbations en cas de changement.

Exemple de données utiles

{ "members": [ { "externalMemberId": "EMP001", "email": "foo@workleap.com", "firstName": "Foo", "lastName": "Bar", "jobTitle": "Engineer", "imageUrl": "https://...", "languagePreferences": ["en", "fr"], "productAssignations": ["Officevibe", "Skills"], "Extra Custom Propery": "" } ], "teams": [ { "externalTeamId": "TEAM001", "teamName": "Operations" } ], "teamMappings": [ { "externalTeamId": "TEAM001", "externalMemberId": "EMP001", "isMember": true, "isManager": false } ] }

Étape 4 : Envoyer une requête POST au point terminal

Point terminal API

PUT https://api.platform.workleap.com/public/provisioning/json/process-and-schedule

L’API valide votre charge de données utiles et planifie le processus de provisionnement. Chaque synchronisation remplace la précédente.

Attention : Incluez toujours les 3 sections de la charge utile, sinon l’opération échouera.

Exemple Curl :

curl -X PUT \ 'https://api.platform.workleap.com/public/provisioning/json/process-and-schedule' \ -H 'Content-Type: application/json' \ -H 'workleap-subscription-key: <votre-clé-api>' \ -d @votre_charge_utile.json

Effets de données manquantes

Voici ce qui se passe lorsqu’un membre ou une équipe de la précédente synchronisation est absent de la nouvelle charge utile JSON :

Membres absents de members :
- Si le membre était actif — il est désactivé.
- Si le membre était invité ou créé — il est supprimé.
- Exception : Les Administrateurs ne sont jamais désactivés ni supprimés automatiquement.
Équipes absentes de teams :
- Les équipes actives précédemment sont supprimées.

Consulter l’historique des synchronisations

Pour voir l’historique de toutes vos synchronisations de provisionnement :

Allez dans Paramètres > Provisionnement.
Cliquez sur Afficher l’historique des synchronisations.
Consultez la liste des synchronisations avec leur statut et leur source.

Remarque : Les synchronisations effectuées via l’API ont toujours API d’approvisionnement comme source.

Statuts de synchronisation

Les synchronisations affichent l’un des statuts suivants dans l’historique :

En attente : La synchronisation est en cours.
En pause : Le seuil de risque est dépassé. Approuvez ou rejetez les modifications.
Rejetée : Une synchronisation en pause a été rejetée.
Réussie : La synchronisation est terminée (elle peut avoir été en pause auparavant).
Avertissement : Succès partiel. Consultez le rapport pour des problèmes comme des doublons.
Échec : La synchronisation n’a pas été effectuée.

Besoin d’aide supplémentaire ?

Consultez notre FAQ sur l’API d’approvisionnement pour des conseils de dépannage et des cas d’usage avancés.
Pour consulter tous les champs pris en charge, les codes d’erreur, et d’autres informations API supplémentaires, rendez-vous sur notre portail développeur Workleap.
Pour une assistance personnalisée, contactez notre équipe de soutien via le widget de clavardage.