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é."] }
}
Toujours envoyer 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êteQuandValeur
AcceptToujoursapplication/json
AuthorizationRoutes protégéesBearer <token>
Content-TypeEnvoi JSONapplication/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.

Une seule session active par compte, tous appareils confondus

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é.

Tous les 401 ne sont pas des expirations

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

CodeSignificationRéaction attendue
401Jeton absent, invalide ou révoqué — ou identifiants incorrects sur /auth/loginN'effacer le jeton que si un jeton avait été envoyé ; sinon afficher le message
403Accès refusé — voir le corpsAfficher le message ; lire access_locked et registration_form
404Introuvable, ou masqué volontairementMessage neutre, pas « supprimé »
422ValidationAfficher errors champ par champ
Un 403 peut arriver sans en-tête CORS

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

POST/auth/registerpublic

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), phone facultatif 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.
POST/auth/loginpublic

Objectif — ouvrir une session.

Comment
Le champ s'appelle login, pas email : il accepte l'email ou le téléphone. Plus password.
Deux réponses possibles
Session ouverte : data.token et data.user.
Double authentification active : data.two_factor_required = true, data.method (app, email ou sms) et data.sent_to masqué. Aucun jeton n'est délivré — basculez sur l'écran de code.
POST/auth/two-factor-challengepublic

Objectif — terminer une connexion interrompue par la double authentification.

Comment
Renvoyez login, password et code. Ajoutez company: true pour une connexion organisateur.
Voisin
POST /auth/two-factor-resend renvoie le code par email ou SMS.
POST/auth/verifyjeton

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-code en renvoie un.
POST/auth/forgot-passwordpublic

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.
POST/auth/reset-passwordpublic

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.
GET/auth/mejeton

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.
POST/auth/logoutjeton

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é

GET/my/profilejeton

Objectif — lire le profil complet : identité, téléphone, biographie, spécialités, diplôme, avatar.

PUT/my/profilejeton

Objectif — modifier le profil, champ par champ.

Comment
Mise à jour partielle : n'envoyez que ce qui change. name porte le nom de famille, first_name le prénom. specialties est un tableau de chaînes.
Piège
Le téléphone est unique : un doublon renvoie un 422 sur phone.
POST/my/profile/avatarjeton

Objectif — définir la photo de profil, affichée dans le fil, les commentaires et les attestations.

Comment
multipart/form-data, champ avatar. 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.avatar contient l'URL complète. L'ancienne image est supprimée côté serveur.
DELETE/my/profile/avatarjeton

Objectif — retirer la photo. L'interface doit retomber sur les initiales.

PUT/my/passwordjeton

Objectif — changer le mot de passe.

Comment
current_password, password, password_confirmation, et logout_other_devices (booléen, vrai par défaut).
Comportement
Les autres sessions sont fermées, jamais celle qui fait la demande. data.revoked_sessions indique combien.
POST/my/security/logout-othersjeton

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

POST/my/two-factor/setupjeton

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

