Documentation de l'API

Chaque institution dispose de sa propre documentation interactive de l’API, disponible sous /docs/ à partir de l’adresse de votre Eduvem - par exemple, https://love.eduvem.com/docs/. C’est le support que l’équipe technique responsable de l’intégration (RH, ERP, BI ou tout autre système externe) utilisera pour découvrir et tester l’API avant d’écrire la moindre ligne de code.

Ce que vous y trouvez

La documentation réunit tous les endpoints de l’API d’intégration : paramètres acceptés, schémas de requête et de réponse, et portées exigées par chaque appel. La page est interactive - vous pouvez déplier n’importe quel endpoint, renseigner les paramètres et envoyer la requête directement depuis le navigateur, avec un jeton réel, sans avoir besoin de Postman ni d’aucun autre outil externe.

Où trouver le lien

Dans l’onglet Intégrations des paramètres de l’institution (Institution > Intégrations), la section Configuration de l’API pour les intégrations propose :

• Le lien Documentation de l’API, qui ouvre le /docs/ de votre institution.
• L’URL de l’API, prête à copier - l’adresse de base utilisée dans chaque appel d’intégration.

Astuce

Chaque institution a sa propre documentation, sur son propre domaine. Si vous administrez ou intégrez plus d’une Eduvem, vérifiez toujours quel /docs/ vous utilisez - celui de chaque institution est différent.

Authentification

Pour tester un appel directement dans la documentation interactive - ou pour configurer une véritable intégration - vous avez besoin d’un jeton d’API valide. La création, la révocation et les portées des jetons se gèrent dans le même onglet Intégrations : voir Jetons de l’API d’intégration. Sans jeton, la documentation reste consultable et chaque endpoint reste visible, mais le bouton d’envoi de la requête renvoie une erreur d’authentification.

Leçons d’un contenu

Une intégration qui traite chaque leçon comme une tâche à part entière - un plan de développement individuel dans un système RH, par exemple - peut consulter la liste des leçons d’un contenu et, par inscription, le statut de chacune :

• GET /integrations/courseVersions/{courseVersionUUID}/lessons renvoie la liste ordonnée et en lecture seule des leçons du contenu publié - les leçons du wizard regroupées par module, les SCOs d’un paquet SCORM, ou l’unité unique d’un coursebox.
• GET /integrations/enrollments/{enrollmentUUID}/lessons renvoie la même liste pour une inscription spécifique, avec le statut « consultée »/« terminée » de chaque leçon et la progression globale de l’inscription.

Les deux appels ont leur propre limite d’utilisation : 120 requêtes par minute, par institution, pour chacun.

Tous les champs, portées et exemples complets de chaque endpoint se trouvent dans la documentation interactive de l’API de votre institution (ci-dessus).

Astuce

L’identifiant de chaque leçon (lessonKey) est l’identité de la leçon ; sa position dans la liste (position) n’est que l’ordre d’affichage - si un auteur réordonne les leçons, la position change, mais le lessonKey reste le même. La stabilité du lessonKey varie aussi selon le type de contenu : les identifiants des leçons du wizard survivent à une republication et restent les mêmes d’une traduction à l’autre. Les identifiants des leçons SCORM, en revanche, sont les chemins de fichiers du paquet SCORM lui-même : les identifiants peuvent changer ou disparaître si le paquet est remplacé par une nouvelle version ou, dans l’appel par inscription, une fois que le premier accès du participant fixe une langue dont le paquet comporte des fichiers différents. Une intégration qui conserve cet identifiant (pour suivre des tâches, par exemple) doit se resynchroniser après l’un de ces changements. La plupart des contenus SCORM n’ont qu’une seule leçon.

Étapes et progression d’un parcours

Une intégration qui suit un parcours - un ensemble de salles qui composent un même cheminement - peut consulter la liste des étapes du parcours et la progression de chaque participant dans celui-ci :

• GET /integrations/categories/{categoryUUID}/steps renvoie la liste ordonnée et en lecture seule des étapes (salles) qui composent le parcours, avec le nom de chacune et son délai en jours configuré (0 quand il n’y a pas de délai). Ne fonctionne que pour une catégorie marquée comme parcours - pour toute autre catégorie, l’appel renvoie une erreur « introuvable ».
• GET /integrations/categories/{categoryUUID}/progress renvoie, par participant, le total d’étapes terminées et l’état de chaque étape (non inscrit, inscrit, bloqué par une étape antérieure, en attente d’évaluation ou terminé). Exige la permission Rapports (lecture) sur le jeton et a sa propre limite d’utilisation : 120 requêtes par minute.

Comme pour les leçons d’un contenu, tous les champs de chaque réponse se trouvent dans la documentation interactive de l’API de votre institution (ci-dessus).

Formations NR pour les systèmes SST

