Comment intégrer l'API TalentLMS en 2026 (Tutoriel)

Introduction

TalentLMS est une plateforme LMS cloud puissante pour déployer des formations en ligne scalables, utilisée par plus de 25 000 organisations. En 2026, son API REST v1 reste le standard pour les intégrations automatisées : synchronisation d'utilisateurs depuis un CRM, création dynamique de cours depuis une base de données, ou envoi de certificats via webhooks.

Ce tutoriel intermédiaire vous guide pour intégrer l'API TalentLMS dans une application Node.js avec TypeScript. Vous apprendrez à configurer l'authentification Basic Auth (domain + API key), à lister les utilisateurs, créer un cours, et gérer les erreurs. Chaque étape inclut du code complet et fonctionnel, prêt à copier-coller. À la fin, vous maîtriserez une intégration robuste, évitant les pièges courants comme les rate limits (100 req/min).

Pourquoi c'est crucial ? Les équipes RH automatisent 70% des inscriptions via API, réduisant les tâches manuelles de 80%. Prêt à booster votre stack formation ? (128 mots)

Prérequis

Compte TalentLMS actif (plan Starter suffisant pour tester l'API).
Clé API générée dans Account & Settings > API Authentication (format : api_key:secret).
Domaine TalentLMS (ex: mondomaine.talentlms.com).
Node.js 20+ et npm/yarn installés.
Connaissances de base en TypeScript et fetch/axios.
Éditeur comme VS Code avec extension TypeScript.

Initialiser le projet Node.js

terminal

mkdir talentlms-integration
cd talentlms-integration
npm init -y
npm install typescript @types/node axios dotenv
npm install -D ts-node nodemon
npx tsc --init
mkdir src

Cette commande crée un projet Node.js propre, installe axios pour les appels HTTP, dotenv pour les variables d'environnement, et TypeScript pour la typage statique. ts-node permet d'exécuter directement les fichiers TS. Évitez yarn si vous ciblez npm pour la prod.

Configurer les variables d'environnement

Créez un fichier .env à la racine pour stocker vos credentials TalentLMS de manière sécurisée. Ne commitez jamais ce fichier (ajoutez-le à .gitignore). L'API utilise Basic Auth : encodez api_key:secret en base64.

Fichier de configuration .env et types

src/config.ts

import dotenv from 'dotenv';
dotenv.config();

export interface TalentLMSConfig {
  domain: string;
  apiKey: string;
  apiSecret: string;
  baseUrl: string;
}

export const config: TalentLMSConfig = {
  domain: process.env.TALENTLMS_DOMAIN || 'mondomaine.talentlms.com',
  apiKey: process.env.TALENTLMS_API_KEY || '',
  apiSecret: process.env.TALENTLMS_API_SECRET || '',
  baseUrl: `https://${process.env.TALENTLMS_DOMAIN || 'mondomaine.talentlms.com'}/api/v1`,
};

if (!config.apiKey || !config.apiSecret) {
  throw new Error('TALENTLMS_API_KEY et TALENTLMS_API_SECRET manquants dans .env');
}

Ce module charge les env vars et définit une interface TypeScript pour la config. Il valide les credentials au démarrage, évitant des erreurs runtime. Utilisez-le partout pour centraliser l'accès API, comme une 'boîte à outils' unique.

Implémenter l'authentification Basic Auth

TalentLMS requiert un header Authorization: Basic . Créons un helper réutilisable pour générer ce token, avec retry sur 401 Unauthorized.

Module d'authentification

src/auth.ts

import axios, { AxiosInstance, AxiosError } from 'axios';
import { config } from './config';

const authToken = Buffer.from(`${config.apiKey}:${config.apiSecret}`).toString('base64');

export const apiClient: AxiosInstance = axios.create({
  baseURL: config.baseUrl,
  timeout: 10000,
  headers: {
    'Authorization': `Basic ${authToken}`,
    'Content-Type': 'application/json',
  },
});

apiClient.interceptors.response.use(
  (response) => response,
  (error: AxiosError) => {
    if (error.response?.status === 401) {
      throw new Error('Authentification échouée : vérifiez api_key et secret');
    }
    if (error.response?.status === 429) {
      throw new Error('Rate limit dépassé : attendez 1 min');
    }
    return Promise.reject(error);
  }
);

export default apiClient;

Ce client Axios préconfigure l'auth Basic et gère les erreurs courantes (401, 429) via interceptors. Réutilisable pour tous les endpoints, il timeout à 10s pour éviter les blocages. Testez-le avec un GET /courses pour valider.

Lister les utilisateurs

Endpoint : GET /users. Paramètres optionnels : page=1, per_page=50. Réponse JSON avec users[] incluant id, email, firstname.

Script pour lister les users

src/users.ts

import apiClient from './auth';

interface TalentLMSUser {
  id: number;
  email: string;
  firstname: string;
  lastname: string;
  status: string;
}

interface UsersResponse {
  users: TalentLMSUser[];
  page: number;
  per_page: number;
  total_pages: number;
}

export async function listUsers(page: number = 1, perPage: number = 20): Promise<UsersResponse> {
  try {
    const response = await apiClient.get<UsersResponse>('/users', {
      params: { page, 'per_page': perPage },
    });
    console.log(`Page ${page} : ${response.data.users.length} users trouvés.`);
    return response.data;
  } catch (error) {
    console.error('Erreur lors du listage users:', error);
    throw error;
  }
}

// Exemple d'usage
if (import.meta.url === `file://${process.argv[1]}`) {
  listUsers().then(console.log).catch(console.error);
}

Ce script typé fetch la liste paginée d'utilisateurs et log les résultats. Utilisez page et per_page pour scaler (max 100). Lancez avec ts-node src/users.ts après avoir sourcé .env.

Créer un nouveau cours

Endpoint : POST /courses. Corps JSON : {name, description, price}. Réponse : {success: true, id: 123}. Vérifiez les quotas (500 cours max/plan).

Script pour créer un cours

src/courses.ts

import apiClient from './auth';

export interface CreateCoursePayload {
  name: string;
  description?: string;
  price: number;
  catalog_visibility?: 'public' | 'private';
}

export interface CourseResponse {
  success: boolean;
  id: number;
}

export async function createCourse(payload: CreateCoursePayload): Promise<CourseResponse> {
  try {
    const response = await apiClient.post<CourseResponse>('/courses', payload);
    console.log(`Cours créé avec ID: ${response.data.id}`);
    return response.data;
  } catch (error) {
    console.error('Erreur création cours:', error);
    throw error;
  }
}

// Exemple
if (import.meta.url === `file://${process.argv[1]}`) {
  createCourse({
    name: 'Introduction à TypeScript 2026',
    description: 'Cours avancé sur les generics et async.',
    price: 49.99,
    catalog_visibility: 'public',
  }).then(console.log).catch(console.error);
}

Ce code POST un cours avec validation via interface TS. catalog_visibility contrôle l'accès. Gérez les duplicatas (erreur 400 si nom existe). Idéal pour automatiser depuis un CMS.

Inscrire un user à un cours

Endpoint : POST /users/{user_id}/courses. Corps : {course_id: 123}. Utile pour onboarding automatisé.

Script d'inscription user-cours

src/enrollments.ts

import apiClient from './auth';

export interface EnrollmentPayload {
  course_id: number;
}

export async function enrollUser(userId: number, payload: EnrollmentPayload): Promise<{success: boolean}> {
  try {
    const response = await apiClient.post(`users/${userId}/courses`, payload);
    console.log(`User ${userId} inscrit au cours ${payload.course_id}`);
    return { success: true };
  } catch (error) {
    console.error('Erreur inscription:', error);
    return { success: false };
  }
}

// Exemple : user 42 au cours 123
if (import.meta.url === `file://${process.argv[1]}`) {
  enrollUser(42, { course_id: 123 }).then(console.log);
}

POST pour inscrire un user spécifique. Vérifiez user_id et course_id via listUsers/createCourse. Retourne booléen pour chaining. Évitez les inscriptions multiples (API ignore silencieusement).

Script principal d'intégration

src/index.ts

#!/usr/bin/env node
import { listUsers } from './users';
import { createCourse } from './courses';
import { enrollUser } from './enrollments';

async function main() {
  console.log('🚀 Début intégration TalentLMS');
  
  // 1. Lister users
  const users = await listUsers(1, 5);
  console.table(users.users.slice(0, 3));
  
  // 2. Créer cours
  const newCourse = await createCourse({
    name: 'API Mastery 2026',
    price: 99.99,
  });
  
  // 3. Inscrire premier user
  if (users.users[0]) {
    await enrollUser(users.users[0].id, { course_id: newCourse.id });
  }

  console.log('✅ Intégration terminée');
}

main().catch(console.error);

Script orchestrateur combinant toutes les fonctions. Exécutez avec ts-node src/index.ts. Chaine les ops pour un flux complet : list > create > enroll. Ajoutez try/catch pour prod.

Ajouter un package.json script

Mettez à jour package.json pour des commandes faciles.

Scripts npm dans package.json

package.json

{
  "name": "talentlms-integration",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "nodemon --exec ts-node src/index.ts",
    "start": "ts-node src/index.ts",
    "users": "ts-node src/users.ts",
    "courses": "ts-node src/courses.ts"
  },
  "dependencies": {
    "axios": "^1.7.2",
    "dotenv": "^16.4.5",
    "typescript": "^5.5.3"
  },
  "devDependencies": {
    "@types/node": "^22.3.0",
    "ts-node": "^10.9.2",
    "nodemon": "^3.1.4"
  }
}

