API EventCollab pour le mobile
Référence des endpoints exposés à une application mobile : à quoi sert chacun, dans quel cas l'appeler, et comment. Les routes réservées à l'espace organisateur et à la plateforme sont volontairement exclues. Pour le code d'intégration — client HTTP, stockage du jeton, modèles — voir le guide Flutter.
Conventions
Base : https://collab-api.eventcollab.io/api/v1
Toutes les réponses partagent la même enveloppe. Lisez systématiquement
data ; ne vous fiez jamais au seul code HTTP pour savoir si une
opération métier a abouti.
{ "success": true, "message": "Connexion réussie.", "data": { … } }
En erreur, data est absent et errors peut apparaître :
{
"success": false,
"message": "Données invalides.",
"errors": { "email": ["Cet email est déjà utilisé."] }
}
Accept: application/json
Sans cet en-tête, Laravel tente une redirection HTML sur les routes protégées et renvoie une erreur 500 au lieu d'un 401 exploitable. C'est la première cause de bugs d'intégration sur ce projet.
En-têtes
| En-tête | Quand | Valeur |
|---|---|---|
Accept | Toujours | application/json |
Authorization | Routes protégées | Bearer <token> |
Content-Type | Envoi JSON | application/json |
Pour un envoi de fichier, utilisez multipart/form-data et
laissez la librairie HTTP poser elle-même le Content-Type avec
sa boundary.
Pagination
Les listes paginées suivent le format Laravel : data.data porte
les éléments, et data.current_page, data.last_page,
data.total la navigation. Le paramètre per_page est
accepté. Trois listes récentes aplatissent ce format et exposent directement
data.posts, data.notifications ou
data.groups — c'est signalé sur chacune.
Sessions & jetons
L'authentification utilise Laravel Sanctum. Le jeton renvoyé à la connexion n'expire jamais : stockez-le dans le trousseau sécurisé du système (Keychain sur iOS, Keystore sur Android) et réutilisez-le tant que l'utilisateur ne se déconnecte pas.
Chaque connexion appelle issueToken(), qui commence par
$user->tokens()->delete() : tous les jetons
existants sont révoqués. Se connecter sur mobile déconnecte donc
la session web, et inversement.
Concrètement : attendez-vous à des 401 inexpliqués si la même
personne utilise l'application et le site. Prévoyez une reconnexion
silencieuse ou un message explicite. Ce comportement est à confirmer avec
l'équipe backend : il entre en conflit avec la session persistante
attendue côté web.
Que faire sur un 401
Effacez le jeton stocké et renvoyez vers l'écran de connexion, en mémorisant
la destination pour y revenir. N'effacez rien sur un 403 : la
session est valide, c'est l'accès à la ressource qui est refusé.
POST /auth/login répond 401 avec « Identifiants
incorrects. » quand le mot de passe est faux, et 403 quand le
compte est désactivé. Un intercepteur qui vide la session sur tout
401 provoquerait une boucle sur l'écran de connexion. Le
critère fiable : un jeton avait-il été envoyé ?
Erreurs
| Code | Signification | Réaction attendue |
|---|---|---|
401 | Jeton absent, invalide ou révoqué — ou identifiants incorrects sur /auth/login | N'effacer le jeton que si un jeton avait été envoyé ; sinon afficher le message |
403 | Accès refusé — voir le corps | Afficher le message ; lire access_locked et registration_form |
404 | Introuvable, ou masqué volontairement | Message neutre, pas « supprimé » |
422 | Validation | Afficher errors champ par champ |
Le pare-feu de l'hébergeur bloque les envois multipart dont le nom de fichier contient une apostrophe ou des accents. La réponse 403 est émise avant l'application, donc rien n'apparaît dans les logs. Assainissez tout nom de fichier avant l'envoi : retirez accents et apostrophes, remplacez par des tirets bas.
Parcours : de la découverte à l'accès
C'est le parcours central de l'application. Trois verrous peuvent se présenter, dans cet ordre, et chacun a sa propre réponse d'API.
GET /events → le participant parcourt le catalogue
GET /events/{uuid} → il consulte un événement
POST /events/{uuid}/register → il s'inscrit (statut « en_attente » ou « valide »)
├─ Événement payant ?
│ POST /my/enrollments/{participant}/pay → il règle
│ GET /my/payments/{payment}/status → l'app attend la confirmation
│
├─ Formulaire d'inscription exigé ?
│ GET /public/forms/{shareLink} → l'app affiche le formulaire
│ POST /public/forms/{shareLink}/respond → il le remplit
│
└─ GET /my/events/{uuid} → son espace s'ouvre
GET /my/events/{uuid} est l'écran pivot : sa réponse dit à
l'application lequel des verrous s'applique.
{
"access": {
"granted": false, // espace verrouillé
"requires_full_payment": true,
"total_paid": 2000, "registration_fee": 5000, "remaining": 3000
},
"registration_form": {
"required": true, "completed": false,
"form_id": 6, "share_link": "eUv1EPrV…"
}
}
Ordre d'affichage recommandé : si
access.granted est faux, montrez l'écran de paiement et rien
d'autre. Une fois l'accès accordé, si registration_form.required
est vrai et completed faux, montrez le formulaire. Ensuite
seulement, l'espace complet.
Authentification
Objectif — créer un compte participant et ouvrir une session immédiatement.
- Quand l'utiliser
- Écran d'inscription de l'application. Renvoie directement un jeton : pas besoin d'enchaîner un login.
- Comment
name(nom de famille),first_name,email,password+password_confirmation(8 caractères minimum),phonefacultatif mais unique.- Après
- Le compte n'est pas vérifié. Enchaînez sur l'écran de saisie du code reçu par email, puis
/auth/verify.
Objectif — ouvrir une session.
- Comment
- Le champ s'appelle
login, pasemail: il accepte l'email ou le téléphone. Pluspassword. - Deux réponses possibles
-
Session ouverte :
data.tokenetdata.user.
Double authentification active :data.two_factor_required = true,data.method(app,emailousms) etdata.sent_tomasqué. Aucun jeton n'est délivré — basculez sur l'écran de code.
Objectif — terminer une connexion interrompue par la double authentification.
- Comment
- Renvoyez
login,passwordetcode. Ajoutezcompany: truepour une connexion organisateur. - Voisin
POST /auth/two-factor-resendrenvoie le code par email ou SMS.
Objectif — confirmer l'adresse email avec le code à 6 chiffres.
- Quand l'utiliser
- Juste après l'inscription. Le jeton existe déjà : l'appel est authentifié.
- Comment
{ "code": "123456" }.POST /auth/resend-codeen renvoie un.
Objectif — envoyer un code de réinitialisation à 6 chiffres, valable 15 minutes.
- Attention
- La réponse est toujours un succès, même si l'email est inconnu : c'est voulu, pour ne pas révéler l'existence d'un compte. N'affichez jamais « compte introuvable ».
- Latence
- L'envoi est synchrone, comptez 3 à 7 secondes. Prévoyez un indicateur d'attente et un délai d'expiration généreux.
Objectif — définir un nouveau mot de passe à partir du code reçu.
- Comment
email,code,password,password_confirmation.- Conséquence
- Toutes les sessions sont révoquées, y compris celle en cours. L'utilisateur doit se reconnecter.
Objectif — récupérer le compte connecté, ses rôles et ses affiliations.
- Quand l'utiliser
- Au démarrage, pour valider le jeton stocké et réhydrater l'état. Un 401 ici signifie que la session est morte.
Objectif — révoquer le jeton courant.
- Comment
- Effacez le jeton local même si l'appel échoue : la déconnexion ne doit jamais dépendre du réseau.
Les variantes organisateur existent sous /auth/company/*
(register, login, forgot-password,
reset-password). Ne les utilisez que si l'application mobile
ouvre un espace organisateur.
Profil & sécurité
Objectif — lire le profil complet : identité, téléphone, biographie, spécialités, diplôme, avatar.
Objectif — modifier le profil, champ par champ.
- Comment
- Mise à jour partielle : n'envoyez que ce qui change.
nameporte le nom de famille,first_namele prénom.specialtiesest un tableau de chaînes. - Piège
- Le téléphone est unique : un doublon renvoie un 422 sur
phone.
Objectif — définir la photo de profil, affichée dans le fil, les commentaires et les attestations.
- Comment
multipart/form-data, champavatar. JPG, PNG ou WebP, 4 Mo maximum.- Recommandé
- Recadrez en carré côté application avant l'envoi : le serveur ne recadre pas, et un fichier d'appareil photo pèse inutilement lourd.
- Réponse
data.avatarcontient l'URL complète. L'ancienne image est supprimée côté serveur.
Objectif — retirer la photo. L'interface doit retomber sur les initiales.
Objectif — changer le mot de passe.
- Comment
current_password,password,password_confirmation, etlogout_other_devices(booléen, vrai par défaut).- Comportement
- Les autres sessions sont fermées, jamais celle qui fait la demande.
data.revoked_sessionsindique combien.
Objectif — fermer toutes les autres sessions sans changer de mot de passe.
- Quand l'utiliser
- Écran « sécurité », en cas de doute sur un appareil perdu.
Double authentification
Objectif — activer la 2FA. Renvoie le secret et l'URI à encoder en QR pour une application d'authentification.
Puis POST /my/two-factor/confirm avec le code pour valider, POST /my/two-factor/resend pour les méthodes email et SMS, DELETE /my/two-factor pour désactiver.
- État du SMS
- Le fournisseur SMS n'est pas branché : la méthode
smsécrit dans les logs au lieu d'envoyer. Ne la proposez pas encore dans l'application.
Catalogue d'événements
Objectif — lister les événements publiés, pour l'écran de découverte.
- Filtres
search(titre, description, lieu),type(presentiel,distanciel,hybride),upcoming=1,per_page.- À savoir
- Pagination Laravel classique. Les brouillons n'apparaissent jamais. Chaque élément porte
cover_image,organizationetparticipants_count.
Objectif — fiche détaillée d'un événement, avec l'état de ma propre inscription.
- Ce que renvoie la réponse
data.event,data.enrollment(null si non inscrit),data.speakers(intervenants publiés) etdata.badges(badges « J'y serai » publiés).- Verrou important
- Pour un webinaire,
webinar_urletlocationsont null tant que l'inscription n'est pas réglée. Ne construisez aucun bouton « Rejoindre » sur une valeur absente. - Identifiant
- Les événements se référencent par leur
uuid, jamais par leur identifiant numérique.
Objectif — inscrire le compte connecté à l'événement.
- Après
data.statusvautvalide, ouen_attentesi l'organisateur valide manuellement. Rechargez ensuite/my/events/{uuid}pour connaître les verrous restants.
Objectif — mettre un événement de côté. DELETE sur la même route pour retirer.
- Voisins
GET /my/favoritespour la liste complète,GET /my/favorites/idspour un tableau d'identifiants — idéal pour colorer les cœurs d'une liste sans charger les objets.
Mon espace événement
Objectif — lister mes inscriptions avec leur situation de paiement.
- Quand l'utiliser
- Écran « Mes événements ». Chaque élément porte
payment_summary:registration_fee,total_paid,remaining,is_fully_paid.
Objectif — l'écran d'accueil d'un événement auquel je suis rattaché. C'est le point d'entrée de tout le reste.
- Ce qu'il faut en lire
-
roles—participant,trainer,supervisor: le menu de l'application en dépend.
access— le verrou de paiement.
registration_form— le verrou de formulaire.
speakers— intervenants publiés.
partners— partenaires de l'événement. - Rôles contextuels
- Le rôle vaut pour cet événement. La même personne peut être participante ici et formatrice ailleurs : ne mettez jamais un rôle en cache globalement.
Objectif — les documents mis à disposition par l'organisateur.
- Filtrage automatique
- Seuls les documents visibles, et ceux destinés à ma classe ou à tout le monde. Un document d'une autre classe n'apparaît jamais.
- 403 attendu
- Si l'espace est verrouillé. Traitez ce 403 comme « paiement en attente », pas comme une erreur.
Objectif — mon emploi du temps pour cet événement.
Variante globale : GET /schedule/me, tous événements confondus — pratique pour un écran « agenda » unique.
Objectif — indiquer si je participerai à une séance.
Objectif — les cours publiés qui me concernent.
Détail d'un cours : GET /my/courses/{course} (supports, exercices). Discussion : GET et POST /courses/{course}/comments.
Objectif — les évaluations à passer.
- Déroulé
POST /evaluations/{id}/startouvre une tentative, puisPOST /evaluations/{id}/attempts/{attempt}/submitl'envoie. Respectezduration_minutescôté application.
Objectif — les badges « J'y serai » publiés, à personnaliser avec sa photo.
- Comment composer
- Récupérez le gabarit via
GET /public/badges/{badge}/template(flux image servi avec CORS), composez sur un canvas, puis signalez l'usage avecPOST /my/events/{uuid}/badges/{badge}/use.
Objectif — les formulaires rattachés à l'événement.
Autres : /accommodation (mon logement), /supervision (espace superviseur).
Objectif — mes attestations délivrées, avec le chemin du PDF.
- Vérification publique
GET /public/certificates/{number}/verifyest ouvert à tous : c'est la cible du QR code imprimé sur l'attestation.
Paiements
Objectif — lancer un paiement mobile money pour une inscription.
- Comment
payment_method_idest obligatoire : récupérez-le d'abord viaGET /my/enrollments/{participant}/payment, qui liste les méthodes disponibles et les frais calculés.phoneest facultatif (par défaut celui du profil),amountaussi (montant partiel, si l'échelonnement est autorisé).- Réponse
- 201, pas 200. Contient
payment_id,charge_amount(ce qui sera réellement débité, frais inclus) etredirect_urlquand l'opérateur exige une page web. - Ensuite
- Le paiement est asynchrone : la réponse ne signifie pas qu'il a abouti. L'opérateur envoie une demande de validation sur le téléphone du payeur. Interrogez
GET /my/payments/{payment}/statusjusqu'àpayeouechoue. - Rythme d'interrogation
- Toutes les 3 à 5 secondes, avec un abandon au bout de 2 minutes et un message invitant à vérifier plus tard. N'interrogez jamais en boucle serrée.
Objectif — l'historique des paiements du compte.
Objectif — payer sans compte, via un lien partagé par l'organisateur.
- Quand l'utiliser
- Si l'application ouvre un lien de paiement reçu par message.
POSTsur la même route lance l'opération,GET /public/pay/{token}/status/{tempRef}suit son issue.
POST /payments/webhook/{gateway} et
/withdrawals/webhook/{gateway} sont appelés par l'opérateur de
paiement, jamais par l'application. Ne les implémentez pas.
Fil social
Objectif — le mur de publications des organisations suivies et de celles où je suis inscrit.
- Format
- Aplati :
data.posts,data.current_page,data.last_page,data.total. Paramètrepage. - Classement
- Abonnements d'abord, découverte ensuite, chronologique dans chaque groupe. Chaque publication porte
subscribedpour appliquer la même règle à vos propres cartes. - Contenu
media[](images et vidéos, avecurlcomplète),programsi un événement est mis en avant,my_reaction,reaction_breakdown,reactions_count,comments_count.
Objectif — réagir à une publication.
- Comment
{ "kind": "jaime" }— valeurs :jaime,bravo,soutien,interessant.- Comportement
- Une seule réaction par personne : renvoyer un autre type remplace la précédente, elle ne s'ajoute pas.
DELETEsur la même route retire la réaction. - Interface
- La réponse renvoie les compteurs à jour : mettez à jour la carte localement plutôt que de recharger le fil, sinon la position de lecture est perdue.
Objectif — lire les commentaires d'une publication. Chargez-les à l'ouverture du fil de commentaires, pas avec la liste.
POST sur la même route pour commenter (body, 2000 caractères). DELETE /post-comments/{comment} pour supprimer le sien. Chaque commentaire porte mine.
Statuts éphémères
Objectif — la bande de statuts, façon « stories » : des annonces qui disparaissent au bout de 24 heures.
- Format
data.groups: un groupe par organisation, avecorganizationetstatuses[]triés du plus ancien au plus récent — l'ordre de lecture d'une visionneuse.- Types
texte(avecbackground),image,video.- Vidéo : à lire attentivement
-
video_startetvideo_durationdéfinissent un extrait de 30 secondes maximum. Le fichier complet est servi, mais vous ne devez lire que cette fenêtre : placez la lecture àvideo_startet arrêtez-la àvideo_start + video_duration. Le découpage n'a pas lieu côté serveur. - Expiration
- Filtrée côté serveur.
seconds_leftpermet d'afficher un compte à rebours sans recalculer.
Notifications
Objectif — le nombre de non-lues, pour la pastille.
- Quand l'utiliser
- Requête légère, à appeler périodiquement (une fois par minute suffit) ou au retour au premier plan. N'utilisez pas la liste complète pour cela.
Objectif — la liste, à charger seulement à l'ouverture du panneau.
- Format
- Aplati :
data.notificationsetdata.unread_count.unread=1ne renvoie que les non-lues. - Types (
kind) event_new,event_changed,event_reminder,enrollment,payment,certificate,post. Chacune portetitle,body,url(chemin relatif à ouvrir),actoretactor_logo.- Marquage
POST /my/notifications/{id}/readetPOST /my/notifications/read-all. Marquez localement d'abord, l'appel peut échouer sans gêner l'utilisateur.- Pas de notification poussée
- Aucun service de push n'est branché. Une pastille ne s'actualise qu'à l'ouverture de l'application.
Abonnements
Objectif — suivre un organisateur. DELETE pour se désabonner.
- Effet
- Détermine le contenu du fil, de la bande de statuts et les notifications de nouvel événement. C'est le levier central de la personnalisation.
- Équivalents
/users/{id}/followpour suivre une personne.GET /my/followingliste mes abonnements,GET /organizations/{id}/pagela page publique d'un organisateur et/page/eventsses événements.
Offres d'emploi
Objectif — le tableau des offres publiées. GET /jobs/{id} pour le détail.
Objectif — postuler.
- Comment
multipart/form-dataavec le CV. Assainissez le nom du fichier — voir l'avertissement sur le pare-feu.- Suivi
GET /my/applications, puisGETetPOST /job-applications/{id}/messagespour la discussion avec le recruteur.
Quiz en direct
Objectif — rejoindre une session de quiz avec son code.
- Déroulé
- Rejoindre, puis
POST /kahoot/sessions/{id}/answerà chaque question, etGET /kahoot/sessions/{id}/resultspour le classement. - Limite connue
- Le temps réel repose sur Reverb, désactivé en production (hébergement mutualisé, pas de processus permanent). L'application doit donc interroger périodiquement au lieu d'attendre un événement poussé, et la synchronisation sera imparfaite.
Accès public
Ces routes ne demandent aucun jeton. Utiles pour le partage et les liens profonds.
Objectif — afficher un formulaire à partir de son lien de partage — dont le formulaire d'inscription d'un événement.
POST /public/forms/{shareLink}/respond envoie les réponses. C'est ce couple qui lève le verrou de formulaire décrit plus haut.
Objectif — ouvrir un badge partageable sans compte, quand l'organisateur a autorisé les invités.
Objectif — vérifier l'authenticité d'une attestation. Cible du QR code imprimé.
Données de référence
GET /countries et GET /cities alimentent les
sélecteurs de pays et de villes. Mettez-les en cache localement : le contenu
ne bouge pratiquement jamais et la liste des villes est volumineuse.
GET /announcements/active renvoie les annonces mises en avant et
validées, destinées à une bande promotionnelle en haut du fil.
Pièges connus
Chaque connexion révoque toutes les autres. Une personne connectée sur le site sera déconnectée en ouvrant l'application. À arbitrer avec l'équipe backend avant la mise en production de l'application.
Le pare-feu de l'hébergeur rejette l'envoi en 403, sans en-tête CORS et sans trace dans les logs. Assainissez systématiquement le nom avant tout envoi multipart — photo de profil, CV, document.
Aucune file d'attente n'est en place : les appels qui déclenchent un email (mot de passe oublié, code de vérification) prennent 3 à 7 secondes. Prévoyez des délais d'expiration généreux et un indicateur d'attente.
La plupart des listes suivent la pagination Laravel
(data.data). Le fil, les notifications et les statuts
aplatissent la réponse (data.posts,
data.notifications, data.groups). Écrivez deux
adaptateurs plutôt qu'un seul qui devine.
Sur l'espace événement, il signifie « paiement en attente » ou « formulaire à remplir », et le corps porte de quoi construire l'écran adéquat. Le traiter comme une erreur générique donnerait une impasse à l'utilisateur.