L’API REST de Moodle permet à vos autres outils de dialoguer avec votre plateforme de formation : un SIRH qui crée les comptes, un CRM ou une boutique qui inscrit les apprenants, un outil de reporting qui lit la progression et les notes, un script ou un scénario no-code qui automatise une tâche répétitive. Ce guide explique comment elle fonctionne, comment obtenir un jeton d’accès et comment faire vos premiers appels, avec des exemples prêts à copier.
Tout ce qui suit s’applique à n’importe quel Moodle. Sur GoodMoodLMS, les réglages se font depuis l’administration de votre plateforme, sans passer par l’administration technique de Moodle : nous le montrons en captures d’écran.
Comment fonctionne l'API REST de Moodle
Moodle expose ses fonctions à travers ce qu’il appelle des services web. Trois notions suffisent pour s’y retrouver :
- Une fonction fait une chose précise :
core_user_create_userscrée des comptes,enrol_manual_enrol_usersinscrit des utilisateurs à un cours,core_completion_get_course_completion_statusrenvoie l’état d’achèvement d’un cours. Moodle en compte plus de 600, et chaque plugin peut ajouter les siennes. - Un service est un ensemble de fonctions que vous choisissez d’exposer. C’est votre périmètre : une intégration SIRH n’a pas besoin des fonctions de notes, un outil de reporting n’a pas besoin de créer des comptes.
- Un token (jeton) est la clé qui autorise un utilisateur donné à appeler un service donné. Chaque appel s’exécute avec les droits de cet utilisateur : l’API ne contourne jamais les rôles et les capacités de Moodle.
Tous les appels passent par un point d’entrée unique, /webservice/rest/server.php, avec trois paramètres communs : wstoken (le jeton), wsfunction (le nom de la fonction) et moodlewsrestformat=json pour obtenir une réponse JSON. Les paramètres propres à chaque fonction s’ajoutent comme des champs de formulaire classiques, en GET ou en POST.
Étape 1 : activer les services web et créer un service
Sur un Moodle classique, tout se passe dans Administration du site > Serveur > Services web > Vue d’ensemble, qui liste les étapes : activer les services web, activer le protocole REST, créer un service, y ajouter des fonctions, autoriser un utilisateur, créer un jeton. Il faut être administrateur du site.
Sur GoodMoodLMS, les services web et le protocole REST sont déjà activés (la supervision de la plateforme en dépend) et la page Services web de l’administration réunit le reste : la liste des services existants, ceux qu’apportent vos plugins, et le bouton Créer un service. Un gestionnaire de plateforme y a accès sans être administrateur Moodle.
Trois conseils au moment de créer un service :
- Donnez-lui un nom qui dit à quoi il sert (« Intégration SIRH », « Export reporting »), et un nom abrégé sans espace.
- Créez un service par intégration. Révoquer l’accès d’un outil ne doit jamais casser les autres.
- Cochez « Uniquement utilisateurs autorisés » : seuls les comptes explicitement autorisés pourront utiliser le service, même s’ils obtiennent un jeton par un autre moyen.
Étape 2 : choisir les fonctions et lire leur documentation
Un service vide ne sert à rien : il faut y ajouter les fonctions dont votre intégration a besoin. Sur GoodMoodLMS, la vue Fonctions et documentation d’un service permet de chercher une fonction par son nom ou par son plugin (core_user, get_courses, enrol…) et d’en ajouter plusieurs d’un coup.
Chaque fonction ajoutée affiche ensuite sa fiche : lecture ou écriture, capacités Moodle requises, tableau des paramètres avec leur type et leur caractère obligatoire, structure de la réponse, et un exemple d’appel curl prêt à adapter. Sur un Moodle classique, cette documentation existe aussi, sous Administration du site > Serveur > Services web > Documentation API, dans un format plus brut.
Le tableau des capacités mérite un coup d’œil : il indique ce que l’utilisateur du jeton doit avoir le droit de faire. Si l’appel échoue plus tard avec une erreur d’accès, c’est presque toujours là que se trouve l’explication.
Étape 3 : créer un token
Le jeton est lié à un utilisateur et à un service. Bonne pratique : créez un compte dédié à l’intégration (par exemple « integration.sirh ») plutôt que d’utiliser le compte d’une personne. Ce compte doit avoir les capacités listées par les fonctions du service, généralement via un rôle attribué au niveau du site.
Sur GoodMoodLMS, la page Tokens de l’administration demande l’utilisateur, le service, une date de fin de validité facultative et une restriction d’adresse IP facultative. Le rôle « Utilisateur de services web », qui autorise l’appel du protocole REST, est attribué automatiquement si le compte ne l’a pas, et le compte est autorisé sur le service s’il est restreint.
Le jeton est affiché une seule fois, avec un bouton pour le copier et l’URL d’appel. Rangez-le dans le gestionnaire de secrets de votre outil ou dans une variable d’environnement, jamais dans un dépôt de code ni dans un document partagé. En cas de doute sur sa confidentialité, supprimez-le et créez-en un nouveau : c’est l’affaire d’une minute.
Étape 4 : le premier appel
La fonction core_webservice_get_site_info est le test idéal : elle ne modifie rien et renvoie le nom du site, l’utilisateur du jeton et la liste des fonctions que ce jeton peut appeler.
curl -X POST "https://votre-plateforme.goodmoodlms.com/webservice/rest/server.php" \
-d "wstoken=VOTRE_TOKEN" \
-d "wsfunction=core_webservice_get_site_info" \
-d "moodlewsrestformat=json"Extrait de la réponse :
{
"sitename": "Formation ACME",
"username": "integration.sirh",
"userid": 1042,
"release": "5.0.1",
"functions": [
{ "name": "core_user_create_users", "version": "2025041400" },
{ "name": "core_webservice_get_site_info", "version": "2025041400" }
]
}Point important, qui surprend souvent : Moodle répond en HTTP 200 même en cas d’erreur. Le code HTTP ne suffit donc pas, il faut regarder si la réponse contient une clé exception :
{
"exception": "webservice_access_exception",
"errorcode": "accessexception",
"message": "Access control exception"
}Les trois erreurs les plus fréquentes :
invalidtoken: le jeton est faux, expiré, ou appelé depuis une adresse IP non autorisée.accessexception: la fonction n’est pas dans le service du jeton, ou l’utilisateur n’a pas les capacités requises.invalidparameter: un paramètre manque ou n’a pas le bon format, le plus souvent un tableau mal encodé (voir ci-dessous).
Exemples d'appels utiles
Les fonctions Moodle prennent presque toutes des tableaux en paramètre, pour traiter plusieurs éléments en un appel. En REST, un tableau s’écrit avec des crochets : users[0][email], enrolments[0][courseid], values[1]. C’est la source d’erreur numéro un des premiers appels.
Retrouver un utilisateur à partir de son e-mail
curl -X POST "https://votre-plateforme.goodmoodlms.com/webservice/rest/server.php" \
-d "wstoken=VOTRE_TOKEN" \
-d "wsfunction=core_user_get_users_by_field" \
-d "moodlewsrestformat=json" \
-d "field=email" \
-d "values[0]=camille.durand@exemple.fr"La réponse est un tableau, vide si personne ne correspond. À utiliser avant toute création pour éviter les doublons.
Créer un compte apprenant
curl -X POST "https://votre-plateforme.goodmoodlms.com/webservice/rest/server.php" \
-d "wstoken=VOTRE_TOKEN" \
-d "wsfunction=core_user_create_users" \
-d "moodlewsrestformat=json" \
-d "users[0][username]=camille.durand" \
-d "users[0][firstname]=Camille" \
-d "users[0][lastname]=Durand" \
-d "users[0][email]=camille.durand@exemple.fr" \
-d "users[0][createpassword]=1"Avec createpassword=1, Moodle génère un mot de passe et envoie un e-mail de bienvenue à l’apprenant. Vous pouvez aussi fournir users[0][password], qui doit respecter la politique de mots de passe du site. Le nom d’utilisateur doit être en minuscules. La réponse contient l’id du compte créé, à conserver pour les appels suivants.
Trouver un cours et y inscrire l'apprenant
curl -X POST "https://votre-plateforme.goodmoodlms.com/webservice/rest/server.php" \
-d "wstoken=VOTRE_TOKEN" \
-d "wsfunction=core_course_get_courses_by_field" \
-d "moodlewsrestformat=json" \
-d "field=shortname" \
-d "value=SST-2026"Puis l’inscription, avec le rôle étudiant (roleid=5 dans une installation standard) et, si besoin, une date de fin d’accès :
curl -X POST "https://votre-plateforme.goodmoodlms.com/webservice/rest/server.php" \
-d "wstoken=VOTRE_TOKEN" \
-d "wsfunction=enrol_manual_enrol_users" \
-d "moodlewsrestformat=json" \
-d "enrolments[0][roleid]=5" \
-d "enrolments[0][userid]=1042" \
-d "enrolments[0][courseid]=37" \
-d "enrolments[0][timeend]=1767225600"La méthode d’inscription manuelle doit être active dans le cours, ce qui est le cas par défaut. En cas de succès, la réponse est vide : pas de nouvelle, bonne nouvelle.
Lire l'achèvement et les notes
curl -X POST "https://votre-plateforme.goodmoodlms.com/webservice/rest/server.php" \
-d "wstoken=VOTRE_TOKEN" \
-d "wsfunction=core_completion_get_course_completion_status" \
-d "moodlewsrestformat=json" \
-d "courseid=37" \
-d "userid=1042"La réponse indique dans completionstatus.completed si le cours est achevé, et détaille chaque critère (activités, note, durée). Le suivi d’achèvement doit être activé dans le cours. Pour les notes :
curl -X POST "https://votre-plateforme.goodmoodlms.com/webservice/rest/server.php" \
-d "wstoken=VOTRE_TOKEN" \
-d "wsfunction=gradereport_user_get_grade_items" \
-d "moodlewsrestformat=json" \
-d "courseid=37" \
-d "userid=1042"Chaque élément de usergrades[0].gradeitems donne la note brute, la note formatée et le pourcentage, activité par activité, avec le total du cours en dernier.
Enfin, core_enrol_get_users_courses avec un simple userid liste les cours d’un apprenant avec sa progression en pourcentage : pratique pour un tableau de bord externe.
Bonnes pratiques
- POST et HTTPS, toujours. En GET, le jeton finit dans les journaux du serveur et des proxys.
- Un service, un compte, un jeton par intégration, avec les seules fonctions nécessaires et les seules capacités nécessaires.
- Date de validité et restriction IP quand l’outil appelant a une adresse fixe : un jeton volé devient inutilisable ailleurs.
- Testez la clé
exceptionde chaque réponse, pas seulement le code HTTP. - Cherchez avant de créer : un compte ou une inscription en double est plus long à nettoyer qu’à éviter.
- Groupez les appels : les tableaux acceptent des dizaines d’éléments. Cent comptes se créent en un appel, pas en cent.
- Validez sur une plateforme d’essai avant la production : les données de formation sont des preuves, pour Qualiopi comme pour vos clients.
Et sans développeur ?
L’API REST n’exige pas d’écrire du code. Les outils d’automatisation comme Zapier, Make ou n8n disposent d’un module « requête HTTP » qui appelle une fonction Moodle exactement comme les exemples ci-dessus : inscription automatique après un achat ou une signature de devis, relance des apprenants inactifs, export hebdomadaire des résultats vers un tableur. Pour les logiciels de gestion de la formation, GoodMoodLMS propose des connecteurs Dendreo et Ymag qui s’appuient sur cette même API, sans rien à configurer de votre côté au-delà du jeton.
Aller plus loin
La documentation officielle des services web Moodle détaille les protocoles et les options avancées. Sur GoodMoodLMS, les services web, les tokens et la documentation de chaque fonction font partie du pack Intégrations & API. Le plus simple pour tester vos appels reste une plateforme d’essai gratuite de 14 jours : une vraie instance, tous les packs, et un jeton en quelques clics.
