API

API

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

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 }.
• 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[], `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'

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 ; 402 premium_required (details.reason = create_limit) si un compte gratuit a déjà un parcours non supprimé (D-023)
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'
POST	/internal/certification	Recalcul nocturne du badge Créateur certifié selon les seuils de settings
POST	/internal/recommendation	Recalcul nocturne des composantes stockées du score
GET	/admin/stats	Compteurs du tableau de bord
POST	/admin/places/import	CSV, rôle admin

Interne (jeton de service, Cloud Scheduler)

Méthode	Route	Description
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