Intégrer l'API EventCollab dans une application Flutter

Le socle technique à écrire une fois : client HTTP, enveloppe de réponse, stockage du jeton, puis le code des parcours qui réservent des surprises. Chaque extrait indique le fichier où il va. La liste des endpoints est dans la référence mobile ; ce document explique comment les consommer.

Les trois pièges qui coûtent une journée
  • Une seule session par compte. Chaque connexion révoque tous les jetons existants, tous appareils confondus. Se connecter sur mobile déconnecte le site, et inversement.
  • success: true ne veut pas dire « connecté ». Une connexion avec double authentification répond 200 avec success: true et data.two_factor_required, sans jeton.
  • Un nom de fichier accentué fait échouer l'envoi. Le pare-feu de l'hébergeur renvoie 403 avant Laravel, sans en-tête CORS ni trace dans les logs. Or une photo d'écran s'appelle « capture d'écran.png ».

Démarrer

pubspec.yaml
dependencies:
  flutter:
    sdk: flutter

  # Réseau
  dio: ^5.7.0                     # interceptors, FormData, annulation
  # Stockage du jeton — jamais SharedPreferences pour un jeton
  flutter_secure_storage: ^9.2.2  # Keychain (iOS) / Keystore (Android)

  # État — au choix ; les exemples utilisent provider
  provider: ^6.1.2

  # Médias
  image_picker: ^1.1.2
  image_cropper: ^8.0.2           # recadrage carré de l'avatar
  video_player: ^2.9.2            # lecture de la fenêtre des statuts
  cached_network_image: ^3.4.1
  file_picker: ^8.1.4             # CV pour les candidatures

  path: ^1.9.0                    # basename du fichier à envoyer
  intl: ^0.19.0                   # dates et montants en fr

Deux remarques. flutter_secure_storage n'est pas une préférence de confort : un jeton Sanctum n'expire jamais, il doit vivre dans le trousseau du système. Et aucun paquet de notifications poussées n'est listé — le serveur n'en expose pas, voir Notifications.

Arborescence

Le découpage qui tient sur la durée : le dossier core ne connaît rien du métier, les repositories ne connaissent rien de l'interface.

lib/
lib/
  main.dart
  core/
    api_config.dart        # URL de base, délais
    api_result.dart        # l'enveloppe {success, message, data}
    api_client.dart        # Dio + interceptors
    session_store.dart     # le jeton dans le trousseau
    errors.dart            # DioException -> message en français
    file_name.dart         # assainissement des noms de fichiers
    json.dart              # asDouble, asInt, asDate
  models/
    user.dart  event.dart  post.dart  app_status.dart
    event_access.dart  page.dart
  repositories/
    auth_repository.dart   event_repository.dart
    feed_repository.dart   payment_repository.dart
  features/
    auth/  feed/  events/  payment/  notifications/

Configuration

L'URL de base ne se code pas en dur dans le code métier : elle change entre le poste de développement et la production.

lib/core/api_config.dart
class ApiConfig {
  /// Surchargeable au build :
  ///   flutter run --dart-define=API_BASE_URL=http://10.0.2.2:8000/api/v1
  static const String baseUrl = String.fromEnvironment(
    'API_BASE_URL',
    defaultValue: 'https://collab-api.eventcollab.io/api/v1',
  );

  static const Duration connectTimeout = Duration(seconds: 15);

  /// Généreux volontairement. Les emails partent de façon SYNCHRONE côté
  /// serveur (aucune file d'attente) : « mot de passe oublié » et l'envoi
  /// d'un code de vérification prennent 3 à 7 secondes. Un délai de 10 s
  /// ferait échouer des requêtes qui aboutissent.
  static const Duration receiveTimeout = Duration(seconds: 40);
}
Sur émulateur

localhost depuis un émulateur Android désigne l'émulateur lui-même. Utilisez 10.0.2.2 pour joindre la machine hôte (127.0.0.1 fonctionne sur le simulateur iOS). Et lancez php artisan serve --host=0.0.0.0 pour un appareil physique.

L'enveloppe en Dart

Toute réponse de l'API a la même forme : {success, message, data}, plus errors en cas de validation. Un seul type la représente, et tout le reste du code en dépend.

lib/core/api_result.dart
/// Une réponse de l'API, succès comme échec. Jamais d'exception pour un
/// 401/403/422 : ce sont des réponses métier que l'interface doit présenter.
class ApiResult<T> {
  const ApiResult({
    required this.status,
    required this.success,
    required this.message,
    this.data,
    this.errors = const {},
  });

  final int status;                        // 0 = la requête n'a pas abouti
  final bool success;
  final String message;                    // toujours affichable à l'écran
  final T? data;
  final Map<String, List<String>> errors;  // {champ: [messages]}

  bool get ok => success && status >= 200 && status < 300;

  /// Session morte : à distinguer d'un mauvais mot de passe, voir api_client.
  bool get unauthenticated => status == 401;

  /// Accès refusé — sur l'espace d'un événement, c'est un verrou, pas un bug.
  bool get forbidden => status == 403;

  /// Premier message d'erreur d'un champ, pour le poser sous le TextField.
  String? fieldError(String field) => errors[field]?.first;

  ApiResult<R> failure<R>() => ApiResult<R>(
        status: status, success: false, message: message, errors: errors,
      );
}

