Faire remonter une complétion depuis un outil tiers

⚠️ Prérequis : une source de contenu externe configurée, et un fournisseur capable d’appeler une URL à la fin d’un contenu.

Le callback est le chemin par lequel un outil tiers indique à Beedeez qu’un apprenant a terminé une capsule. Beedeez n’émet aucun appel dans ce sens : c’est le fournisseur qui appelle Beedeez. Le sens inverse relève du webhook, et les deux mécanismes ne sont pas interchangeables.

Où activer la remontée des résultats

Ouvrez Configuration > Intégration > LMS > Configuration de contenu externe, puis réglez le champ Récupération des résultats sur la valeur Url de retour.

Ce réglage porte sur la source de contenu externe, et non sur une capsule ou sur le compte entier. Toutes les capsules servies par cette source remontent leurs résultats, ou aucune.

Comment Beedeez fabrique et transmet l’URL

L’URL de retour n’est affichée nulle part dans le back-office, et il n’en existe pas une seule pour tout le compte. Beedeez en fabrique une par apprenant et par capsule, au lancement du contenu, puis la transmet au fournisseur.

Le mode de transmission dépend de la valeur du champ Authentification, qui s’affiche en majuscules et sans traduction :

• NONE et TALENTSOFT : l’URL est ajoutée à l’URL de lancement, dans le paramètre CALLBACK_URL ;
• LTI : l’URL est envoyée dans le paramètre personnalisé custom_callbackurl ;
• APIKEY : aucune URL de retour n’est transmise.

ℹ️ À savoir. Le fournisseur doit lire l’URL à chaque lancement. Un fournisseur qui demande de saisir une URL unique et définitive dans son interface ne sait pas exploiter ce mécanisme.

Envoyer l’appel

Le point d’entrée est le suivant :

POST https://api.developers.beedeez.com/v1/callbacks/update-user-lesson-status/{CALLBACK_TOKEN}

La méthode GET est acceptée sur la même adresse, pour les outils qui ne savent produire qu’une redirection à la fin du contenu. Cette entrée figure aussi dans la référence OpenAPI, sur doc.developers.beedeez.com .

Le corps de la requête est au format JSON et accepte trois champs :

Une réponse 200 renvoie UserID, LessonID, status et progress, complétés par score et absoluteScore lorsqu’un score a été envoyé. absoluteScore correspond au nombre de points réellement crédités.

Les réponses en erreur se répartissent ainsi :

• 400 : la valeur de score sort de la plage 0 à 100 ;
• 403 : le jeton est inconnu, expiré ou d’un autre type, ou la capsule n’est pas un contenu externe ;
• 404 : aucune activité ne correspond au jeton, ou la source n’est pas réglée sur Url de retour.

ℹ️ À savoir. La valeur de progress n’est pas contrôlée. Une valeur hors plage est enregistrée telle quelle.

Ce que chaque statut enregistre

Le statut envoyé détermine l’état de la capsule :

• succeeded : la capsule passe à 100 % et est marquée réussie ;
• failed : la capsule passe à 100 % et est marquée non réussie. Il s’agit également d’une complétion ;
• in-progress et not-started : la capsule prend la valeur de progress et reste non réussie.

Pour une capsule de contenu externe, Beedeez ne recalcule pas la réussite. Le bloc Succès de la capsule, avec son mode de validation et son pourcentage, ne s’applique pas : le fournisseur décide seul du résultat. Tenez compte de cette distinction avant de construire une logique de facturation ou de conformité sur cette remontée.

Sans score, un statut succeeded crédite la totalité des points bonus de la capsule. Avec score, la capsule reçoit ce pourcentage des points bonus, arrondi à l’entier le plus proche.

ℹ️ À savoir. Il n’existe pas de callback de parcours. Un parcours se termine par ses capsules ; aucun appel ne permet de le déclarer terminé directement.

Ce que le jeton identifie

Rien dans la requête ne nomme l’apprenant ni la capsule : le jeton porte l’ensemble des informations, à savoir le compte, l’apprenant, la capsule et la tentative en cours. Il s’agit d’un identifiant aléatoire, créé au premier lancement, réutilisé aux suivants, et valable 100 jours.

La réponse renvoie les identifiants internes Beedeez, sous la forme de 24 caractères hexadécimaux. Aucune référence de votre système n’y est reprise. Si votre récepteur doit faire le lien avec votre propre référentiel, il lui revient de mémoriser la correspondance au moment du lancement.

Sécurité du jeton

L’authentification repose uniquement sur le jeton. Il n’y a ni clé d’API, ni en-tête d’autorisation, ni signature, ni liste d’adresses IP autorisées. C’est le seul point d’entrée de l’API publique dans ce cas. Toute personne qui détient l’URL peut déclarer une complétion pour cet apprenant et cette capsule.

Le jeton figure dans le chemin de l’URL. Il apparaît donc dans les journaux des serveurs mandataires, dans les en-têtes de provenance et dans l’historique du navigateur. En authentification NONE, il circule en clair dans une URL ouverte par le navigateur de l’apprenant, qui peut le lire.

Aucun bouton de révocation n’est disponible dans le back-office. Pour invalider un jeton, adressez-vous à votre interlocuteur Beedeez.

Le premier signal à 100 % verrouille la capsule

Dès que la capsule atteint 100 %, tout appel ultérieur est ignoré. La réponse reste 200 et contient l’état déjà enregistré, mais aucune donnée ne change. Renvoyer deux fois le même appel est donc sans effet, et ce comportement ne constitue pas une idempotence exploitable : il s’agit d’un verrou.

Deux conséquences en découlent :

• un failed reçu en premier fige la capsule sur « terminée, non réussie » ; un succeeded envoyé ensuite ne la corrige pas ;
• l’application peut être ce premier signal. Un apprenant qui termine la capsule dans l’application la passe lui-même à 100 %, et l’appel du fournisseur qui arrive ensuite ne modifie plus rien.

Ce que le callback ne fait pas

• Aucun rattrapage. Beedeez n’émet pas cet appel. Si le fournisseur échoue ou n’appelle jamais, rien ne répare la remontée : il n’existe ni file d’attente ni rejeu. Demandez au fournisseur ce qu’il prévoit en cas d’échec, et sur combien de tentatives.
• Aucune remise à zéro. Le callback ne peut pas ramener une capsule terminée à l’état non terminé.
• Aucun événement webhook. Une complétion reçue par callback ne déclenche pas d’événement lesson_completed : cet événement n’est pas émis.

Vérifier la remontée en conditions réelles

Testez le parcours de bout en bout avec un compte apprenant réel : l’apprenant lance le contenu, va jusqu’au bout chez le fournisseur, et la capsule passe à 100 % dans Beedeez.

Ne validez pas la configuration sur un appel simulé. Une URL appelée à la main prouve que le point d’entrée répond, mais pas que le fournisseur appelle au bon moment, ce qui constitue la principale cause d’échec en production.

💡 Conseil : testez également le cas d’échec. Envoyez un statut failed sur un compte de test et observez la manière dont vos statistiques le traitent.

Pour aller plus loin

• Configurer une source de contenu externe : le réglage Récupération des résultats s’effectue à cet endroit.
• API publique, webhooks, callbacks : que choisir : le tableau qui indique qui appelle qui.
• Les événements webhook disponibles : la liste des événements réellement émis.
• Importer les activités suivies hors Beedeez : la reprise en masse lorsqu’aucun callback n’est possible.