API

API

Statut : 🟡 Brouillon · Màj : 2026-09-28 · Tickets : #164

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).
• Dates ISO 8601 UTC ; coordonnées { lat, lng }.
• Toutes les lectures publiques sont cachables (Cache-Control court, ETag).

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é. 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
GET	/routes/:id/timeline	Query startsAt= : timeline recalculée et conflits
GET	/geocode	Query q=, proxy Mapbox Geocoding restreint FR, avec cache
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) :

• 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.
• stepCount : nombre d'étapes du parcours, 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 : le départ seul, avec name et durationMin à null ; les étapes 2 et suivantes ne quittent jamais l'API, ni lieu ni coordonnées, puisque la recherche est publique (D-014, #161). La tooltip Premium lit stepCount et durationMin du parcours (« 4 étapes en 7 h »).
• 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 et sur un parcours Premium), 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).

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

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

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ôle moderator ou admin)

Méthode	Route	Description
GET	/admin/moderation	File pending et changes_requested
POST	/admin/routes/:id/publish
POST	/admin/routes/:id/request-changes	{ message }
POST	/admin/routes/:id/reject	{ reasonCode, message }
POST	/admin/routes/:id/unpublish
GET	/admin/signals	Groupés par lieu
POST	/admin/places/:id/verify	Remet verified, purge les signaux ouverts
POST	/admin/places/:id/close	Passe closed, parcours concernés en needs_fix
POST	/admin/signals/:id/reject
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	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

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