/// Décode l'enveloppe. `parse` transforme `data` en modèle ; omis, on ignore
/// le contenu (utile pour un POST dont seul le succès compte).
ApiResult<T> decodeEnvelope<T>(
  int status,
  dynamic body,
  T Function(dynamic json)? parse,
) {
  if (body is! Map) {
    return ApiResult<T>(
      status: status,
      success: false,
      message: 'Réponse inattendue du serveur.',
    );
  }

  final map = body.cast<String, dynamic>();
  final success = map['success'] == true;
  final message = (map['message'] as String?)?.trim() ?? '';
  final raw = map['data'];

  return ApiResult<T>(
    status: status,
    success: success,
    message: message.isNotEmpty ? message : _fallbackMessage(status),
    data: success && parse != null && raw != null ? parse(raw) : null,
    errors: _parseErrors(map['errors']),
  );
}

Map<String, List<String>> _parseErrors(dynamic errors) {
  if (errors is! Map) return const {};
  return errors.map((key, value) => MapEntry(
        key.toString(),
        value is List
            ? value.map((e) => e.toString()).toList()
            : [value.toString()],
      ));
}

String _fallbackMessage(int status) => switch (status) {
      401 => 'Session expirée. Reconnectez-vous.',
      403 => 'Accès refusé.',
      404 => 'Introuvable.',
      422 => 'Données invalides.',
      _ => 'Une erreur est survenue.',
    };
Pourquoi pas d'exceptions

Un 422 de validation et un 403 « paiement en attente » sont des réponses normales du produit : ils doivent remonter jusqu'au widget qui affichera le message ou l'écran de paiement. Les transformer en exceptions oblige à des try/catch partout et fait perdre errors. Seule une panne réseau mérite d'être traitée à part, et elle est convertie en ApiResult avec status: 0.

Le client HTTP

Un seul endroit pose Accept: application/json et le jeton. C'est aussi le seul endroit qui décide qu'une session est morte.

lib/core/api_client.dart
import 'package:dio/dio.dart';

class ApiClient {
  ApiClient._(this._dio, this._session);

  final Dio _dio;
  final SessionStore _session;

  /// `onSessionExpired` est appelé une seule fois, quand un jeton valide a
  /// été refusé : au-dessus, l'application vide son état et renvoie à l'écran
  /// de connexion en mémorisant la destination.
  factory ApiClient(SessionStore session, {VoidCallback? onSessionExpired}) {
    final dio = Dio(BaseOptions(
      baseUrl: ApiConfig.baseUrl,
      connectTimeout: ApiConfig.connectTimeout,
      receiveTimeout: ApiConfig.receiveTimeout,
      headers: {
        // INDISPENSABLE. Sans cet en-tête, Laravel tente une redirection HTML
        // sur les routes protégées et renvoie un 500 au lieu d'un 401.
        'Accept': 'application/json',
      },
      // On veut traiter 401/403/404/422 comme des réponses, pas des jets.
      validateStatus: (code) => code != null && code < 500,
    ));

    dio.interceptors.add(InterceptorsWrapper(
      onRequest: (options, handler) async {
        final token = await session.readToken();
        if (token != null) {
          options.headers['Authorization'] = 'Bearer $token';
          // On note qu'un jeton est parti : c'est ce qui permet de distinguer
          // « session morte » de « mauvais identifiants » à la réponse.
          options.extra['sentToken'] = true;
        }
        handler.next(options);
      },
      onResponse: (response, handler) {
        final sentToken = response.requestOptions.extra['sentToken'] == true;

        // PIÈGE : /auth/login répond 401 « Identifiants incorrects » quand le
        // mot de passe est faux. Vider le trousseau et renvoyer à la connexion
        // dans ce cas provoquerait une boucle. Un 401 n'est une expiration que
        // si un jeton avait bien été envoyé.
        if (response.statusCode == 401 && sentToken) {
          session.clear();
          onSessionExpired?.call();
        }
        handler.next(response);
      },
    ));

    return ApiClient._(dio, session);
  }

  Future<ApiResult<T>> get<T>(
    String path, {
    Map<String, dynamic>? query,
    T Function(dynamic)? parse,
    CancelToken? cancelToken,
  }) =>
      _send(() => _dio.get(path, queryParameters: query, cancelToken: cancelToken), parse);

  Future<ApiResult<T>> post<T>(
    String path, {
    Object? body,
    T Function(dynamic)? parse,
  }) =>
      _send(() => _dio.post(path, data: body), parse);

  Future<ApiResult<T>> put<T>(String path, {Object? body, T Function(dynamic)? parse}) =>
      _send(() => _dio.put(path, data: body), parse);

  Future<ApiResult<T>> delete<T>(String path, {T Function(dynamic)? parse}) =>
      _send(() => _dio.delete(path), parse);

  /// Envoi multipart. Le nom de fichier est assaini ici, à l'unique endroit
  /// par lequel passent tous les envois — voir « Envoi de fichiers ».
  Future<ApiResult<T>> upload<T>(
    String path, {
    required String field,
    required String filePath,
    Map<String, dynamic> fields = const {},
    T Function(dynamic)? parse,
    void Function(int sent, int total)? onProgress,
  }) async {
    final form = FormData.fromMap({
      ...fields,
      field: await MultipartFile.fromFile(
        filePath,
        filename: sanitizeFileName(basename(filePath)),
      ),
    });

    return _send(
      () => _dio.post(path, data: form, onSendProgress: onProgress),
      parse,
    );
  }