Ajoute des scripts npm pour hot-reload (dev) et exécution one-shot. type: module active ES modules pour imports modernes. Lancez npm run start après .env.

Bonnes pratiques

Rate limiting : Implémentez un délai de 600ms entre req (100/min max). Utilisez p-limit pour concurrency.
Sécurité : Stockez jamais credentials en dur ; utilisez AWS Secrets ou Vault pour prod.
Pagination : Bouclez sur total_pages pour >100 users, avec offset pour éviter doublons.
Logging : Intégrez Winston ou Pino pour tracer les appels API en prod.
Typage complet : Étendez les interfaces depuis la doc API TalentLMS pour auto-complétion VS Code.

Erreurs courantes à éviter

401 Unauthorized : Vérifiez encoding base64 exact (api_key:secret, sans espaces). Regénérez la clé si expirée.
404 Not Found : Domaine mal orthographié (ex: mondomaine sans .talentlms.com).
422 Validation : Corps JSON invalide (ex: price négatif). Validez payload client-side.
CORS en frontend : API TalentLMS bloque browser ; utilisez proxy Next.js ou server-side only.

Pour aller plus loin

Explorez les webhooks TalentLMS pour notifs en temps réel (ex: user_completed_course).
Intégrez avec Zapier ou n8n pour no-code workflows.
Migrez vers GraphQL si >10k users (beta 2026).
Doc officielle API.

Découvrez nos formations Learni sur les LMS et APIs pour maîtriser H5P, SCORM et plus.

Comment intégrer l'API TalentLMS en 2026