API

API

Statut : 🟡 Brouillon · Màj : 2026-10-14 · Tickets : #164 #306 #378 #383 #393

Contrat du MVP. Préfixe /v1. Authentification par jeton Firebase quand indiqué. Les schémas Zod dans packages/shared font foi ; cette page en est le résumé lisible.

Conventions

• Pagination par curseur : ?cursor=&limit= (max 50), réponse { items, nextCursor }.
• Listes dans la query : clé répétée, avec ou sans crochets (moods[]=food&moods[]=culture ou moods=food&moods=culture) ; les deux notations se mélangent et les doublons sont retirés. Toute autre notation (moods[0]=) est une clé inconnue. Les queries sont strictes : une clé inconnue (mood=, moods[0]=) ou une valeur hors taxonomie (budgets[]=premium) répond 400 validation_error, avec details.issues ; jamais un résultat non filtré (#25, D-066). Règle du code HTTP de validation_error (D-071, #221) : 400 pour une query invalide (GET), 422 pour un corps invalide (POST, PATCH, PUT).
• Erreurs : { code, message, details? }, codes HTTP standards. Codes métier stables : validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, coherence_blocked, link_expired (en 410 : lien de confirmation expiré, déjà utilisé ou annulé, D-062), premium_required (en 402, avec details.reason pour alimenter E-17 : premium_route ou create_limit, et details.limit pour la création ; D-023) ; brouillon #393, à valider : route_removed (en 410 : parcours retiré, avec details.removedAt et details.near, voir Fiche parcours).

🟡 Brouillon #383 du 2026-10-14, à valider par Ilan, voir Compte-et-Monetisation › Fin de la limite de création : proposé, premium_required ne garde que premium_route (create_limit et details.limit de la création retirés) ; rate_limited porte details.reason (pending_routes) et details.limit pour la limite de relecture (D-073).

• Dates ISO 8601 UTC ; coordonnées { lat, lng }.
• Toutes les lectures publiques sont cachables (Cache-Control court, ETag), pour l'appelant anonyme.
• Authentification facultative (D-075) : une route publique dont la réponse dépend du droit de l'appelant (aujourd'hui /routes/search) accepte un jeton Firebase sans l'exiger. Sans en-tête Authorization, réponse anonyme, Cache-Control: public. Avec un en-tête Authorization, réponse Cache-Control: private et Vary: Authorization, jamais servie à un autre appelant. Un jeton présent mais invalide ou expiré répond 401 unauthorized, comme sur une route authentifiée : l'API ne retombe pas en silence sur la réponse anonyme, pour que l'app rafraîchisse son jeton et réessaie.

Découverte (public)

