Référence de l'API

URL de base et format des réponses

Chaque route est servie sous le préfixe /api. En local, l'URL de base est http://localhost:8000/api. Sur un serveur, c'est l'adresse de votre API suivie de /api, la même valeur que les deux frontends lisent dans NEXT_PUBLIC_API_BASE_URL (Variables d'environnement).

L'API sert deux publics qui ne partagent jamais de jeton. Les étudiants utilisent les routes sous /api/users/<area> et /api/shop, listées dans les sections étudiantes ci-dessous. Le tableau de bord admin utilise toutes les autres routes, y compris /api/users lui-même et /api/users/<username>, qui gèrent les comptes étudiants.

Les corps de requête sont en JSON, sauf pour l'envoi de fichiers. Chaque réponse arrive dans la même enveloppe :

{
  "success": true,
  "data": { },
  "message": ""
}

data contient le résultat. message est une courte phrase que certaines écritures renseignent, traduite dans la langue de la requête, et vide sinon. Le health check n'exige pas de jeton et montre l'enveloppe :

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok"},"message":""}

Il répond 503 tant que la base de données est injoignable ou ne contient aucune table : un load balancer peut donc l'utiliser comme sonde de disponibilité.

Erreurs

Une requête qui échoue répond avec le statut HTTP correspondant et la même enveloppe, avec success: false, data: null et, pour la validation, les problèmes par champ, indexés par le nom du champ (un champ d'un objet imbriqué par son chemin pointé) :

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"not-an-email","password":"x"}'

{
  "success": false,
  "data": null,
  "message": "Enter a valid email address (example@domain.com).",
  "errors": {
    "email": ["Enter a valid email address (example@domain.com)."]
  }
}

Les écritures réussies répondent 201 pour POST et 200 pour les autres méthodes.

Pagination et tri

Les listes ont deux formes, une par public. Les routes étudiantes répondent dans la forme que lit le site étudiant ; les routes admin répondent dans la forme que lit le tableau de bord.

Une page contient au plus 100 lignes : une taille plus grande est lue comme 100, et une taille absente ou illisible revient à la valeur par défaut de la liste. Il en va de même pour page, qui revient à 1.

sort n'accepte que les colonnes autorisées par chaque liste. Une clé inconnue se replie sur l'ordre par défaut au lieu d'échouer : un ancien favori se charge donc toujours.

La liste publique des cours se trie par id, price, discount_percentage, rating, duration, level, language, created_at ou updated_at, et se filtre par title, category_id, instructor_id et type (live ou recorded).

Langue

Envoyez la langue du lecteur dans l'en-tête Accept-Language. L'API parle les langues listées dans back-end/src/i18n/locales.ts, en et ar à la livraison. Elle lit la première étiquette, donc ar-SA est de l'arabe, et une requête qui ne nomme aucune langue prise en charge reçoit une réponse dans la langue du paramètre default_locale. Il n'y a pas de paramètre de requête pour la langue.

• Les messages d'erreur et le message d'une écriture réussie sont traduits.
• Le texte enregistré dans les deux langues, comme les titres et descriptions des cours, est renvoyé sous la forme { "en": "...", "ar": "..." } et le client choisit l'une des deux.
• Quelques routes étudiantes ne répondent que dans la langue demandée : la liste des inscriptions, le contenu d'un cours et la recherche.
• Le paiement prend la langue dans son corps (locale, l'une des langues prises en charge), pour que le reçu corresponde à la page sur laquelle l'étudiant a acheté.

Authentification

Les étudiants et les administrateurs se connectent sur des endpoints différents, sur des tables différentes, et reçoivent des jetons que seules leurs propres routes acceptent.

• Les deux sont des JWT signés avec JWT_SECRET. Envoyez-les sous la forme Authorization: Bearer <token>.
• Un jeton dure JWT_EXPIRATION, 7d par défaut (Variables d'environnement). La connexion administrateur renvoie la même valeur dans expires_in.
• Il n'y a pas d'endpoint de rafraîchissement. Quand un jeton expire, la requête suivante répond 401 et le client se reconnecte.
• La déconnexion (POST /api/users/auth/logout) indique seulement au client d'abandonner son jeton. Rien n'est révoqué sur le serveur : un jeton reste donc valide jusqu'à son expiration.
• Un jeton étudiant est refusé sur les routes admin et un jeton admin sur les routes étudiantes, bien que les deux utilisent le même secret.
• Une connexion qui échoue répond 401 avec un seul message, que l'e-mail n'ait pas de compte ou que le mot de passe soit faux : le formulaire ne permet donc pas de savoir qui a un compte.
• Les routes de connexion, d'inscription et de mot de passe acceptent 10 tentatives par minute depuis une même adresse, comptées par route. Au-delà, elles répondent 429 avec un en-tête Retry-After. Le compte est gardé dans la mémoire de l'API : il repart de zéro au redémarrage et chaque instance a le sien.

1. 01

   Se connecter avec le Super Admin des données de démonstration

   TerminalCopier

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@learnio.com","password":"Admin@123"}'

   RéponseCopier

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "admin": {
         "id": 1,
         "email": "admin@learnio.com",
         "instructor_id": null,
         "roles": [{ "id": 1, "name": "Super Admin", "guard_name": "web" }],
         "permissions": ["admins.view", "admins.create", "..."]
       }
     },
     "message": "Signed in successfully."
   }
