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.
- 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: truene veut pas dire « connecté ». Une connexion avec double authentification répond 200 avecsuccess: trueetdata.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
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/
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.
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);
}
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.
/// 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.',
};
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.
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));
}
}
}
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
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.
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.
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();
}
}
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.
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.
| Champ | Ce qu'on attend | Ce 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. |
/// 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 [];
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.
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);
}
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 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.
/// 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ée | Sortie |
|---|---|
capture d'écran.png | capture_d_ecran.png |
j'y serai.jpg | j_y_serai.jpg |
CV – Koffi (2026).pdf | CV_Koffi_2026.pdf |
....png | fichier.png |
photo.JPEG | photo.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.
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.
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?,
);
}
}
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;
}
@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),
};
}
/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.
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.
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();
}
}
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.
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
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.
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
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.
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.
/// `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
<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
- Notifications poussées — aucun service branché.
- Temps réel — Reverb est désactivé en production (hébergement mutualisé, pas de processus permanent). Le quiz en direct doit donc interroger périodiquement, et la synchronisation reste approximative.
- SMS — la double authentification par SMS écrit dans les logs au lieu d'envoyer. Ne proposez que « application » et « email ».
- Rafraîchissement de jeton — pas de refresh token : le jeton vit jusqu'à révocation.
Checklist avant publication
Accept: application/jsonsur toutes les requêtes, posé dansBaseOptions.- Le jeton est dans
flutter_secure_storage, pas dansSharedPreferences. - Un
401ne vide la session que si un jeton avait été envoyé. - Un
403sur l'espace d'un événement ouvre l'écran de paiement ou de formulaire, jamais un message d'erreur. - Tous les envois de fichier passent par
ApiClient.upload, donc parsanitizeFileName. - Le test de succès du paiement accepte
201. payment_method_idest récupéré avant de lancer un paiement.- Les montants sont lus avec
asDouble, pasas double. - L'identifiant d'une notification est typé
String. - Le
receiveTimeoutdépasse 30 secondes pour les routes qui envoient un email. - Les minuteurs de paiement et de notifications sont arrêtés dans
disposeet en arrière-plan. - La fenêtre
video_start/video_durationest respectée par le lecteur. - L'expiration de session a un parcours de reconnexion, destination mémorisée.
- « Mot de passe oublié » ne révèle pas si le compte existe.
- Les listes gèrent la forme imbriquée et la forme aplatie.
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.