Méthode	Route	Description
GET	/routes/search	Parcours dans une zone avec filtres. Query : bbox=w,s,e,n, audiences[], moods[], conditions[], durations[], budgets[], transports[] (valeurs de la taxonomie), `sort=recommended
GET	/users/:id/profile	Profil public (D-023) : avatar, prénom, membre depuis, quartier, bio, certified et certification (critères avec valeur, seuil et état, pour la sheet d'explication), chiffres routesPublished, routesCompleted, ratingAvg (chacun null s'il n'existe pas), verifiedPlaces (lieux distincts confirmés sur place ou après la sortie, null à zéro, D-056), anecdotes dans l'ordre (questionKey, libellé, réponse), parcours à la une dans l'ordre (cards), parcours publiés (cards ; query `sort=recent
GET	/routes/:id/ratings	Avis visibles, paginés
GET	/routes/search/count	Même query, réponse { count } pour le compteur des filtres. breakdown=all_but_one ajoute without : le nombre de parcours obtenu en retirant chaque filtre actif pris isolément, groupe par groupe et jamais valeur par valeur, pour les suggestions du zéro résultat de E-03 (D-010)
GET	/routes/:id	Fiche complète (étapes, lieux, horaires du jour, computed, vérification, lieux signalés ; pour l'utilisateur connecté, myReport : date et statut de son signalement en cours, D-057). ?token= pour un parcours privé. Trajets à pied, à vélo et en voiture : distances, durées et tracés exacts demandés à Mapbox Directions pour cette réponse, jamais enregistrés ; nos estimations si Mapbox ne répond pas (estimated, sans tracé, D-088). Parcours access = premium pour un appelant non abonné : étape 1 complète, étapes suivantes réduites à heure, catégorie, durée et trajet, sans lieu, coordonnées ni conseil, et pas de tracé (D-014). Parcours retiré : 410 avec la date du retrait. Contrat détaillé, en brouillon : Fiche parcours
GET	/routes/:id/timeline	Query startsAt= : timeline recalculée et conflits, sur les trajets exacts de Mapbox quand il répond, nos estimations sinon (D-088). Le brouillon #393 propose nos estimations seules (Q6) : Fiche parcours
GET	/geocode	Query q=, proxy Mapbox (Geocoding et Search Box pour les stations), interrogé dans l'emprise de l'Île-de-France ; une zone n'est gardée que si chaque mot tapé commence un mot de son nom. Sans cache (résultats temporaires de Mapbox, qu'il est interdit de conserver) : Cache-Control: no-store. Limité à 30 requêtes par minute et par IP. Le géocodage permanent, qui permettrait un cache de 24 h, est écarté pour l'instant, question ouverte (D-081, voir Recherche textuelle)
GET	/weather/today	Query city=paris : `{ condition: 'rainy'
GET	/config	Taxonomies, libellés, seuils publics (dont ceux de la certification), questions d'anecdote actives (clé, libellé, ordre), versions de l'app par plateforme : minVersion (sous elle, E-20 bloque) et recommendedVersion (sous elle, E-20 propose la mise à jour, D-063) ; versions en vigueur des textes légaux (legal.terms, legal.privacy)
GET	/legal/:doc	doc = terms ou privacy, `?locale=fr
POST	/support/messages	Formulaire « Nous écrire » (E-19, D-063), avec ou sans jeton : `{ topic: 'question'

Card de recherche

Card de /routes/search (RouteCard dans packages/shared), telle que livrée par #25, #161, #63 et #170 (D-066), révisée pour les parcours Premium par D-075 :

• id, title, coverUrl (photo de couverture du parcours), isOfficial, author (id, firstName, avatarUrl ; null pour un parcours « Par Widoo », et quand l'auteur est supprimé ou son profil non public, D-025), access (free, premium), isVerified, moods (la première est l'ambiance principale), audiences, district et neighborhood du départ (« 3e », « Le Marais »), durationMin et durationBucket, distanceM, rating (average, null avant le premier avis, et count).
• budgetPerPersonEur : somme exacte des coûts des étapes par personne, en euros, un seul nombre ; plus de fourchette (D-032, #170). L'app l'arrondit à l'affichage (« ≈ 25 € par pers. », « Gratuit » à zéro). budgetBucket est dérivé de la même somme exacte, jamais de l'arrondi.
• isLocked : true quand la card d'un parcours access = premium est verrouillée pour l'appelant, false sinon (toujours false pour un parcours gratuit). L'app lit ce champ, jamais access seul, pour choisir l'affichage : une card Premium déverrouillée s'affiche comme un parcours gratuit, avec sa pastille Premium (D-075).
• stepCount : nombre d'étapes du parcours, exact, que steps les porte toutes ou non.
• steps[], dans l'ordre, pour les pastilles et la tooltip de la carte (E-04) : category (valeur de places.category), location ({ lat, lng }), name (nom du lieu) et durationMin (durée sur place, pour « Étape i/n · catégorie · durée »). Parcours gratuit : toutes les étapes. Parcours access = premium : la règle d'E-04 (« Abonné, le tap validé ne change pas ») se tient dans l'API (D-014, D-075).
  • Card verrouillée (isLocked = true), sans jeton ou pour un compte qui n'a pas droit au parcours : le départ seul, avec sa catégorie et ses coordonnées, name et durationMin à null ; les étapes 2 et suivantes ne quittent pas l'API, ni nom, ni lieu, ni coordonnées, ni photo. La tooltip Premium lit stepCount et durationMin du parcours (« 4 étapes en 7 h ») ; la carte se recadre sans tracé ni étapes.
  • Card déverrouillée (isLocked = false), avec le jeton valide d'un compte qui a droit au parcours : toutes les étapes, comme un parcours gratuit ; la carte affiche tracé, étapes et tooltips.
  • Droit au parcours : aujourd'hui, un compte dont users.plan vaut premium et dont users.plan_expires_at n'est pas passé. Le pass 7 jours (même colonnes) et le déblocage à l'unité (route_unlocks) entrent dans la même règle par #66, calculée en un seul endroit du code et partagée avec /routes/:id (#36).
  • Écarté : réduire la card pour tout le monde au nom du cache public (choix de #161, refusé le 2026-09-29) ; faire attendre l'abonné jusqu'à l'ouverture de la fiche.
• Photo de la ligne d'étape de la tooltip : la maquette montre la photo du lieu de l'étape (E-04), que la card ne porte pas ; l'app affiche aujourd'hui coverUrl. Décision (D-066) : la card gagne steps[].photoUrl (photo principale du lieu en vignette, null sans photo ; présente seulement sur les étapes que la card porte, donc absente des étapes 2 et suivantes d'une card verrouillée, D-075), la tooltip retombant sur coverUrl quand elle est nulle ; nécessaire à la tooltip d'une étape touchée (#153), dont le lieu n'est pas celui de la couverture. Confirmé par Ilan le 2026-09-28 (D-071) ; photo principale d'un lieu : voir Modele-de-Donnees › media ; livré par #219.
• reason : raison principale du classement, avec sort=recommended seulement (absente avec les autres tris) : { key: 'near_you', distanceM }, ou { key } parmi top_rated, verified, fresh, good_timing, official ; null quand aucune composante ne se dégage, et l'app n'affiche alors rien. Clés techniques ; les libellés sont dans l'app, qui n'affiche que good_timing et fresh (D-071). Règles : Filtres-et-Recherche › Recommandation (#63).

Fiche parcours (brouillon #393)

Statut : 🟡 Brouillon du 2026-10-14, à valider par Ilan, en réponse à #393. Rien ici n'est encore décidé : chaque choix ouvert est une question numérotée (Questions à trancher), avec la recommandation et ce qu'elle écarte. Après validation : entrée D-xxx au Design-Changelog, report par MANAGER dans #36.

Contrat de GET /routes/:id (la fiche, Ecrans › E-05) et de GET /routes/:id/timeline. Point de départ : le schéma RouteDetail de packages/shared/src/schemas/route-detail.ts, fixé par la PR #390 (#37) ; cette section en est le résumé lisible et liste ce que #36 doit y ajouter. L'endpoint tient ce schéma partagé, sans seconde définition.

Qui obtient quoi

Authentification facultative, comme /routes/search (voir Conventions, D-075) : la réponse dépend de l'appelant (droit Premium, myReport). Un jeton Firebase invalide ou expiré répond 401 unauthorized. Le droit au parcours entier se décide par canAccessRoute(route, viewer, now) (apps/api/src/access/route-access.ts), la règle unique déjà lue par la recherche et la programmation, sans seconde implémentation.

Statut du parcours	Sans jeton de lien	Avec ?token= valide (routes.share_token)	Auteur connecté
published, needs_fix	200	200, jeton ignoré	200
private	404 not_found	200, avec sharedBy	200
pending, changes_requested, jamais publié	404	200, avec sharedBy (Q4)	200
pending, changes_requested, déjà publié (un needs_fix corrigé et resoumis, PR #420)	404 (Q3)	404 (Q3)	200
draft, rejected	404	404	404 : l'auteur les lit par GET /me/routes/:id
unpublished	410 route_removed	410	410 : l'auteur le rouvre par GET /me/routes/:id
inexistant, ou supprimé avec le compte de son auteur (D-025)	404	404	—

• Identifiant mal formé : 400 validation_error (D-071). Jeton faux ou d'un autre parcours : 404, jamais 403, pour ne pas confirmer qu'un parcours privé existe.
• Pas d'exception de rôle : un modérateur lit un parcours par GET /admin/routes/:id.
• Auteur supprimé : un parcours publié anonymisé reste servi, author à null (« Membre Widoo », D-025).

Réponse 200 de GET /routes/:id

Query : token (lien privé) ; trips=estimated (nos estimations seules, sans appel à Mapbox ni tracé, pour le site, Q9) ; toute autre clé : 400 validation_error.

RouteDetail, tel que l'appelant a le droit de le voir :

• Identité : champs de la card (id, title, coverUrl, isOfficial, author, access, isVerified, moods, audiences, conditions, transport, district, neighborhood, rating, stepCount), plus status (published ou needs_fix pour le public), description, photoUrls (couverture d'abord).
• Chiffres (issus de computed, sans exposer l'objet brut) : durationMin, durationBucket, distanceM, walkingDistanceM, effort, budgetPerPersonEur et budgetBucket, startAccess (station la plus proche du départ, D-050, null tant qu'elle n'est pas calculée). Le budget est la somme exacte, comme sur la card ; l'app l'arrondit (« ≈ 25 € par pers. », D-032, D-066 ; Q11). Les paliers restent ceux enregistrés ; durée, distance, marche et effort sont ceux des trajets de la réponse (Q6).
• Créateur : creator (routesPublished, isCertified, D-023) ; sharedBy (firstName) pour un parcours privé ouvert par son lien (« Partagé par Camille »), null sinon.
• Avis : reviews, les trois derniers avis visibles, du plus récent au plus ancien (prénom, note, commentaire, date ; sans réponse) ; la liste complète est GET /routes/:id/ratings.
• Timeline : timeline, celle du départ conseillé, aujourd'hui dans la ville (« Départ conseillé à 10:00 ») : routes.suggested_start, sinon le départ calculé (D-050). Même forme RouteTimeline que celle de PlannedRoute (GET /me/planned, PR #401) : { startsAt, endsAt, steps: [{ stepId, arrivesAt, leavesAt, conflicts }] }, une entrée par étape dans l'ordre des étapes, conflits d'Orchestration › Timeline (closed_at_arrival, closed_that_day, closes_during_step, hours_unknown).
• Étapes : steps, toutes, dans l'ordre (steps.length = stepCount).
  • Étape complète (isLocked: false) : titre, description (le conseil du créateur), durée, coût, réservation (bookingRequired, bookingUrl, bookingProvider, bookingNote, bookingIsAffiliate, D-048, D-052), endsOn (étape éphémère, D-050), transitionNote, le lieu (name, category, location, address, isIndoor, photoUrl, verificationStatus, verifiedAt, hours) et la vérification { confirmations, lastConfirmedAt, reports: { count, lastAt } | null } (D-013, D-056 ; « Pas encore vérifié » quand lastConfirmedAt est nul).
  • Étape verrouillée (isLocked: true, LockedStep strict) : id, position, category, durationMin, transition seulement. Le schéma refuse tout autre champ : ni nom, ni lieu, ni coordonnées, ni conseil, ni photo ne quittent l'API (D-014).
  • Trajet vers l'étape suivante (transition, null pour la dernière) : distanceM, durationMin, mode, estimated, et geometry, à ajouter au schéma pour #154 : le tracé dans les rues en polyline encodée (précision 5, ce que apps/api/src/directions/mapbox.ts demande déjà), null sans tracé.
• Pour l'utilisateur connecté : myReport, date de son signalement du parcours s'il date de moins de 7 jours et n'est pas tranché, null sinon (D-057) ; absent ou null sans jeton.

Trajets exacts, rien d'enregistré (D-088). À chaque GET /routes/:id d'un parcours que l'appelant voit en entier, l'API demande à Mapbox Directions les trajets à pied, à vélo et en voiture (profils walking, cycling, driving) pour cette réponse seulement : estimated: false, distance, durée et geometry de Mapbox. Rien n'est écrit en base (computed, steps.transition, direction_cache restent sur nos estimations), ni journalisé, ni mis en cache (voir En-têtes). Repli, jamais une erreur : Mapbox en échec, trop lent (4 s par appel, comme aujourd'hui) ou quota atteint, la réponse porte l'estimation enregistrée, estimated: true, geometry: null. Le métro n'a pas de profil Mapbox : toujours notre estimation, estimated: true, sans tracé (ligne droite dans l'app, #154). Piste de #36 : une requête par profil et par parcours, les étapes en points de passage (25 au plus), pour tenir la limite de 300 requêtes par minute.

Parcours Premium sans droit (isLocked: true, D-014, D-075) : étape 1 complète, étapes suivantes en LockedStep ; aucun tracé (geometry: null partout) ; aucun appel à Mapbox, trajets sur nos estimations (Q7) ; conflits de la timeline vides sur les étapes verrouillées, qui ne disent rien des horaires d'un lieu caché (Q7). La fiche reste lisible : photos, titre, chiffres, description, infos, créateur, avis.

Avertissements utiles au lecteur (Q10) : la fiche ne porte ni warnings ni errors de cohérence, réservés à l'éditeur (OwnRoute, PR #420) et à la modération ; « le score de cohérence n'est pas montré à l'utilisateur final » (Orchestration). Le lecteur voit ce qui le concerne par des champs déjà là : status = needs_fix (bandeau), les conflits de la timeline, la vérification et verificationStatus de chaque lieu (lieu signalé, stale, closed), endsOn d'une étape (« Une étape s'est terminée le 17 janvier »).

À ajouter au schéma de #390 par #36, décisions déjà prises que route-detail.ts ne porte pas encore :

• geometry de chaque trajet (D-088, #154) ;
• myReport (D-057) ;
• « À prévoir » : lignes du créateur (routes.tips) et suggestions calculées non masquées (computed, moins routes.tips_hidden), D-048, D-050, lues par E-06 ;
• crédit des photos libres (author, license, sourceUrl, D-052) : photoUrls et place.photoUrl deviennent des objets photo, null pour une photo de créateur ;
• timezone de la ville (fuseau IANA, comme PlannedRouteSnapshot) : les horaires sont des heures locales, et « Ouvert aujourd'hui » se lit à l'heure de Paris, pas à celle du téléphone.

Hors de #36 : la traduction (route_translations, D-076), qui ajoutera sa langue d'origine et ses champs traduits avec son propre ticket ; l'état « déjà programmé » de la barre (D-035), lu sur GET /me/planned.

GET /routes/:id/timeline?startsAt=

• Query : startsAt obligatoire, date et heure ISO 8601 avec décalage, même format que POST /me/planned ; token pour un parcours privé. Clé inconnue ou valeur invalide : 400 validation_error.
• Mêmes règles d'accès que la fiche (404, 410, jeton). Parcours Premium sans droit : 402 premium_required, details.reason: premium_route, comme PATCH /me/planned/:id sur startsAt (D-038) : sans droit, on ne programme pas (Q7).
• Réponse : RouteTimeline pour ce départ, même forme que timeline de la fiche et de PlannedRoute, horaires valables à la date demandée (horaires saisonniers, jour de fermeture), conflits compris.
• Trajets : nos estimations, celles que POST /me/planned fige dans la programmation, pour que l'heure de fin vue dans E-06 soit celle de la sortie enregistrée ; aucun appel à Mapbox (Q6, qui amende la ligne du tableau ci-dessus).
• Ce qui reste à /timeline : un autre départ que le départ conseillé (E-06 « Autre date », changement d'heure). La fiche n'a pas besoin de l'appeler à l'ouverture : sa timeline est dans RouteDetail.

Parcours retiré : la 410

Un parcours unpublished (retiré par son auteur, par l'équipe, ou dépublié parce qu'un de ses lieux a fermé définitivement) répond, à tout appelant et avec ou sans jeton :

HTTP/1.1 410 Gone
{
  "code": "route_removed",
  "message": "Route removed",
  "details": {
    "removedAt": "2026-09-20T08:12:00.000Z",
    "near": { "lat": 48.86, "lng": 2.35 }
  }
}

• Code stable route_removed, à ajouter à la liste des Conventions ; il figure déjà dans apiErrorCodes (packages/shared/src/schemas/error.ts), et details est validé côté app par RouteRemovedDetails, auquel s'ajoute near. Corps unique ApiError d'apps/api/src/errors.ts (code, message, details), qui demande un apiCode explicite comme coherence_blocked, 410 n'ayant pas de code par défaut dans codeByStatus.
• removedAt : date du passage en unpublished. Aucune colonne ne la porte aujourd'hui : routes.unpublished_at (timestamptz), posée par l'écrivain unique du statut (moveRoute) à chaque passage en unpublished, remise à null à la republication (Q2).
• near : la zone du parcours, pour que « Voir des parcours proches » recentre l'accueil (E-05) : les coordonnées du départ arrondies à deux décimales (environ 1,1 km du nord au sud, 0,7 km d'est en ouest à Paris), jamais le point exact (Q1).
• Rien d'autre du parcours retiré : ni titre, ni auteur, ni étapes, ni motif du retrait.
• La 410 vaut tant que la ligne du parcours existe ; un parcours supprimé avec le compte de son auteur répond 404 (seuls les parcours publiés sont gardés, anonymisés, D-025). Le site (/r/:id, E-21) rend sur la 410 l'encart « Ce parcours n'est plus disponible », sans lire near.
• Écart avec la planche parcours retiré : elle dit « Son créateur l'a retiré le 20 sept. », alors qu'un retrait peut venir de l'équipe ou d'un lieu fermé (Q2).

En-têtes de cache et limites

• GET /routes/:id, réponse 200 : Cache-Control: no-store, sans ETag (Q8). Elle porte des résultats de Mapbox Directions, qu'il est interdit de conserver (D-088), comme /geocode (D-081) ; et elle dépend de l'appelant. L'app garde la fiche ouverte en mémoire pendant qu'on la lit, sans la persister.
• Limite : 60 requêtes par minute et par IP sur GET /routes/:id, chaque ouverture coûtant une requête Mapbox par profil, voire par trajet (menace « abus des API tierces payantes », Securite-et-RGPD) ; 429 rate_limited au-delà (Q8).
• GET /routes/:id/timeline, sans données Mapbox : comme /routes/search, Cache-Control: public (60 s, ETag) sans Authorization ni token ; private, no-cache et Vary: Authorization avec un jeton Firebase ; private, no-store avec un token de lien privé (règle de /r/:id, Site-Web).
• Erreurs (400, 401, 402, 404, 410, 429) : jamais mises en cache, comme aujourd'hui (cacheHook).
• Site widoo.app : son cache de 5 minutes sur /r/:id ne peut pas garder de résultat Mapbox ; il lit la fiche avec ?trips=estimated, sans appel à Mapbox, réponse alors cachable comme /timeline (Q9).

Questions à trancher (#393)

Pour Ilan. Chaque question porte la recommandation, puis ce qu'elle écarte.

1. Zone dans la 410. La 410 porte-t-elle un point pour « Voir des parcours proches » ? Recommandé : oui, details.near, départ arrondi à 0,01° (environ 1 km), assez pour recentrer la carte de l'accueil sur le quartier, sans désigner un lieu. Écarte : le départ exact (il nommerait le premier lieu d'un parcours peut-être retiré pour « Lieu dangereux ou interdit d'accès ») ; l'arrondissement en texte (l'app devrait le géocoder par Mapbox, et « 3e » seul n'a pas de centre) ; l'emprise du parcours (elle trace sa forme) ; rien (l'accueil s'ouvrirait sur la position de l'utilisateur, alors qu'E-05, validée, dit « accueil centré sur sa zone »).
2. Date et auteur du retrait. Recommandé : nouvelle colonne routes.unpublished_at, et un texte neutre sur la planche, « Ce parcours a été retiré le 20 sept. », sans dire qui l'a retiré. Écarte : details.removedBy (author ou team), qui dirait publiquement que l'équipe a retiré le parcours d'un créateur nommé ailleurs ; garder « Son créateur l'a retiré » pour tous les retraits (faux pour un retrait de l'équipe ou un lieu fermé) ; lire la date dans un journal d'actions, qui ne couvre pas les retraits de l'auteur.
3. Parcours déjà publié en cours de relecture. Un needs_fix corrigé par son auteur repasse pending et sort du public jusqu'à la décision (choix 5 de la PR #420, à confirmer). Que voit celui qui l'ouvre d'un favori ? Recommandé : 404, comme un parcours introuvable, pour un état court et rare au MVP. Écarte : la 410 (elle annoncerait un retrait qui n'a pas eu lieu, avec une fausse date) ; un nouvel état « en cours de correction » (planche à faire). À reconsidérer : corriger un needs_fix par une révision, comme un parcours publié, pour qu'il reste visible avec son bandeau pendant la relecture (#53).
4. Lien privé d'un parcours soumis. Recommandé : le jeton ouvre le parcours tant qu'il est private, pending ou changes_requested sans avoir été publié, comme le dit « Partageable : oui » de Creation-et-Moderation › Cycle de vie ; l'auteur le lit sans jeton. Écarte : un jeton valable seulement en private, qui casserait les liens déjà envoyés dès que l'auteur soumet.
5. L'auteur d'un parcours Premium. Recommandé : l'auteur a toujours droit à son propre parcours en entier, fiche et programmation, ce que canAccessRoute ne dit pas aujourd'hui (règle à étendre par #36 ou #66). Écarte : verrouiller l'auteur comme un autre non-abonné (il ne verrait plus ses étapes dans la fiche).
6. Trajets exacts ou estimés, fiche et /timeline. Recommandé : la fiche calcule durée, distance, marche, effort et sa timeline sur les trajets de la réponse (exacts quand Mapbox répond), pour que les heures s'additionnent avec les trajets affichés ; paliers et filtres restent sur l'enregistré. /timeline reste sur nos estimations, celles que la programmation enregistre, ce qui amende la ligne actuelle « sur les trajets exacts de Mapbox » (D-088). Écarte : /timeline exacte (l'heure de fin vue dans E-06 différerait de quelques minutes de la sortie enregistrée, et chaque changement de date coûterait des requêtes Mapbox) ; une fiche entièrement estimée (« 15 min à pied » affiché, 13 min entre deux heures).
7. Parcours Premium sans droit. Recommandé : aucun appel à Mapbox (trajets estimés, aucun tracé), conflits vides sur les étapes verrouillées, /timeline en 402 premium_required. Écarte : interroger Mapbox pour des étapes que l'appelant ne voit pas (coût sans usage) ; des conflits qui laisseraient deviner les horaires d'un lieu caché ; une timeline à un départ libre pour un parcours qu'il ne peut pas programmer.
8. Cache et limite de la fiche. Recommandé : no-store sur la réponse 200 de GET /routes/:id, et 60 requêtes par minute et par IP. Écarte : le cache public court de la convention « toutes les lectures publiques sont cachables » (il garderait les résultats Mapbox dans le CDN et l'app, D-088), qui devient une exception à écrire dans Conventions ; aucune limite (une boucle d'ouvertures épuiserait le quota Mapbox de 300 requêtes par minute pour tous).
9. Le site /r/:id (E-21). Son rendu est mis en cache 5 minutes, et sa carte du parcours ne montre jamais le détail des étapes (E-21, D-068) : il n'a besoin d'aucun trajet. Recommandé : le site lit la fiche avec ?trips=estimated (nos estimations seules, aucun appel à Mapbox, réponse cachable 5 minutes comme /timeline). Écarte : un appel à Mapbox à chaque revalidation du site, pour des trajets qu'il n'affiche pas ; un résultat Mapbox gardé 5 minutes dans son cache (interdit par D-088) ; un endpoint de plus, propre au site.
10. Avertissements dans la fiche. Recommandé : aucun warnings ni errors de cohérence dans la fiche ; le lecteur voit status, les conflits, la vérification et les dates de fin. Écarte : exposer les avertissements de l'éditeur (too_many_transitions, back_and_forth…), qui parlent au créateur et à la modération, pas à celui qui sort.
11. Budget. Recommandé : somme exacte, comme sur la card (D-066), l'arrondi aux 5 € restant dans l'app (une seule fonction partagée, que le test « 23 € donne 25 € » de #36 vise). Écarte : un budget déjà arrondi par l'API, que demande encore le corps de #36 et qui ferait deux règles entre la card et la fiche.

Compte (auth)

Méthode	Route	Description
GET	/me	Profil complet (bio, quartier, anecdotes, à la une), rôle, plan, préférences, canCreateRoute (faux pour un compte gratuit qui a déjà son parcours), certification (critères avec valeur, seuil et état). Plus de compteurs du mois (D-023)
PATCH	/me	Prénom ou pseudo, avatar, bio (150 caractères), quartier (facultatif), isPublic, locale (fr, en, ou null pour la langue du téléphone, D-062), notificationPrefs ({ reminders, nextDay, myRoutes }, booléens, D-062), anecdotes (liste ordonnée [{ questionKey, answer }], 3 au plus, question unique, réponse de 150 caractères) et featuredRouteIds (3 au plus, parcours publiés de l'appelant), enregistrés en une transaction par « Enregistrer » de Modifier le profil ; 422 validation_error sinon
POST	/webhooks/revenuecat	Webhook signé : met à jour plan et plan_expires_at
DELETE	/me	Suppression de compte, sans paramètre (D-025) : parcours publiés anonymisés (auteur « Membre Widoo »), tout le reste supprimé
POST	/me/devices	Enregistrement du jeton push, avec la langue du téléphone (locale) : langue des push quand users.locale est nul (D-062)
POST	/me/email	{ newEmail } (D-062) : envoie à la nouvelle adresse un lien de confirmation, dans la langue du compte ; l'ancienne adresse reste active. Remplace une demande en attente. 409 conflict (details.reason email_in_use), 422 validation_error, 429 rate_limited moins de 30 s après l'envoi précédent
POST	/me/email/confirm	{ token } (lien ouvert dans l'app) : l'adresse change dans Firebase Auth (Admin updateUser, emailVerified) et dans users.email ; la connexion par e-mail suit, Apple et Google ne changent pas. 410 link_expired
GET	/me/export	Export de vos données (E-19 › Confidentialité, D-063) : un JSON (profil, anecdotes, à la une, favoris, sorties programmées et passées, notes, parcours créés avec leurs étapes et les liens de leurs photos, préférences), Content-Disposition: attachment; filename=widoo-donnees-AAAA-MM-JJ.json ; préparé à la demande, non conservé ; 429 rate_limited au-delà de quelques demandes par heure
DELETE	/me/email	Annule le changement en attente (« Annuler » de E-19) ; le lien déjà envoyé ne marche plus

🟡 Brouillon #383 du 2026-10-14, à valider par Ilan, voir Compte-et-Monetisation › Fin de la limite de création : proposé, canCreateRoute est retiré de GET /me, sans remplaçant (jamais codé) : la création n'a plus de limite, la seule limite se dit à la soumission.

Favoris et programmation (auth)

Méthode	Route	Description
GET	/me/favorites
PUT / DELETE	/me/favorites/:routeId	Sans limite (D-023)
GET	/me/planned	Query status=
POST	/me/planned	{ routeId, startsAt } → programmation avec timeline et checklist. 402 premium_required (parcours Premium pour un non-abonné) ; sans limite sinon (D-023)
POST	/me/planned/:id/rating	{ rating, comment? } ; exige un Go terminé ; crée ou met à jour route_ratings
PATCH	/me/planned/:id	startsAt, checklist, status (planned pour « Rétablir » ou « Reprogrammer », in_progress, completed, cancelled) ; changer startsAt recalcule la timeline et recale les rappels ; parcours Premium sans abonnement : 402 premium_required sur startsAt et in_progress (D-038). personalNote retiré (D-029)
POST	/me/planned/:id/steps/:stepId/done	Coche une étape (Go) ; corps facultatif { signal: { kind, reason?, comment? } } pour la vérification sur place
GET	/me/planned/:id/maps-url	URL Google Maps à pied jusqu'à une étape, construite côté serveur : une URL par étape, jamais pour tout le parcours (D-032)

Création (auth)

Méthode	Route	Description
GET	/me/routes	Mes parcours, tous statuts
POST	/routes	Crée un brouillon, sans limite (révision du 2026-09-28 ; l'ancienne limite create_limit est abandonnée)
PATCH	/routes/:id	Informations, ambiances, publics, conditions, transport
PUT	/routes/:id/steps	Remplace la liste ordonnée des étapes ; retourne le résultat d'orchestration (computed, warnings, errors)
POST	/routes/:id/submit	Passe en pending ; 422 coherence_blocked si règles bloquantes
POST	/routes/:id/status	private, draft, unpublished par l'auteur
POST	/media/upload-url	{ ownerType, ownerId, contentType } → URL signée et mediaId
DELETE	/media/:id

🟡 Brouillon #383 du 2026-10-14, à valider par Ilan, voir Compte-et-Monetisation › Fin de la limite de création : proposé, POST /routes/:id/submit documente aussi la 429 rate_limited (details: { reason: 'pending_routes', limit }) déjà codée (#66, #48) : au-delà de settings.max_pending_routes (3) parcours en relecture, une révision en attente comptant pour un, compte editor non limité (à confirmer, question 4).

Lieux (auth)

Méthode	Route	Description
GET	/places/search	Query q=, near=, category= : lieux Widoo existants
POST	/places	Création ; répond 409 avec le candidat si un lieu proche de même nom existe, sauf force=true
PATCH	/places/:id	Auteur du lieu tant qu'il n'est utilisé que par ses parcours ; sinon modérateur
POST	/places/:id/signals	`{ kind: 'confirm'
POST	/routes/:id/reports	{ reason, stepId?, comment? } (D-056) ; stepId pour place_changed ; un signalement par utilisateur et par parcours sur 7 jours glissants (409 sinon) ; 403 sur ses propres parcours ; envoyé en différé par l'app hors connexion

Admin (rôles editor, moderator, admin)

Rôle exigé par section : matrice de Admin-Web › Rôles. Toute écriture est journalisée dans admin_actions (D-085). Jeton sans second facteur : 403 mfa_required (D-087). Une décision sur un parcours ou un signalement déjà tranché par un autre membre de l'équipe : 409 already_decided avec la décision prise.

Méthode	Route	Description
GET	/admin/moderation	File pending et changes_requested
GET	/admin/routes/:id	Fiche de modération (A-02) : parcours tel qu'il sera publié, avertissements de cohérence, différence avec la version publiée pour une révision, chiffres et historique de l'auteur, historique du parcours, position dans la file (« 1 sur 14 »)
GET	/admin/counters	Compteurs légers de la navigation (modération et ancienneté maximale, signalements, support, brouillons IA, traductions en échec), filtrés par rôle
POST	/admin/routes/:id/publish
POST	/admin/routes/:id/request-changes	{ message }
POST	/admin/routes/:id/reject	{ reasonCode, message }
POST	/admin/routes/:id/unpublish	{ reasonCode, message }
GET	/admin/signals	Groupés par lieu
POST	/admin/places/:id/verify	Remet verified, purge les signaux ouverts
POST	/admin/places/:id/close	{ reason } ; passe closed, parcours concernés en needs_fix
POST	/admin/signals/:id/reject	{ reason }
GET	/admin/reports	Signalements de parcours ouverts, avec l'étape pour place_changed (D-056)
POST	/admin/reports/:id/resolve	`{ outcome: 'accepted'
POST	/admin/ratings/:id/hide	{ reason } ; masque un commentaire
POST	/admin/users/:id/certification	`{ override: 'none'
GET	/admin/stats	Compteurs du tableau de bord
POST	/admin/places/import	CSV, rôle admin
POST	/admin/routes/:id/republish	Republie un parcours dépublié
POST	/admin/routes/:id/reassign	Réassigne à l'équipe Widoo
GET	/admin/ratings	Avis avec commentaire, filtres note et parcours ; POST /admin/ratings/:id/unhide rétablit
PATCH	/admin/places/:id	Édition d'un lieu, dont partner_booking_url et partner_program_id ; POST /admin/places crée un lieu
GET	/admin/users, /admin/users/:id	Recherche et fiche (A-06)
PATCH	/admin/users/:id/role	Rôle admin seulement ; jamais sur soi-même
POST	/admin/users/:id/suspend, /reactivate	{ reason } ; un compte suspendu reçoit 403 account_suspended partout
POST	/admin/users/:id/gift	{ until? , routeId? } : Premium offert jusqu'à une date ou un parcours offert, plan_source = gift
GET	/admin/users/:id/export	Export RGPD, même contenu que celui de l'app
DELETE	/admin/users/:id	Même règle que la suppression dans l'app
POST, GET, PATCH, DELETE	/admin/ai-drafts	Génération, liste, éditeur assigné, suppression des brouillons IA (A-07, #247)
GET	/admin/translations	Traductions en échec ou corrigées ; POST /:id/retry, PATCH /:id (champ corrigé)
GET, POST, PATCH	/admin/affiliate-programs	Programmes d'affiliation (A-09)
GET	/admin/bookable-steps	Étapes réservables, origine du lien, clics sur 30 jours
GET, POST, PATCH	/admin/b2b-clients	Partenaires B2B ; PUT /:id/routes : 3 à 10 parcours dans l'ordre (A-10)
GET	/admin/settings	Réglages ; PATCH /admin/settings/:key (admin), validation par clé, effet sous une minute
GET	/admin/actions	Journal (admin)
GET	/admin/support	Messages « Nous écrire » ; POST /:id/reply (e-mail Brevo E-22), POST /:id/handled

Publics liés à l'admin : GET /go/:stepId enregistre un clic dans booking_clicks et redirige (302) vers le lien de réservation affiché (créateur d'abord, D-048) ; GET /public/partners/:slug sert la page partenaire B2B du site.

Interne (jeton de service, Cloud Scheduler)

Appelées par Cloud Scheduler avec Authorization: Bearer <INTERNAL_TOKEN>, jamais par un utilisateur ni par l'admin web : 401 sans le bon jeton (comparé en temps constant) ; routes absentes quand le jeton n'est pas configuré ; Cache-Control: no-store ; hors de la documentation publique de l'API (D-066).

Méthode	Route	Description
POST	/internal/recommendation	Recalcul nocturne des composantes stables du score de recommandation dans routes.recommendation (qualité, fiabilité, fraîcheur, officiel, moments ; voir Filtres-et-Recherche › Recommandation) ; réponse { updated } (#63)
POST	/internal/certification	Recalcul nocturne du badge Créateur certifié selon les seuils de settings
POST	/internal/recompute	Recalcul des parcours dont un lieu a changé
POST	/internal/reminders	Rappels J-1 et H-1 des parcours programmés
POST	/internal/verification-decay	Passage verified → stale après 90 jours