Référence de l'API

Cette page liste toutes les routes HTTP du backend. Le tableau est généré à la construction de la documentation en lisant backend/src/app.ts et chaque fichier *.routes.ts : méthode, chemin complet, accès requis, middlewares de contrôle et résumé OpenAPI. Les règles métier, les corps de requête et les erreurs de chaque route sont détaillés dans les pages Modules métier.

#Swagger UI

Le serveur publie une interface Swagger sur /api/docs, par exemple http://localhost:2053/api/docs en local. La spécification OpenAPI 3.0 est construite au démarrage par swagger-jsdoc à partir des blocs @openapi placés au-dessus de chaque route (backend/src/config/swagger.config.ts). Elle lit les fichiers src/api/**/*.routes.ts en développement et dist/src/api/**/*.routes.js après compilation.

Les blocs OpenAPI ne contiennent qu'une étiquette et un résumé : ni paramètres, ni corps, ni réponses. Swagger UI sert donc d'index cliquable et de console pour envoyer une requête avec un jeton (bouton Authorize), pas de contrat d'interface. La route /api/docs est servie dans tous les environnements, production comprise, et passe par le rate limiting global.

#Préfixes

Les deux préfixes partagent les mêmes compteurs de rate limiting et les mêmes clés d'idempotence par utilisateur, mais pas le même chemin : une clé d'idempotence utilisée sur /api/lottery/buy n'est pas reconnue sur /api/v1/lottery/buy.

#Authentification

Les routes protégées attendent un jeton de session dans l'en-tête Authorization :

GET /api/v1/user/profile HTTP/1.1
Host: localhost:2053
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIwMTlhN2MzZS...

Le jeton s'obtient par POST /auth/login puis POST /auth/2fa/verify (voir Authentification). Il n'y a ni cookie de session, ni jeton de rafraîchissement : à l'expiration (12 heures par défaut), le client doit se reconnecter. Le préfixe Bearer est sensible à la casse.

#Idempotence

Cinq routes acceptent l'en-tête Idempotency-Key : POST /lottery/buy, POST /lottery/gift, POST /lottery/claim-prize, POST /marketplace/claim et POST /marketplace/scratch. Le middleware backend/src/middlewares/idempotency.middleware.ts protège contre le double clic et les nouvelles tentatives réseau d'une opération qui dépense des ethers ou des points.

POST /api/v1/lottery/buy HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Idempotency-Key: 6b0f3c2e-9d41-4a7e-b5a8-1c2d3e4f5a6b

{"quantity":1}

Le corps de la requête ne fait pas partie de la clé : la même clé avec un autre corps rejoue la première réponse. Une erreur 400 ou 409 est mémorisée comme un succès ; après une erreur de validation, il faut une nouvelle clé. Sans Redis, les clés sont gardées dans la mémoire du process et ne protègent plus contre un rejeu reçu par une autre instance.

#Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy (format draft-7 de l'IETF), exposés aux navigateurs par CORS. Au-delà de la limite, la réponse est un 429 au format habituel, par exemple { "success": false, "message": "Trop de requêtes depuis cette adresse IP, veuillez réessayer plus tard." }. Les compteurs sont dans Redis (ratelimit:global:, ratelimit:auth:, ratelimit:identity: et ratelimit:support:) ; si Redis répond en erreur, la requête passe (passOnStoreError). Derrière un proxy, TRUST_PROXY doit être réglé, sinon tous les clients partagent l'IP du proxy.

#Corps et formats

Les corps sont en JSON (Content-Type: application/json) ou en formulaire URL-encodé, 1 Mo au plus, sauf POST /user/identity, qui accepte 12 Mo de JSON pour les deux photos encodées en base64. Un JSON mal formé renvoie 400 Corps de requête JSON invalide, un corps trop gros 413 Corps de requête trop volumineux. Les réponses suivent le format décrit dans Réponses et erreurs, sauf trois exceptions : les sondes /health*, les métadonnées POAP GET /lottery/poap/:file et /metrics.

#Lire les résumés OpenAPI

La colonne « Résumé » du tableau reprend le summary du bloc @openapi placé au-dessus de chaque route, celui qu'affiche aussi Swagger. Les résumés ont été alignés sur le comportement réel du code. Quelques nuances ne tiennent pas dans une ligne : elles sont détaillées dans les pages de modules.

#Routes

Chaque route est servie sous /api/v1 et, pour compatibilité, sous /api. Les sondes et métriques du module système sont à la racine du serveur.

L'API expose 70 routes réparties en 9 modules.

#Système

Fichier source : backend/src/api/system/system.routes.ts

#Authentification

Fichier source : backend/src/api/auth/auth.routes.ts

#Loterie

Fichier source : backend/src/api/lottery/lottery.routes.ts

#Boutique et récompenses

Fichier source : backend/src/api/marketplace/marketplace.routes.ts

#Partenaires

Fichier source : backend/src/api/partners/partners.routes.ts

#Utilisateur et RGPD

Fichier source : backend/src/api/user/user.routes.ts

#Analytique

Fichier source : backend/src/api/analytics/analytics.routes.ts

#Administration Mairie

Fichier source : backend/src/api/admin/admin.routes.ts

#Webhooks

Fichier source : backend/src/api/webhooks/webhooks.routes.ts