  Future<ApiResult<T>> _send<T>(
    Future<Response> Function() call,
    T Function(dynamic)? parse,
  ) async {
    try {
      final res = await call();
      return decodeEnvelope<T>(res.statusCode ?? 0, res.data, parse);
    } on DioException catch (e) {
      return ApiResult<T>(status: 0, success: false, message: describeError(e));
    }
  }
}
lib/core/errors.dart
String describeError(DioException e) => switch (e.type) {
      DioExceptionType.connectionTimeout ||
      DioExceptionType.sendTimeout ||
      DioExceptionType.receiveTimeout =>
        'Le serveur met trop de temps à répondre. Réessayez.',
      DioExceptionType.connectionError =>
        'Pas de connexion. Vérifiez votre réseau.',
      DioExceptionType.badCertificate =>
        'Certificat du serveur refusé.',
      DioExceptionType.cancel => 'Requête annulée.',
      // validateStatus laisse passer < 500 : ici, c'est une panne serveur.
      _ => _serverMessage(e),
    };

String _serverMessage(DioException e) {
  final code = e.response?.statusCode;

  // Le 403 du pare-feu sur un nom de fichier interdit arrive SANS corps JSON.
  // Il ne faut pas l'annoncer comme une panne réseau : le message serait
  // trompeur et personne ne chercherait du côté du nom de fichier.
  if (code == 403 && e.response?.data is! Map) {
    return 'Envoi refusé par le serveur. Renommez le fichier sans accent '
        'ni apostrophe, puis réessayez.';
  }
  if (code != null && code >= 500) {
    return 'Le serveur a rencontré une erreur ($code). Réessayez plus tard.';
  }
  return 'Une erreur est survenue.';
}

Stockage du jeton

lib/core/session_store.dart
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

/// Le jeton Sanctum n'expire pas : il reste valable jusqu'à une déconnexion
/// ou une nouvelle connexion (qui révoque tout). Il a donc sa place dans le
/// trousseau du système, et nulle part ailleurs.
class SessionStore {
  static const _key = 'eventcollab.token';

  static const _storage = FlutterSecureStorage(
    aOptions: AndroidOptions(encryptedSharedPreferences: true),
    iOptions: IOSOptions(accessibility: KeychainAccessibility.first_unlock),
  );

  String? _cached;
  bool _loaded = false;

  Future<String?> readToken() async {
    if (!_loaded) {
      _cached = await _storage.read(key: _key);
      _loaded = true;
    }
    return _cached;
  }

  Future<void> save(String token) async {
    _cached = token;
    _loaded = true;
    await _storage.write(key: _key, value: token);
  }

  Future<void> clear() async {
    _cached = null;
    _loaded = true;
    await _storage.delete(key: _key);
  }
}

Le drapeau _loaded compte : sans lui, un _cached ??= await read() relit le trousseau à chaque requête tant que la valeur est nulle, c'est-à-dire sur toute la navigation avant connexion.

Au démarrage

Un jeton stocké ne prouve pas que la session vit : elle a pu être révoquée par une connexion ailleurs. Validez-la avec GET /auth/me avant d'afficher l'écran d'accueil.

lib/features/auth/boot.dart
Future<User?> restoreSession(ApiClient api, SessionStore session) async {
  if (await session.readToken() == null) return null;

  final res = await api.get<User>('/auth/me', parse: (d) => User.fromJson(d));

  // 401 : l'interceptor a déjà vidé le trousseau. On repart propre.
  // status 0 : pas de réseau — on ne détruit SURTOUT pas la session, on
  // laisse l'utilisateur réessayer, sinon un métro sans réseau déconnecte.
  if (res.unauthenticated) return null;
  return res.data;
}

Authentification

La connexion a trois issues, pas deux. Un type somme les rend impossibles à confondre, et le compilateur force à traiter le cas 2FA.

lib/repositories/auth_repository.dart
sealed class LoginOutcome {
  const LoginOutcome();
}

class LoginSuccess extends LoginOutcome {
  const LoginSuccess(this.user);
  final User user;
}

/// Connexion suspendue : un code est attendu. AUCUN jeton n'a été délivré.
class LoginNeedsCode extends LoginOutcome {
  const LoginNeedsCode({required this.method, this.sentTo});
  final String method;   // 'app' | 'email' | 'sms'
  final String? sentTo;  // destination masquée, à afficher tel quel
}

class LoginFailed extends LoginOutcome {
  const LoginFailed(this.message, [this.errors = const {}]);
  final String message;
  final Map<String, List<String>> errors;
}

class AuthRepository {
  AuthRepository(this._api, this._session);
  final ApiClient _api;
  final SessionStore _session;

  /// `login` accepte l'email OU le téléphone : c'est un seul champ côté API,
  /// nommé `login`, et non `email`. L'interface ne doit donc pas valider le
  /// format email.
  Future<LoginOutcome> login({
    required String login,
    required String password,
  }) async {
    final res = await _api.post<Map<String, dynamic>>(
      '/auth/login',
      body: {'login': login, 'password': password},
      parse: (d) => (d as Map).cast<String, dynamic>(),
    );

    if (!res.ok || res.data == null) {
      // 401 = identifiants incorrects. 403 = compte désactivé. 422 = champ
      // manquant. Dans les trois cas, `message` est affichable tel quel.
      return LoginFailed(res.message, res.errors);
    }

    final data = res.data!;

    // PIÈGE : on est ici avec success == true et un code HTTP 200, et pourtant
    // la personne n'est pas connectée.
    if (data['two_factor_required'] == true) {
      return LoginNeedsCode(
        method: data['method'] as String? ?? 'app',
        sentTo: data['sent_to'] as String?,
      );
    }

    await _session.save(data['token'] as String);
    return LoginSuccess(User.fromJson(data['user']));
  }