GET/eventsjeton

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, organization et participants_count.
GET/events/{uuid}jeton

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) et data.badges (badges « J'y serai » publiés).
Verrou important
Pour un webinaire, webinar_url et location sont 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.
POST/events/{uuid}/registerjeton

Objectif — inscrire le compte connecté à l'événement.

Après
data.status vaut valide, ou en_attente si l'organisateur valide manuellement. Rechargez ensuite /my/events/{uuid} pour connaître les verrous restants.
POST/events/{uuid}/favoritejeton

Objectif — mettre un événement de côté. DELETE sur la même route pour retirer.

Voisins
GET /my/favorites pour la liste complète, GET /my/favorites/ids pour un tableau d'identifiants — idéal pour colorer les cœurs d'une liste sans charger les objets.

Mon espace événement

GET/my/enrollmentsjeton

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.
GET/my/events/{uuid}jeton

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.
GET/my/events/{uuid}/materialsjeton

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.
GET/my/events/{uuid}/schedulejeton

Objectif — mon emploi du temps pour cet événement.

Variante globale : GET /schedule/me, tous événements confondus — pratique pour un écran « agenda » unique.

POST/my/events/{uuid}/sessions/{session}/rsvpjeton

Objectif — indiquer si je participerai à une séance.

GET/my/events/{uuid}/coursesjeton

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.

GET/my/events/{uuid}/evaluationsjeton

Objectif — les évaluations à passer.

Déroulé
POST /evaluations/{id}/start ouvre une tentative, puis POST /evaluations/{id}/attempts/{attempt}/submit l'envoie. Respectez duration_minutes côté application.
GET/my/events/{uuid}/badgesjeton

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 avec POST /my/events/{uuid}/badges/{badge}/use.
GET/my/events/{uuid}/formsjeton

Objectif — les formulaires rattachés à l'événement.

Autres : /accommodation (mon logement), /supervision (espace superviseur).

GET/my/certificatesjeton

Objectif — mes attestations délivrées, avec le chemin du PDF.

Vérification publique
GET /public/certificates/{number}/verify est ouvert à tous : c'est la cible du QR code imprimé sur l'attestation.

Paiements

POST/my/enrollments/{participant}/payjeton

Objectif — lancer un paiement mobile money pour une inscription.

Comment
payment_method_id est obligatoire : récupérez-le d'abord via GET /my/enrollments/{participant}/payment, qui liste les méthodes disponibles et les frais calculés. phone est facultatif (par défaut celui du profil), amount aussi (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) et redirect_url quand 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}/status jusqu'à paye ou echoue.
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.
GET/my/paymentsjeton

Objectif — l'historique des paiements du compte.

GET/public/pay/{token}public

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. POST sur la même route lance l'opération, GET /public/pay/{token}/status/{tempRef} suit son issue.
Les webhooks ne vous concernent pas

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

GET/my/feedjeton

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ètre page.
Classement
Abonnements d'abord, découverte ensuite, chronologique dans chaque groupe. Chaque publication porte subscribed pour appliquer la même règle à vos propres cartes.
Contenu
media[] (images et vidéos, avec url complète), program si un événement est mis en avant, my_reaction, reaction_breakdown, reactions_count, comments_count.
POST/posts/{post}/reactionjeton

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. DELETE sur 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.
GET/posts/{post}/commentsjeton

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

GET/my/statusesjeton

Objectif — la bande de statuts, façon « stories » : des annonces qui disparaissent au bout de 24 heures.

Format
data.groups : un groupe par organisation, avec organization et statuses[] triés du plus ancien au plus récent — l'ordre de lecture d'une visionneuse.
Types
texte (avec background), image, video.
Vidéo : à lire attentivement
video_start et video_duration dé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_start et arrêtez-la à video_start + video_duration. Le découpage n'a pas lieu côté serveur.
Expiration
Filtrée côté serveur. seconds_left permet d'afficher un compte à rebours sans recalculer.

Notifications

GET/my/notifications/countjeton

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.
GET/my/notificationsjeton

Objectif — la liste, à charger seulement à l'ouverture du panneau.

Format
Aplati : data.notifications et data.unread_count. unread=1 ne renvoie que les non-lues.
Types (kind)
event_new, event_changed, event_reminder, enrollment, payment, certificate, post. Chacune porte title, body, url (chemin relatif à ouvrir), actor et actor_logo.
Marquage
POST /my/notifications/{id}/read et POST /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

POST/organizations/{id}/followjeton

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}/follow pour suivre une personne. GET /my/following liste mes abonnements, GET /organizations/{id}/page la page publique d'un organisateur et /page/events ses événements.

Offres d'emploi

GET/jobsjeton

Objectif — le tableau des offres publiées. GET /jobs/{id} pour le détail.

POST/jobs/{id}/applyjeton

Objectif — postuler.

Comment
multipart/form-data avec le CV. Assainissez le nom du fichier — voir l'avertissement sur le pare-feu.
Suivi
GET /my/applications, puis GET et POST /job-applications/{id}/messages pour la discussion avec le recruteur.

Quiz en direct

POST/kahoot/sessions/joinjeton

Objectif — rejoindre une session de quiz avec son code.

Déroulé
Rejoindre, puis POST /kahoot/sessions/{id}/answer à chaque question, et GET /kahoot/sessions/{id}/results pour 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.

GET/public/forms/{shareLink}public

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.

GET/public/badges/link/{orgSlug}/{badgeSlug}public

Objectif — ouvrir un badge partageable sans compte, quand l'organisateur a autorisé les invités.

GET/public/certificates/{number}/verifypublic

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

Une seule session par compte

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.

Noms de fichiers : accents et apostrophes interdits

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.

Les emails sont envoyés de façon synchrone

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.

Deux formats de liste cohabitent

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.

Un 403 n'est pas toujours une erreur

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.