API Xamle

URL de base & en-têtes

Toutes les routes sont préfixées par /api/v1. Une documentation Swagger interactive est exposée par le serveur sur /api/docs.

Identifier l'application : X-App-Key

La plateforme est multi-applications. Chaque requête est rattachée à une application via un en-tête :

Sans en-tête, la requête est rattachée à l'application par défaut de la plateforme (rétrocompatibilité). Les routes strictement mobiles comme GET /mobile/config exigent X-App-Key.

{
  "success": true,
  "data": {
    "app": { "id": "…", "slug": "xamle", "name": "Xamle" },
    "capabilities": { "managesUsers": true, "managesAnalytics": true, "hasFeed": true },
    "features": ["engagement.feed", "engagement.agents", "…"],
    "branding": { /* thème Design Manager ou null */ },
    "profileFields": [ /* champs du profil déclarés */ ]
  }
}

Authentification

Deux populations, deux flux — dans les deux cas l'API délivre un couple access token + refresh token (JWT signés RS256) à passer en Authorization: Bearer <accessToken>. L'access token expire après 15 minutes ; le refresh token (7 jours) permet de renouveler la session avec rotation.

Comptes équipe (backoffice)

Connexion par e-mail et mot de passe. Si la 2FA est activée sur le compte, la réponse contient requires2FA et un tempToken à échanger avec le code à 6 chiffres.

# Connexion d'un compte équipe
curl -X POST https://<domaine-api>/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "vous@exemple.sn", "password": "…" }'

# → { "success": true, "data": { "accessToken": "…", "refreshToken": "…", "expiresIn": 900 } }
# ou, si 2FA active : { "requires2FA": true, "tempToken": "…" } → POST /auth/2fa/verify

const res = await fetch("https://<domaine-api>/api/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password })
});
const { data } = await res.json();  // { accessToken, refreshToken, expiresIn }
const me = await fetch("…/api/v1/auth/me", {
  headers: { Authorization: "Bearer " + data.accessToken }
});

Apprenants (mobile) — OTP par SMS

Pas de mot de passe côté apprenant : la connexion se fait par numéro de téléphone + code SMS à 4 chiffres (valable 5 minutes). Un mode invité anonyme permet d'explorer l'app ; la session invité est fusionnée au compte lors de la vérification.

Réponses & erreurs

Toutes les réponses sont enveloppées de façon uniforme.

Succès

{ "success": true, "data": { /* payload */ }, "timestamp": "2026-09-07T10:00:00.000Z" }

Listes paginées

Les listes acceptent ?page= et ?limit= et renvoient un bloc meta :

{
  "success": true,
  "data": [ /* éléments */ ],
  "meta": { "page": 1, "limit": 20, "total": 137, "totalPages": 7,
            "hasNextPage": true, "hasPrevPage": false }
}

Erreurs

{
  "success": false,
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [ /* détails éventuels */ ],
  "requestId": "…",
  "timestamp": "…",
  "path": "/api/v1/…"
}