  /// Deuxième étape : on renvoie les identifiants AVEC le code. Le mot de
  /// passe doit donc être gardé en mémoire entre les deux écrans — en
  /// mémoire seulement, jamais écrit sur le disque.
  Future<LoginOutcome> submitTwoFactor({
    required String login,
    required String password,
    required String code,
  }) async {
    final res = await _api.post<Map<String, dynamic>>(
      '/auth/two-factor-challenge',
      body: {'login': login, 'password': password, 'code': code},
      parse: (d) => (d as Map).cast<String, dynamic>(),
    );

    if (!res.ok || res.data?['token'] == null) {
      return LoginFailed(res.message, res.errors);
    }

    await _session.save(res.data!['token'] as String);
    return LoginSuccess(User.fromJson(res.data!['user']));
  }

  /// L'inscription délivre directement un jeton : pas de login à enchaîner.
  /// Le compte n'est pas encore vérifié, mais rien ne le bloque — la
  /// vérification est informative, aucune route ne l'exige.
  Future<ApiResult<User>> register({
    required String name,       // nom de famille
    required String firstName,
    required String email,
    required String password,
    String? phone,
  }) async {
    final res = await _api.post<Map<String, dynamic>>(
      '/auth/register',
      body: {
        'name': name,
        'first_name': firstName,
        'email': email,
        'phone': phone,
        'password': password,
        'password_confirmation': password,
      },
      parse: (d) => (d as Map).cast<String, dynamic>(),
    );

    if (!res.ok || res.data == null) return res.failure<User>();

    await _session.save(res.data!['token'] as String);
    return ApiResult<User>(
      status: res.status,
      success: true,
      message: res.message,
      data: User.fromJson(res.data!['user']),
    );
  }

  /// La déconnexion ne doit jamais dépendre du réseau.
  Future<void> logout() async {
    await _api.post('/auth/logout');
    await _session.clear();
  }
}
Mot de passe oublié : ne révélez rien

POST /auth/forgot-password répond toujours en succès, même pour une adresse inconnue — c'est volontaire. N'affichez jamais « compte introuvable » : montrez « Si un compte existe pour cette adresse, un code vient d'être envoyé. » Et prévoyez un indicateur d'attente, l'envoi est synchrone.

Réagir à l'expiration

Comme une connexion ailleurs révoque le jeton, l'expiration n'est pas un cas rare à traiter un jour : elle arrivera à toute personne qui utilise aussi le site. Branchez-la une fois, au plus haut.

lib/main.dart
final session = SessionStore();
late final ApiClient api;

api = ApiClient(session, onSessionExpired: () {
  // Pas de dialogue : la personne n'a rien fait de mal. On vide l'état, on
  // renvoie à la connexion et on garde la destination pour y revenir.
  appState.clear();
  final current = router.currentRoute;
  router.goToLogin(redirectAfterLogin: current);
  messenger.showSnackBar(const SnackBar(
    content: Text('Votre session a été ouverte sur un autre appareil. '
        'Reconnectez-vous.'),
  ));
});

Modèles & types

Trois détails de typage font planter une application une fois en production, jamais en développement.

ChampCe qu'on attendCe qui arrive
registration_fee, amount double Un String : MySQL renvoie les colonnes decimal en chaîne. as double jette.
notifications[].id int Un UUID : les notifications Laravel ont une clé texte. Les autres ressources ont bien un int.
media, speakers, program Toujours présents Absents quand la relation n'est pas chargée — ce n'est pas la même chose que vide.
lib/core/json.dart
/// Les décimales MySQL arrivent en chaîne. À utiliser pour tout montant.
double asDouble(dynamic v, [double fallback = 0]) => switch (v) {
      null => fallback,
      num n => n.toDouble(),
      String s => double.tryParse(s) ?? fallback,
      _ => fallback,
    };

int asInt(dynamic v, [int fallback = 0]) => switch (v) {
      null => fallback,
      num n => n.toInt(),
      String s => int.tryParse(s) ?? fallback,
      _ => fallback,
    };

DateTime? asDate(dynamic v) =>
    v is String && v.isNotEmpty ? DateTime.tryParse(v)?.toLocal() : null;

/// Une relation non chargée est absente, pas vide : on retombe sur une liste
/// vide sans distinguer les deux, c'est ce que l'interface veut.
List<T> asList<T>(dynamic v, T Function(dynamic) item) =>
    v is List ? v.map(item).toList() : const [];
lib/models/event.dart
class Event {
  const Event({
    required this.uuid,
    required this.title,
    required this.type,
    this.coverImage,
    this.location,
    this.startDate,
    this.registrationFee = 0,
    this.isPaid = false,
    this.webinarUrl,
  });

  /// Les événements se référencent par leur UUID, jamais par l'id numérique.
  final String uuid;
  final String title;
  final String type;        // presentiel | distanciel | hybride | webinaire
  final String? coverImage;
  final String? location;
  final DateTime? startDate;
  final double registrationFee;
  final bool isPaid;

  /// Null tant que l'inscription n'est pas soldée, pour un webinaire. Ne
  /// construisez pas de bouton « Rejoindre » sans vérifier.
  final String? webinarUrl;

  bool get isWebinar => type == 'webinaire';

  factory Event.fromJson(dynamic json) {
    final m = (json as Map).cast<String, dynamic>();
    return Event(
      uuid: m['uuid'] as String,
      title: m['title'] as String? ?? '',
      type: m['type'] as String? ?? 'presentiel',
      coverImage: m['cover_image'] as String?,
      location: m['location'] as String?,
      startDate: asDate(m['start_date']),
      registrationFee: asDouble(m['registration_fee']),
      isPaid: m['is_paid'] == true,
      webinarUrl: m['webinar_url'] as String?,
    );
  }
}