Les intégrations avec le système SST de l’entreprise (SOC, Senior, TOTVS) peuvent récupérer les formations NR terminées, les mêmes que dans le rapport Exportation des formations NR :

• GET /integrations/reports/nrTrainingRecords renvoie, paginée, la liste des formations NR avec certificat émis dans la période. Elle exige la permission Rapports (lecture) sur le jeton. Le paramètre certifiedSince est obligatoire (aaaa-mm-jj ou un instant ISO-8601 avec Z ou un décalage) et certifiedUntil est facultatif (par défaut, maintenant) ; ps limite la page à 500 enregistrements. La réponse contient aussi le total, le nombre de personnes anonymisées exclues et la version de la structure de la Tabela 28 de l’eSocial.

Le point d’accès a sa propre limite d’usage (60 requêtes par minute) et ne répond que pour les institutions dont la fonctionnalité NR est activée ; pour les autres, l’appel renvoie une erreur. Tous les champs figurent dans la documentation interactive de l’API de votre institution (ci-dessus).

Résumé d’une salle

Une intégration qui affiche l’avancement d’une salle dans un autre système (un tableau de bord BI, par exemple) peut interroger son résumé agrégé :

• GET /integrations/reports/courseClasses/{courseClassUUID}/summary renvoie le nombre d’inscrits et de certificats de la salle, le taux d’achèvement et la moyenne des notes. Il exige la permission Rapports (lecture) sur le jeton et a sa propre limite d’utilisation : 120 requêtes par minute.

Une salle qui existe mais n’a pas encore d’inscription répond normalement (HTTP 200) avec un résumé vide : enrolledCount et certifiedCount égaux à 0, et completionRate et averageAssessmentScore nuls. Une salle qui n’existe pas, a été supprimée, est une salle de test ou appartient à une autre institution renvoie toujours « introuvable » (HTTP 404, courseClassNotFound).

Note

Auparavant, l’appel pour une salle sans inscription renvoyait 404. Si votre intégration traitait cette erreur comme « salle vide », traitez désormais le résumé vide.

Identifiant de votre système RH (externalId)

Quand l’institution charge les personnes par la synchronisation des personnes, chaque personne a un externalId : le code que le système RH utilise pour elle. L’API d’intégration le renvoie désormais, afin que le système externe n’ait pas à recouper par e-mail ou CPF :

• Utilisateurs (GET /integrations/users et la consultation d’un utilisateur) : champ externalId.
• Inscriptions (GET /integrations/enrollments) : champ personExternalId, dans le bloc de la personne.
• Webhooks d’inscription et de parcours : champ person.externalId dans le bloc de la personne de la notification.
• Filtre : GET /integrations/users?externalId=<code> renvoie uniquement la personne dont l’externalId est exactement égal à la valeur indiquée.

La clé est omise quand la personne n’a pas d’externalId. Ainsi, les réponses et les notifications signées des institutions qui n’utilisent pas la synchronisation des personnes restent identiques à celles d’avant. La description de chaque champ figure dans la documentation interactive, dans les quatre langues.

Copier la liste des inscriptions

Pour copier toutes les inscriptions de l’institution vers un autre système (un outil de BI ou un data lake, par exemple), utilisez le curseur de GET /integrations/enrollments au lieu de demander les pages par numéro :

1. Faites le premier appel sans pn (ou avec pn=1). Chaque page complète contient le champ nextCursor.
2. Appelez de nouveau en envoyant cursor=<le nextCursor reçu>, tel quel, jusqu’à ce qu’une réponse contienne un nextCursor nul.

Chaque page par curseur coûte la même chose, que ce soit la première ou la millième, alors que demander la page 500 par numéro oblige à relire les 499 précédentes. Dans les réponses par curseur, count, pageCount et pageNumber sont nuls.

• Ne combinez pas cursor avec un pn supérieur à 1, lastModified ou startedSince, et répétez les mêmes filtres courseClassUUID, userUUID et teamUUID que l’appel qui a produit le curseur. Sinon, la réponse est une erreur cursorConflict.
• Modifications récentes : le curseur ne renvoie que les inscriptions modifiées il y a plus de 5 minutes. Une modification apparaît dans une copie par curseur après ce délai.
• Livraison au moins une fois : une inscription modifiée pendant la copie peut revenir plus loin. Mettez à jour par enrollmentUUID au lieu d’insérer de nouveau.
• Synchronisation incrémentale : conservez le plus grand lastModificationDate reçu et, à l’exécution suivante, commencez avec lastModified=<cette valeur moins 5 minutes>.

Attention

Demander toute la liste page par page par numéro, sans aucun filtre, est obsolète : ces réponses contiennent les en-têtes Deprecation et Sunset (3 janvier 2027). Après cette date, une version future pourra refuser les pages profondes sans filtre et demander le curseur.

Voir aussi

• Jetons de l’API d’intégration