Chaque réponse porte un requestId (repris de l'en-tête X-Request-ID si fourni) : joignez-le à vos signalements de bug.

Endpoints mobiles

Référence des routes consommées par les applications apprenantes (et le SDK). Sauf mention public, elles exigent un JWT apprenant.

Contenus & programmes

Progression & évaluations

Feed, profil & codes

API d'administration (backoffice)

Tout ce que fait la console passe par l'API d'administration, sous /api/v1/admin/*. Chaque requête porte le JWT d'un compte équipe (Authorization: Bearer …) et l'en-tête X-App-Id pour désigner l'application de travail. Chaque route exige une permission précise (format module:action) : sans elle → 403. Quelques opérations destructives sont réservées au rôle Admin.

Équipe, rôles & applications

Contenus (bibliothèque)

Programmes, modules & évaluations

Diffusion & engagement

Utilisateurs mobiles, analytics & système

Collecte analytics

Les événements produit sont envoyés par lots (1 à 500 événements) et acceptés en 202 Accepted : la validation métier et l'agrégation se font ensuite en file de traitement. L'authentification est optionnelle — les événements anonymes sont acceptés, et si un JWT apprenant est présent, l'identité de confiance est résolue côté serveur.

{
  "events": [
    {
      "event_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",  // unique — sert à la déduplication
      "event_name": "lesson_completed",
      "timestamp_occurred": "2026-09-07T14:22:05.120Z",
      "anonymous_id": "device_3f9a2b1c",               // requis
      "session_id": "sess_2cb9e8a1",
      "source": "client",                                // "client" | "server"
      "context": { "app_version": "1.4.0", "platform": "android", "language": "fr" },
      "properties": { "lesson_id": "…", "program_id": "…" }
    }
  ]
}
// → { "accepted": 1, "rejected": 0, "rejected_ids": [] }

Règles

SDK mobile Flutter

Le SDK officiel est un monorepo de 7 packages Flutter/Dart (repo xamle-mobile-sdk, releases coordonnées — tous les packages portent la même version, actuellement v0.9.1). Chaque package couvre un domaine ; vous n'embarquez que ce dont votre app a besoin. Prérequis : Dart ≥ 3.8, Flutter ≥ 3.24.

Installation (dépendance git)

Le repo est privé et rien n'est publié sur pub.dev : chaque package se consomme en dépendance git, tous épinglés sur la même ref. Les dépendances entre packages sont résolues automatiquement dans le clone.

dependencies:
  xamle_sdk_core:
    git: { url: https://github.com/Xamle-tech/xamle-mobile-sdk.git, ref: v0.9.1, path: packages/xamle_sdk_core }
  xamle_sdk_auth:
    git: { url: https://github.com/Xamle-tech/xamle-mobile-sdk.git, ref: v0.9.1, path: packages/xamle_sdk_auth }
  xamle_sdk_content:
    git: { url: https://github.com/Xamle-tech/xamle-mobile-sdk.git, ref: v0.9.1, path: packages/xamle_sdk_content }
  xamle_sdk_analytics:
    git: { url: https://github.com/Xamle-tech/xamle-mobile-sdk.git, ref: v0.9.1, path: packages/xamle_sdk_analytics }
  # optionnels : xamle_sdk_offline, xamle_ui_player, xamle_sdk_partner (même url/ref)

Initialisation

XamleSdk.init est le point d'entrée unique. Il charge GET /mobile/config (avec cache disque : l'app démarre même hors-ligne dès le second lancement), fige les capacités de l'application et choisit le mode :

final sdk = await XamleSdk.init(
  appKey: 'xk_live_…',                       // clé de l'application (console → Réglages)
  baseUrl: 'https://<domaine-api>/api/v1',   // requis
  // externalUserId: 'user-42',              // requis en mode contentOnly uniquement
  deepLinks: [XamleDeepLink(key: 'program', label: 'Programme')], // écrans notifiables
);

sdk.config.name;              // nom de l'app
sdk.mode;                     // XamleMode.managed | contentOnly
sdk.capabilities.hasFeed;     // capacités figées à l'init
sdk.features.contentPrograms; // modules activés dans la console

Les gates de fonctionnalités sont intégrés : chaque repository vérifie que le module correspondant est activé pour l'app et lève une XamleCapabilityError explicite sinon — vos écrans peuvent aussi tester sdk.features.has(…) pour se masquer.

xamle_sdk_core — le socle

Un client HTTP unique (dio) que tous les packages partagent, avec quatre interceptors : en-tête X-App-Key systématique, Authorization: Bearer automatique, refresh sur 401 protégé par mutex (une seule requête de refresh même si dix appels échouent en même temps), et retry exponentiel sur erreurs 5xx/réseau (300 ms → 800 ms → 2 s).

Les tokens vivent dans un TokenStore chiffré (flutter_secure_storage — Keychain iOS, EncryptedSharedPreferences Android, avec récupération automatique si le stockage est corrompu). Les erreurs sont typées : XamleAuthError, XamleValidationError, XamleNetworkError, XamleCapabilityError, XamleConfigError — un simple on XamleAuthError suffit pour router vers l'écran de connexion.

xamle_sdk_auth — connexion apprenant (managed)

final auth = AuthRepository();  // ⚠️ à créer dès le boot : c'est elle qui branche
                                //    le refresh automatique des tokens sur le client

// Mode invité (exploration sans compte)
final guest = await auth.signInAsGuest();

// Connexion par OTP
final req = await auth.requestOtp('+221771234567');
final res = await auth.verifyOtp(phoneNumber: '+221771234567', code: '1234',
                                guestToken: guest.accessToken); // fusionne la session invité

if (res.needsProfileCompletion) {
  // Champs du profil configurés dans la console (dont « Code agent »)
  final schema = await ProfileRepository().getFields();
  await ProfileRepository().submitValues({'full_name': 'Awa Diop', 'code_agent': 'AWA-763'});
}

Autres méthodes : me() (profil + champs manquants), currentAccessToken(), logout() (efface les tokens locaux), updateProfile(…). Les repositories sont sans état : la session persistée vit dans le TokenStore ; la gestion d'état UI (Riverpod, Bloc…) reste celle de votre app.

xamle_sdk_content — contenus & progression

Huit repositories, un par domaine — tous branchés sur le client du core :

Les titres sont des I18nString : title.resolve('wo') renvoie la traduction demandée avec repli sur le français. Chaque leçon expose playbackUrl (HLS adaptatif) et moments (puces horodatées) — à passer tels quels au player.

xamle_sdk_analytics — collecte fiabilisée

await XamleAnalytics.instance.start();   // après XamleSdk.init

MaterialApp(
  navigatorObservers: [XamleAnalytics.instance.navigatorObserver], // screen_viewed auto
  ...
);

await XamleAnalytics.instance.track('lesson_completed',
    properties: {'lesson_id': id, 'program_id': programId});

Sous le capot : file SQLite locale (cap 2 000 événements), envoi par lots gzip toutes les 15 s vers POST /analytics/events, reprise avec backoff exponentiel après coupure, sessions automatiques (timeout 30 min), événements de cycle de vie (app_opened, session_started…) et contexte device injecté (modèle, OS, réseau, version d'app via AnalyticsConfig(appVersion: …)).

xamle_ui_player — lecteurs prêts à l'emploi

Deux widgets autonomes (aucune dépendance au reste du SDK), thémables et localisables :

XamleVideoPlayer(
  source: XamleVideoSource.network(lesson.playbackUrl!),
  moments: lesson.moments.map(XamlePlayerMoment.fromJson).toList(),
  startAt: Duration(seconds: lastPosition),         // reprise de lecture
  onProgress: (position, duration, completed) =>
      progress.reportLesson(lessonId: lesson.id,     // toutes les 5 s + pause + fin
        positionSeconds: position.inSeconds, completed: completed),
  onMomentTap: (m) => m.isQuiz ? openQuiz(m.targetId) : openGlossary(m.targetId),
)

XamleAudioPlayer(
  source: XamleAudioSource.network(url),
  title: lesson.title.resolve(),
  speeds: [1.0, 1.25, 1.5, 2.0],                     // vitesse, avance/recul 10 s
)

XamleVideoPlayer affiche les moments comme marqueurs sur la barre et puces cliquables au bon instant — l'ouverture du quiz ou de la fiche glossaire reste à la main de votre app (onMomentTap). onProgress est calibré pour alimenter reportLesson sans réglage.

xamle_sdk_offline — hors-ligne

OfflineRepository parle au serveur (catalogue des ressources téléchargeables, manifeste des fichiers, journalisation) ; OfflineStore gère l'appareil : download(type, targetId, onProgress) télécharge tous les fichiers d'un programme/module avec progression globale, downloaded() liste le local, localPath(…) donne le chemin à passer à XamleVideoSource.file(…), syncAll() met à jour ce qui a changé, delete(…) libère l'espace.

xamle_sdk_partner — app « Pro » partenaire

Pour l'application des partenaires (auto-écoles) : candidature et suivi d'agrément (me(), apply(…), upload du justificatif), tableau de bord (hub()), liste des élèves filtrable/triable, enregistrement des paiements par tranche (recordPayment — espèces, Wave, Orange Money…, annulable 48 h), encouragements et relances, gains (commissions + primes par période) et outils de partage (affiche PDF avec QR code). L'authentification est celle de xamle_sdk_auth (OTP) sur l'application Pro et sa propre clé.

Ordre d'intégration recommandé (managed)

Points d'attention

Sécurité & limites de débit

Permissions

Les comptes équipe portent des permissions au format module:action (ex. contents:write, notifications:send, agents:read), issues de l'union de leurs rôles. Une route protégée sans la permission requise répond 403 — de même qu'une requête sur une application hors de votre périmètre.

Limites de débit

Une réponse 429 indique un dépassement : espacez vos requêtes et privilégiez les envois par lots (analytics) plutôt que les appels unitaires.

Bonnes pratiques