Pagination

Deux formes cohabitent dans l'API et il ne faut pas écrire un décodeur qui devine : la plupart des listes utilisent la pagination Laravel, où les éléments sont dans data.data ; le fil, les notifications et les statuts aplatissent la réponse et nomment leur liste.

lib/models/page.dart
class Paged<T> {
  const Paged({
    required this.items,
    required this.currentPage,
    required this.lastPage,
    required this.total,
  });

  final List<T> items;
  final int currentPage;
  final int lastPage;
  final int total;

  bool get hasMore => currentPage < lastPage;

  /// Pagination Laravel : /events, /jobs, /my/enrollments, /my/certificates…
  static Paged<T> nested<T>(dynamic json, T Function(dynamic) item) {
    final m = (json as Map).cast<String, dynamic>();
    return Paged(
      items: asList(m['data'], item),
      currentPage: asInt(m['current_page'], 1),
      lastPage: asInt(m['last_page'], 1),
      total: asInt(m['total']),
    );
  }

  /// Réponses aplaties : /my/feed ('posts'), /my/notifications
  /// ('notifications'). Les compteurs sont au même niveau que la liste.
  static Paged<T> flat<T>(dynamic json, String key, T Function(dynamic) item) {
    final m = (json as Map).cast<String, dynamic>();
    return Paged(
      items: asList(m[key], item),
      currentPage: asInt(m['current_page'], 1),
      lastPage: asInt(m['last_page'], 1),
      total: asInt(m['total']),
    );
  }

  static const empty = Paged<Never>(
      items: [], currentPage: 1, lastPage: 1, total: 0);
}
lib/repositories/event_repository.dart
Future<ApiResult<Paged<Event>>> events({
  int page = 1,
  String? search,
  String? type,
  bool upcomingOnly = false,
}) =>
    _api.get<Paged<Event>>(
      '/events',
      query: {
        'page': page,
        if (search != null && search.isNotEmpty) 'search': search,
        if (type != null) 'type': type,
        if (upcomingOnly) 'upcoming': 1,
        'per_page': 12,
      },
      parse: (d) => Paged.nested(d, Event.fromJson),
    );

Envoi de fichiers

Le piège le plus coûteux de l'intégration

Le pare-feu applicatif de l'hébergeur rejette tout envoi multipart dont le nom de fichier contient une apostrophe ou des accents. Le 403 est émis par le serveur web avant Laravel : il n'a pas d'en-tête CORS, ne laisse aucune trace dans les logs, et son corps n'est pas du JSON.

Ce n'est pas un cas rare : image_picker sur Android peut renvoyer le nom d'origine, et une capture d'écran francophone s'appelle « capture d'écran.png ». Assainissez à l'unique endroit par lequel passent les envois, c'est-à-dire ApiClient.upload.

lib/core/file_name.dart
/// Rend un nom de fichier acceptable par le pare-feu : pas d'accent, pas
/// d'apostrophe, pas d'espace, une extension propre.
String sanitizeFileName(String name) {
  const accents = 'àáâäãåèéêëìíîïòóôöõùúûüýÿçñ'
      'ÀÁÂÄÃÅÈÉÊËÌÍÎÏÒÓÔÖÕÙÚÛÜÝÇÑ';
  const plain = 'aaaaaaeeeeiiiiooooouuuuyycn'
      'AAAAAAEEEEIIIIOOOOOUUUUYCN';

  String fold(String input) {
    final out = StringBuffer();
    for (final ch in input.split('')) {
      final i = accents.indexOf(ch);
      out.write(i >= 0 ? plain[i] : ch);
    }
    return out.toString();
  }

  // On sépare sur le DERNIER point : « photo.v2.png » garde « png ».
  final dot = name.lastIndexOf('.');
  var base = dot > 0 ? name.substring(0, dot) : name;
  var ext = dot > 0 ? name.substring(dot + 1) : '';

  base = fold(base).replaceAll(RegExp(r'[^A-Za-z0-9._-]+'), '_');
  ext = fold(ext).replaceAll(RegExp(r'[^A-Za-z0-9]+'), '');

  // Sans ça, « ....png » donnerait un nom réduit à des séparateurs.
  base = base.replaceAll(RegExp(r'^[._-]+'), '').replaceAll(RegExp(r'[._-]+$'), '');

  if (base.isEmpty) base = 'fichier';
  if (ext.isEmpty) ext = 'bin';
  if (base.length > 80) base = base.substring(0, 80);

  return '$base.$ext';
}
EntréeSortie
capture d'écran.pngcapture_d_ecran.png
j'y serai.jpgj_y_serai.jpg
CV – Koffi (2026).pdfCV_Koffi_2026.pdf
....pngfichier.png
photo.JPEGphoto.JPEG

La photo de profil

Recadrez côté application : le serveur ne recadre pas, et un fichier d'appareil photo dépasse la limite de 4 Mo sans rien apporter.

lib/features/profile/avatar.dart
Future<ApiResult<String>> pickAndUploadAvatar(ApiClient api) async {
  final picked = await ImagePicker().pickImage(
    source: ImageSource.gallery,
    // Première réduction : on n'envoie pas un cliché de 12 Mpx.
    maxWidth: 1024,
    maxHeight: 1024,
    imageQuality: 85,
  );
  if (picked == null) {
    return const ApiResult(status: 0, success: false, message: 'Annulé.');
  }

  final cropped = await ImageCropper().cropImage(
    sourcePath: picked.path,
    aspectRatio: const CropAspectRatio(ratioX: 1, ratioY: 1),
    compressFormat: ImageCompressFormat.jpg,
    compressQuality: 85,
  );

  return api.upload<String>(
    '/my/profile/avatar',
    field: 'avatar',
    filePath: cropped?.path ?? picked.path,
    // L'URL complète de la nouvelle image ; l'ancienne est supprimée côté
    // serveur. Videz le cache de l'image, sinon l'ancienne reste affichée.
    parse: (d) => (d as Map)['avatar'] as String,
  );
}