2. 02

   Appeler une route protégée avec le jeton

   TerminalCopier

   curl "http://localhost:8000/api/courses?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   Résultat attendu: Les cinq premiers cours, dans la forme des listes admin.
3. 03

   Se connecter avec l'étudiant des données de démonstration

   Les données d'exemple contiennent aussi un étudiant, demo@learnio.com avec le mot de passe Demo@123 :

   TerminalCopier

   curl -X POST http://localhost:8000/api/users/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"demo@learnio.com","password":"Demo@123"}'

   Transmettez ensuite data.token de la même manière, par exemple à GET /api/users/enrollments.

Permissions

Chaque route admin vérifie d'abord le jeton, puis la permission qu'elle nomme. Les permissions sont nommées <module>.<action>, et un administrateur détient toutes les permissions de tous ses rôles. Quand une route en nomme plusieurs, n'importe laquelle suffit. Dans les tableaux admin ci-dessous, un nom de permission dans la colonne Qui peut l'appeler désigne un administrateur dont les rôles l'accordent.

Relancer le seeder crée les rôles manquants et laisse les permissions des rôles existants telles quelles : les modifications faites dans le tableau de bord sont conservées. Super Admin fait exception : il reçoit toute permission qu'il n'a pas encore.

Chaque permission de lecture se termine par .view, et aucune autre : le rôle Viewer des données de démonstration est construit à partir de cette règle. Les rôles créés par les données d'exemple :

Un compte admin lié à un formateur porte un instructor_id dans sa réponse de connexion, et il est limité à ses propres cours en plus de ses permissions : les listes n'affichent que ces cours et leurs étudiants, et une écriture en dehors répond 403.

Quand les rôles d'un administrateur changent, le tableau de bord en est informé par le socket /auth (événement permissions-updated) pour rafraîchir GET /api/auth/me. Ce socket n'accepte que des jetons d'administrateur.

Catalogue public

Aucun jeton nécessaire. Ce sont les routes qu'appellent les pages publiques du site étudiant.

Le I majuscule de /api/users/Instructors correspond au chemin qu'appelle le site étudiant ; la correspondance n'est pas sensible à la casse.

Inscription et connexion des étudiants

Le site étudiant utilise les routes sous /api/users/auth. L'inscription connecte immédiatement l'étudiant et envoie par e-mail un lien de confirmation ; un compte non confirmé peut quand même naviguer et acheter.

resend et forgot-password répondent de la même façon que l'adresse ait un compte ou non : on ne peut donc pas s'en servir pour savoir qui est inscrit. La connexion, l'inscription, resend, forgot-password et reset-password sont limitées en nombre de tentatives (Authentification).

Un second ensemble de routes étudiantes sous /api/students/auth fonctionne sur les mêmes comptes et répond aussi token et user. Le site étudiant ne l'utilise pas ; préférez /api/users/auth.

Profil, cours et progression de l'étudiant

Chaque route ici exige un jeton étudiant. Les cours et les leçons sont désignés par leur code, pas par leur identifiant numérique.

Les routes d'avis prennent l'identifiant numérique du cours, et chaque étudiant a un avis par cours. Seul un étudiant inscrit au cours peut en écrire un ; une inscription annulée répond 403.

• Un avis est published aussitôt, ou pending jusqu'à ce qu'un modérateur l'approuve quand le paramètre reviews_require_approval vaut true. Modifier un avis masqué par un modérateur le renvoie à pending.
• Un avis supprimé par un modérateur revient avec status: removed et ne peut plus être modifié ni retiré (403).
• Chaque écriture recalcule la note et le nombre d'avis du cours, ainsi que ceux de son formateur.
• Un nouvel avis, et une modification en attente d'approbation, notifient le personnel qui détient reviews.view.

Quiz, devoirs et calendrier