Après succès, appelez CachedNetworkImage.evictFromCache(ancienneUrl) : l'URL peut être réutilisée et l'image en cache masquerait le changement.

Accès à un événement

C'est le parcours central, et le seul où un 403 doit être lu comme un état du produit et non comme une erreur. Deux verrous se présentent, dans un ordre qui compte : le paiement d'abord, le formulaire d'inscription ensuite.

lib/models/event_access.dart
class EventAccess {
  const EventAccess({
    required this.granted,
    required this.requiresFullPayment,
    required this.totalPaid,
    required this.registrationFee,
    required this.remaining,
    required this.allowInstallments,
  });

  final bool granted;
  final bool requiresFullPayment;
  final double totalPaid;
  final double registrationFee;
  final double remaining;

  /// Paiement échelonné autorisé : l'écran propose un montant libre.
  final bool allowInstallments;

  factory EventAccess.fromJson(dynamic json) {
    final m = (json as Map).cast<String, dynamic>();
    return EventAccess(
      granted: m['granted'] == true,
      requiresFullPayment: m['requires_full_payment'] == true,
      totalPaid: asDouble(m['total_paid']),
      registrationFee: asDouble(m['registration_fee']),
      remaining: asDouble(m['remaining']),
      allowInstallments: m['allow_installments'] == true,
    );
  }
}

class RegistrationFormGate {
  const RegistrationFormGate({
    required this.required,
    required this.completed,
    this.shareLink,
    this.title,
  });

  final bool required;
  final bool completed;

  /// Le formulaire s'ouvre par son lien de partage, via les routes publiques
  /// /public/forms/{shareLink}.
  final String? shareLink;
  final String? title;

  factory RegistrationFormGate.fromJson(dynamic json) {
    final m = (json as Map).cast<String, dynamic>();
    return RegistrationFormGate(
      required: m['required'] == true,
      completed: m['completed'] == true,
      shareLink: m['share_link'] as String?,
      title: m['title'] as String?,
    );
  }
}
lib/features/events/gate.dart
enum EventGate { payment, registrationForm, open }

/// L'ordre est imposé par l'API : le formulaire n'est vérifié qu'APRÈS le
/// paiement. Afficher le formulaire à quelqu'un qui n'a pas réglé l'enverrait
/// dans une impasse.
EventGate gateFor(MyEvent event) {
  final access = event.access;
  if (access != null && !access.granted) return EventGate.payment;

  final form = event.registrationForm;
  if (form != null && form.required && !form.completed) {
    return EventGate.registrationForm;
  }

  return EventGate.open;
}
lib/features/events/event_space_page.dart
@override
Widget build(BuildContext context) {
  final event = _event;
  if (event == null) return const _Loading();

  return switch (gateFor(event)) {
    // Un seul écran à la fois : on ne montre pas un espace à moitié ouvert.
    EventGate.payment => PaymentRequiredView(
        event: event,
        access: event.access!,
        onPaid: _reload,   // on recharge : le verrou suivant peut apparaître
      ),
    EventGate.registrationForm => RegistrationFormView(
        shareLink: event.registrationForm!.shareLink!,
        title: event.registrationForm!.title,
        onCompleted: _reload,
      ),
    EventGate.open => EventSpaceTabs(event: event),
  };
}
Les sous-ressources renvoient 403, pas une liste vide

/my/events/{uuid}/materials, /courses, /schedule répondent 403 quand l'espace est verrouillé. Présentez alors l'écran de paiement, pas « aucun document ». Le plus simple est de n'appeler ces routes qu'après EventGate.open.

Paiement

Trois étapes, et aucune n'est optionnelle : récupérer les méthodes disponibles, lancer l'opération, attendre la confirmation de l'opérateur.

lib/repositories/payment_repository.dart
class PaymentRepository {
  PaymentRepository(this._api);
  final ApiClient _api;

  /// Étape 1 — méthodes disponibles et frais calculés. Indispensable :
  /// `payment_method_id` est REQUIS à l'étape suivante.
  Future<ApiResult<Map<String, dynamic>>> options(int participantId) =>
      _api.get<Map<String, dynamic>>(
        '/my/enrollments/$participantId/payment',
        parse: (d) => (d as Map).cast<String, dynamic>(),
      );

  /// Étape 2 — lancer le paiement. L'opérateur envoie une demande de
  /// validation sur le téléphone ; rien n'est encore encaissé.
  ///
  /// Répond 201, pas 200. Un test `status == 200` échouerait sur un succès.
  Future<ApiResult<PaymentStarted>> start({
    required int participantId,
    required int paymentMethodId,
    String? phone,     // omis = le numéro du profil
    double? amount,    // montant partiel, si l'échelonnement est autorisé
  }) =>
      _api.post<PaymentStarted>(
        '/my/enrollments/$participantId/pay',
        body: {
          'payment_method_id': paymentMethodId,
          if (phone != null) 'phone': phone,
          if (amount != null) 'amount': amount,
        },
        parse: (d) => PaymentStarted.fromJson(d),
      );
}

class PaymentStarted {
  const PaymentStarted({
    required this.paymentId,
    required this.amount,
    required this.chargeAmount,
    this.redirectUrl,
  });

  final int paymentId;
  final double amount;

  /// Ce qui sera réellement débité : les frais peuvent être à la charge du
  /// payeur. Affichez ce montant, pas `amount`.
  final double chargeAmount;

  /// Certains opérateurs exigent une page web. Non nul = ouvrez-la.
  final String? redirectUrl;

  factory PaymentStarted.fromJson(dynamic json) {
    final m = (json as Map).cast<String, dynamic>();
    return PaymentStarted(
      paymentId: asInt(m['payment_id']),
      amount: asDouble(m['amount']),
      chargeAmount: asDouble(m['charge_amount']),
      redirectUrl: m['redirect_url'] as String?,
    );
  }
}

Attendre la confirmation

GET /my/payments/{id}/status interroge l'opérateur à chaque appel : ce n'est pas une simple lecture en base. Espacez à 4 secondes, abandonnez au bout de deux minutes, et arrêtez le minuteur quand l'écran disparaît.

lib/features/payment/payment_watcher.dart
enum PaymentState { pending, paid, failed, timedOut }

class PaymentWatcher {
  PaymentWatcher(this._api);
  final ApiClient _api;

  Timer? _timer;
  bool _stopped = false;

  static const _every = Duration(seconds: 4);
  static const _giveUpAfter = Duration(minutes: 2);

  /// Émet l'état jusqu'à une issue définitive, puis ferme le flux.
  Stream<PaymentState> watch(int paymentId) {
    final out = StreamController<PaymentState>();
    final startedAt = DateTime.now();

    Future<void> tick() async {
      if (_stopped) return;

      final res = await _api.get<String>(
        '/my/payments/$paymentId/status',
        parse: (d) => (d as Map)['status'] as String? ?? 'en_attente',
      );

      if (_stopped) return;

      switch (res.data) {
        case 'paye':
          out.add(PaymentState.paid);
          await out.close();
          return;
        case 'echoue':
          out.add(PaymentState.failed);
          await out.close();
          return;
      }

      // Une coupure réseau pendant l'attente ne doit pas tout arrêter : le
      // paiement, lui, continue. On réessaiera au prochain tour.
      out.add(PaymentState.pending);

      if (DateTime.now().difference(startedAt) > _giveUpAfter) {
        out.add(PaymentState.timedOut);
        await out.close();
        return;
      }

      _timer = Timer(_every, tick);
    }

    tick();
    out.onCancel = stop;
    return out.stream;
  }

  void stop() {
    _stopped = true;
    _timer?.cancel();
  }
}
« Expiré » ne veut pas dire « échoué »

Sur timedOut, n'annoncez jamais un échec : la personne peut valider sur son téléphone une minute plus tard. Dites que le paiement est en cours de traitement et qu'elle peut revenir sur l'événement, puis rechargez /my/events/{uuid} à la réouverture de l'écran.

Fil social

Le fil classe les abonnements d'abord. Deux règles d'interface : ne jamais recharger la liste entière après une réaction (la position de lecture serait perdue), et charger les commentaires seulement à l'ouverture.

lib/features/feed/feed_controller.dart
class FeedController extends ChangeNotifier {
  FeedController(this._api);
  final ApiClient _api;

  final List<Post> posts = [];
  int _page = 0;
  int _lastPage = 1;
  bool _loading = false;

  bool get hasMore => _page < _lastPage;

  Future<void> loadMore() async {
    if (_loading || !hasMore) return;
    _loading = true;

    final res = await _api.get<Paged<Post>>(
      '/my/feed',
      query: {'page': _page + 1},
      // Réponse APLATIE : la liste s'appelle 'posts', pas 'data'.
      parse: (d) => Paged.flat(d, 'posts', Post.fromJson),
    );

    _loading = false;
    if (!res.ok || res.data == null) return;

    posts.addAll(res.data!.items);
    _page = res.data!.currentPage;
    _lastPage = res.data!.lastPage;
    notifyListeners();
  }

  /// Une seule réaction par personne : envoyer un autre type REMPLACE la
  /// précédente, elle ne s'ajoute pas. Renvoyer la même la retire.
  Future<void> react(Post post, String kind) async {
    final previous = post.myReaction;
    final isUndo = previous == kind;

    // Mise à jour optimiste : le bouton répond immédiatement.
    post.applyReaction(isUndo ? null : kind);
    notifyListeners();

    final res = isUndo
        ? await _api.delete('/posts/${post.id}/reaction')
        : await _api.post(
            '/posts/${post.id}/reaction',
            body: {'kind': kind},  // jaime | bravo | soutien | interessant
          );

    if (!res.ok) {
      post.applyReaction(previous);   // on remet comme avant
      notifyListeners();
    }
  }
}

La réponse de POST /posts/{id}/reaction contient my_reaction, reactions_count et reaction_breakdown à jour : utilisez-les pour recaler la carte si votre estimation optimiste a divergé.

Statuts vidéo

Le serveur ne découpe pas la vidéo

Un statut vidéo porte video_start et video_duration (30 secondes au maximum), mais le fichier servi est complet : l'hébergeur n'a pas ffmpeg et les fonctions d'exécution sont désactivées, le découpage ne peut pas se faire côté serveur. C'est au lecteur de ne jouer que cette fenêtre.

lib/features/feed/status_video.dart
class _StatusVideoState extends State<StatusVideo> {
  VideoPlayerController? _controller;
  late Duration _start;
  late Duration _end;

  @override
  void initState() {
    super.initState();
    _prepare();
  }