Les routes du calendrier pour les cours en direct sont décrites dans Cours en direct.

Messages et notifications des étudiants

Les nouvelles notifications sont aussi envoyées via Socket.IO, sur le namespace /notifications à l'adresse de l'API sans /api. Transmettez le jeton comme auth.token dans le handshake et écoutez notification:created. Les administrateurs utilisent le même socket avec leur propre jeton.

Paiement et règlements

Quand le paiement répond avec redirect_url, envoyez-y l'acheteur et considérez la commande comme pending : la place est attribuée quand le webhook du prestataire confirme le paiement, pas au retour. Chaque webhook vérifie la signature du prestataire et répond 401 si elle ne correspond pas. Les événements ne sont appliqués qu'une fois, quel que soit le nombre de nouvelles tentatives du prestataire.

Un cours gratuit (prix 0) passe par la même route et n'atteint jamais de processeur de paiement : il fonctionne sans aucune clé de paiement. La commande est enregistrée comme paid avec gateway: "free" et redirect_url: null, la place est attribuée aussitôt, et l'étudiant reçoit l'e-mail d'inscription sans reçu. Les commandes gratuites comptent comme des inscriptions, pas comme des ventes : elles sont exclues du panier moyen.

Configuration des prestataires et de leurs abonnements aux webhooks : Paiements.

Connexion admin et comptes du personnel

Une adresse e-mail appartient à un seul administrateur, même supprimé : créer un administrateur, ou changer un e-mail pour une adresse déjà utilisée, répond 409.

Rôles

Étudiants

Les comptes étudiants sont désignés par username. La suppression d'un compte est une suppression logique, réversible.

Formateurs

Un compte formateur écrit à ses étudiants via ces routes, qui répondent 403 pour un administrateur non lié à un formateur :

Catégories

Les lectures sont ouvertes à tous et listées dans le Catalogue public. Les écritures exigent une permission :

Cours

Programme : sections, leçons et ressources

Quiz et devoirs

Inscriptions et commandes

Le status d'une commande est pending, paid, failed ou refunded. Son gateway nomme le processeur qui a encaissé le paiement, demo pour le simulateur intégré, ou free pour un cours qui ne coûtait rien.

Avis

Les étudiants écrivent leurs propres avis via les routes étudiant, et la page du cours lit ceux qui sont publiés dans le Catalogue public. Chaque décision de modération recalcule la note du cours et celle du formateur.

Blog

Paramètres

Les paramètres de la plateforme sont enregistrés sous forme de paires clé-valeur et désignés par key.

Le seeder crée ces six paramètres, et chacun est lu par l'API ou par le tableau de bord de l'étudiant :

Une modification s'applique à la requête ou à l'e-mail suivant, sans redémarrage. Relancer le seeder ajoute un paramètre manquant, mais n'écrase jamais une valeur déjà enregistrée.

Envoi de médias

Envoyez du multipart/form-data avec le fichier dans file, jusqu'à 150 Mo, et éventuellement path (le dossier, uploads par défaut), for (un préréglage de taille d'image) et type (video pour ignorer le traitement d'image). Les images sont redimensionnées en plusieurs versions ; les vidéos (mp4, webm, mov, m4v) sont enregistrées telles quelles. Cette route a besoin des paramètres du bucket décrits dans Stockage des médias.

La route demande un jeton d'administrateur ou d'étudiant, vérifié avant la lecture du fichier. path doit être l'un des dossiers listés dans back-end/src/modules/helpers/upload/upload-folders.constants.ts ; tout autre répond 400. Un administrateur peut téléverser dans uploads, admins/profile, admins/profiles, users/profiles, blog, categories, courses, instructors, messages et ai-chat. Un étudiant ne peut téléverser que dans messages, pour les images qu'il joint à une conversation. Un nouvel écran qui téléverse dans son propre dossier demande d'ajouter ce dossier à la liste.

curl -X POST http://localhost:8000/api/helpers/upload \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@cover.jpg" -F "path=courses"

Notifications, recherche et statistiques

Un administrateur ne lit et ne modifie que ses propres notifications : les routes prennent l'administrateur dans le jeton. L'API en écrit une pour chacun de ces événements, à chaque administrateur qui détient la permission demandée par l'écran lié :

Un compte administrateur lié à un formateur n'est informé que des cours de ce formateur, et pas des nouvelles inscriptions de comptes. Chaque notification est aussi poussée par le socket /notifications dès son enregistrement.

Cours en direct

Certificats

Assistant IA

Historique des conversations de l'assistant

Serveur MCP

Routes du mode démo

Passerelles de paiement personnalisées