  Future<void> _prepare() async {
    final status = widget.status;
    final controller =
        VideoPlayerController.networkUrl(Uri.parse(status.mediaUrl!));
    await controller.initialize();
    if (!mounted) {
      await controller.dispose();
      return;
    }

    _start = Duration(seconds: status.videoStart);
    _end = status.videoDuration != null
        ? _start + Duration(seconds: status.videoDuration!)
        : controller.value.duration;

    // On borne à la durée réelle : un extrait mal renseigné ne doit pas
    // bloquer la visionneuse sur une position inatteignable.
    if (_end > controller.value.duration) _end = controller.value.duration;

    await controller.seekTo(_start);
    controller.addListener(_enforceWindow);
    await controller.play();

    setState(() => _controller = controller);
  }

  void _enforceWindow() {
    final c = _controller;
    if (c == null || !c.value.isInitialized) return;

    final position = c.value.position;

    if (position >= _end) {
      c.pause();
      widget.onFinished();        // on enchaîne sur le statut suivant
    } else if (position < _start - const Duration(milliseconds: 300)) {
      // Un seek involontaire est sorti de la fenêtre : on y revient.
      c.seekTo(_start);
    }
  }

  @override
  void dispose() {
    _controller?.removeListener(_enforceWindow);
    _controller?.dispose();
    super.dispose();
  }
}

Les statuts expirent au bout de 24 heures et le serveur filtre déjà les expirés. seconds_left permet d'afficher un compte à rebours sans recalculer, et /my/statuses renvoie data.groups : un groupe par organisation, statuts triés du plus ancien au plus récent, c'est-à-dire l'ordre de lecture de la visionneuse.

Notifications

Aucune notification poussée

Le serveur n'expose ni Firebase, ni APNs, ni WebSocket : les notifications vivent en base et se lisent par interrogation. N'intégrez pas firebase_messaging en espérant que ça marche — il n'y a rien en face. La pastille ne peut donc s'actualiser qu'à l'ouverture de l'application et à intervalle régulier pendant qu'elle est au premier plan.

lib/features/notifications/poller.dart
class NotificationPoller extends ChangeNotifier with WidgetsBindingObserver {
  NotificationPoller(this._api) {
    WidgetsBinding.instance.addObserver(this);
    _resume();
  }

  final ApiClient _api;
  Timer? _timer;
  int unread = 0;

  // Une minute : la requête est légère (un entier), mais inutile de la faire
  // plus souvent, les événements de la plateforme ne sont pas temps réel.
  static const _interval = Duration(minutes: 1);

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    // Interroger en arrière-plan ne sert à rien et coûte de la batterie.
    state == AppLifecycleState.resumed ? _resume() : _pause();
  }

  void _resume() {
    _refresh();
    _timer ??= Timer.periodic(_interval, (_) => _refresh());
  }

  void _pause() {
    _timer?.cancel();
    _timer = null;
  }

  Future<void> _refresh() async {
    final res = await _api.get<int>(
      '/my/notifications/count',
      parse: (d) => asInt((d as Map)['unread_count']),
    );
    if (res.ok && res.data != null && res.data != unread) {
      unread = res.data!;
      notifyListeners();
    }
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    _pause();
    super.dispose();
  }
}

N'appelez /my/notifications (la liste) qu'à l'ouverture du panneau. Chaque élément porte kind (event_new, event_changed, event_reminder, enrollment, payment, certificate, post) et url, un chemin relatif — faites-le correspondre à vos routes Flutter plutôt que de l'ouvrir dans un navigateur.

lib/features/notifications/open.dart
/// `url` vient du web ('/my/events/UUID', '/events/UUID'…). On le traduit en
/// destination Flutter ; l'inconnu renvoie à l'accueil plutôt qu'au vide.
void openNotification(BuildContext context, AppNotification n) {
  final url = n.url ?? '';

  final myEvent = RegExp(r'^/my/events/([0-9a-f-]+)').firstMatch(url);
  if (myEvent != null) {
    return context.pushEventSpace(myEvent.group(1)!);
  }

  final event = RegExp(r'^/events/([0-9a-f-]+)').firstMatch(url);
  if (event != null) {
    return context.pushEventDetail(event.group(1)!);
  }

  if (url.startsWith('/my/certificates')) return context.pushCertificates();
  if (url.startsWith('/home') || url.startsWith('/feed')) return context.pushFeed();

  context.pushHome();
}

Le marquage comme lu (POST /my/notifications/{id}/read, /read-all) doit être optimiste : décrémentez la pastille tout de suite, l'appel peut échouer sans gêner personne. Attention au typage, id est une chaîne UUID.

iOS & Android

Permissions

ios/Runner/Info.plist
<key>NSPhotoLibraryUsageDescription</key>
<string>Pour choisir votre photo de profil et illustrer vos publications.</string>
<key>NSCameraUsageDescription</key>
<string>Pour prendre une photo de profil.</string>

Côté Android, INTERNET est accordée par défaut et image_picker n'exige plus de permission de stockage sur les versions récentes. L'API étant servie en HTTPS, aucune exception de sécurité réseau n'est nécessaire — sauf pour viser un serveur local en HTTP pendant le développement, qui demande un network_security_config.xml.

Ce que l'API ne fournit pas

Checklist avant publication

Pour tester les endpoints

La console interactive /api/v1/docs/explorer permet d'appeler l'API avec un jeton, champ par champ : utile pour vérifier la forme exacte d'une réponse avant d'écrire le modèle Dart. La liste complète des endpoints est dans la référence mobile.