Documentation API Backend (OpenAPI/Swagger)

1

VUE D'ENSEMBLE DE L'API

1.1 Introduction

Cette documentation décrit l'API REST Backend de REWAPP au format OpenAPI 3.0 (Swagger). L'API permet l'interaction entre les différentes applications clientes (Application Mobile, Dashboard Partenaire, Dashboard Admin, Site Vitrine) et le système backend.

1.2 Caractéristiques Principales

Spécifications Techniques

Caractéristique	Valeur
Spécification	`OpenAPI 3.0.3`
Base URL Production	`https://api.rewapp.fr/api/v1`
Base URL Staging	`https://api-staging.rewapp.fr/api/v1`
Format de données	`JSON (application/json)`
Authentification	`Bearer Token (JWT RS256)`
Versioning	`URL-based (/api/v1, /api/v2)`
Encodage	`UTF-8`

1.3 URLs de Documentation

Ressources de Documentation

Ressource	URL
Swagger UI	`https://api.rewapp.fr/docs`
OpenAPI JSON	`https://api.rewapp.fr/docs/openapi.json`
OpenAPI YAML	`https://api.rewapp.fr/docs/openapi.yaml`
ReDoc	`https://api.rewapp.fr/redoc`
JWKS (clés publiques)	`https://api.rewapp.fr/.well-known/jwks.json`

2

INFORMATIONS OPENAPI

2.1 Spécification OpenAPI

YAML

openapi: 3.0.3
info:
  title: REWAPP API
  description: API Backend pour la plateforme de cashback REWAPP
  version: 1.0.0
  contact:
    name: REWAPP Support Technique
    email: api-support@rewapp.fr
    url: https://developers.rewapp.fr
  license:
    name: Propriétaire
    url: https://rewapp.fr/legal/api-license
  termsOfService: https://rewapp.fr/legal/api-terms

servers:
  - url: https://api.rewapp.fr/api/v1
    description: Production
  - url: https://api-staging.rewapp.fr/api/v1
    description: Staging
  - url: http://localhost:3000/api/v1
    description: Développement local

2.2 Tags de l'API

Liste des Tags

Tag	Description
`Authentication`	Authentification et gestion des sessions JWT
`Users`	Gestion du profil utilisateur et préférences
`Points`	Gestion des points de fidélité et solde
`QR Codes`	Génération et validation des QR codes de paiement
`Transactions`	Historique et détails des transactions
`Partners`	Recherche et informations sur les partenaires
`Banking`	Liaison carte bancaire et virements
`Notifications`	Gestion des notifications utilisateur
`Merchant`	Endpoints du dashboard partenaire
`Admin`	Endpoints d'administration (rôle admin requis)
`Webhooks`	Réception des événements externes

3

AUTHENTIFICATION ET SÉCURITÉ

3.1 Schéma d'Authentification

L'API utilise l'authentification JWT (JSON Web Token) avec l'algorithme RS256.

YAML

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT
    description: Token JWT obtenu via /auth/login

3.2 Structure du Token JWT

JSON - Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key_2025_v1"
}

JSON - Payload

{
  "sub": "user_abc123def456",
  "email": "jean.dupont@example.com",
  "role": "USER",
  "permissions": ["read:points", "write:qrcode", "read:transactions"],
  "deviceId": "device_xyz789",
  "iat": 1732441800,
  "exp": 1732442700,
  "iss": "https://api.rewapp.fr",
  "aud": "rewapp-mobile"
}

3.3 Durée de Validité des Tokens

Durées de Validité

Type de Token	Durée	Stockage
Access Token	15 minutes	Mémoire client
Refresh Token	7 jours	Secure Storage / HttpOnly Cookie

3.4 Endpoints Publics

Tous les endpoints nécessitent une authentification sauf :

POST /auth/register
POST /auth/login
POST /auth/forgot-password
POST /auth/verify-email
GET /partners (liste publique)
GET /partners/:id (détail public)

3.5 Headers Requis

Headers HTTP

Header	Valeur	Obligatoire
`Authorization`	Bearer {access_token}	Oui
`Content-Type`	application/json	POST/PUT
`Accept`	application/json	Recommandé
`Accept-Language`	fr-FR, en-US	Optionnel
`X-Device-Id`	{device_fingerprint}	Mobile
`X-App-Version`	1.0.0	Mobile

4

ENDPOINTS AUTHENTIFICATION

POST /auth/register

Crée un nouveau compte utilisateur.

Requête

JSON

{
  "email": "jean.dupont@example.com",
  "password": "MotDePasse123!",
  "firstName": "Jean",
  "lastName": "Dupont",
  "phoneNumber": "+33612345678",
  "acceptTerms": true,
  "acceptMarketing": false
}

Réponse 201 Created

JSON

{
  "success": true,
  "data": {
    "userId": "user_abc123def456",
    "email": "jean.dupont@example.com",
    "firstName": "Jean",
    "lastName": "Dupont",
    "status": "PENDING_VERIFICATION",
    "createdAt": "2025-11-24T10:30:00.000Z"
  },
  "message": "Compte créé. Veuillez vérifier votre email."
}

Validations

email : Format email valide, unique
password : Min 8 caractères, 1 majuscule, 1 chiffre, 1 caractère spécial
firstName/lastName : 2-50 caractères
phoneNumber : Format E.164 (+33...)

POST /auth/login

Authentifie un utilisateur et retourne les tokens JWT.

Requête

JSON

{
  "email": "jean.dupont@example.com",
  "password": "MotDePasse123!",
  "deviceId": "device_fingerprint_xyz",
  "deviceName": "iPhone 15 Pro"
}

Réponse 200 OK

JSON

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
    "expiresIn": 900,
    "tokenType": "Bearer",
    "user": {
      "id": "user_abc123def456",
      "email": "jean.dupont@example.com",
      "firstName": "Jean",
      "lastName": "Dupont",
      "role": "USER",
      "hasLinkedCard": true,
      "hasBankAccount": true
    }
  }
}

POST /auth/login/biometric

Authentifie via FaceID/TouchID avec le token biométrique stocké.

Requête

JSON

{
  "biometricToken": "bio_token_encrypted_xyz",
  "deviceId": "device_fingerprint_xyz"
}

POST /auth/refresh

Renouvelle l'access token avec un refresh token valide.

Requête

JSON

{
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

POST /auth/logout

Invalide les tokens de la session courante.

Headers : Authorization: Bearer {access_token}

Réponse : 204 No Content

POST /auth/forgot-password

Envoie un email de réinitialisation du mot de passe.

Requête

JSON

{
  "email": "jean.dupont@example.com"
}

Réponse 200 OK

JSON

{
  "success": true,
  "message": "Si cette adresse existe, un email a été envoyé."
}

POST /auth/reset-password

Réinitialise le mot de passe avec le token reçu par email.

Requête

JSON

{
  "token": "reset_token_from_email",
  "newPassword": "NouveauMotDePasse456!"
}

POST /auth/verify-email

Vérifie l'adresse email avec le token reçu.

Requête

JSON

{
  "token": "verification_token_from_email"
}

5

ENDPOINTS UTILISATEURS

GET /users/me

Récupère le profil de l'utilisateur connecté.

Réponse 200 OK

JSON

{
  "success": true,
  "data": {
    "id": "user_abc123def456",
    "email": "jean.dupont@example.com",
    "firstName": "Jean",
    "lastName": "Dupont",
    "phoneNumber": "+33612345678",
    "avatar": "https://cdn.rewapp.fr/avatars/user_abc123.jpg",
    "status": "ACTIVE",
    "preferences": {
      "language": "fr",
      "notifications": { "push": true, "email": true, "sms": false },
      "biometricEnabled": true
    },
    "stats": {
      "totalPointsEarned": 15420,
      "totalPointsSpent": 8500,
      "totalWithdrawals": 3,
      "memberSince": "2024-06-15T08:00:00.000Z"
    }
  }
}

PUT /users/me

Met à jour les informations du profil utilisateur.

Requête

JSON

{
  "firstName": "Jean-Pierre",
  "lastName": "Dupont",
  "phoneNumber": "+33698765432",
  "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}

PUT /users/me/preferences

Met à jour les préférences de notification et paramètres.

PUT /users/me/password

Change le mot de passe de l'utilisateur connecté.

Requête

JSON

{
  "currentPassword": "AncienMotDePasse123!",
  "newPassword": "NouveauMotDePasse456!"
}

DELETE /users/me

Supprime définitivement le compte utilisateur (RGPD).

ATTENTION

Action irréversible. Tous les points non utilisés seront perdus.

Requête

JSON

{
  "password": "MotDePasse123!",
  "reason": "Je n'utilise plus l'application",
  "confirmDeletion": true
}

Réponse 200 OK

JSON

{
  "success": true,
  "message": "Votre compte sera supprimé dans 30 jours.",
  "data": {
    "deletionScheduledAt": "2025-12-24T10:30:00.000Z"
  }
}

GET /users/me/export

Génère un export de toutes les données personnelles (RGPD).

GET /users/me/devices

Liste tous les appareils connectés au compte.

DELETE /users/me/devices/:id

Déconnecte un appareil spécifique.

Réponse : 204 No Content

6

ENDPOINTS POINTS ET FIDÉLITÉ

RÈGLES MÉTIER FONDAMENTALES

1 point = 0,10€
Cashback bancaire : points × 0,095 (-5%)
Cashback commerçant : points × 0,105 (+5%)
Validité : 12 mois, méthode FIFO

GET /points/balance

Récupère le solde de points de l'utilisateur.

Réponse 200 OK

JSON

{
  "success": true,
  "data": {
    "available": 2450,
    "pending": 150,
    "blocked": 0,
    "total": 2600,
    "equivalentEuros": {
      "bankCashback": 232.75,
      "merchantCashback": 257.25
    },
    "expiringPoints": {
      "next30Days": 500,
      "next7Days": 100,
      "nextExpiration": {
        "amount": 100,
        "expiresAt": "2025-12-01T23:59:59.000Z"
      }
    }
  }
}

GET /points/history

Récupère l'historique des mouvements de points.

Query Parameters : page, limit, type (CREDIT/DEBIT), startDate, endDate

GET /points/expiring

Liste les lots de points proches de l'expiration.

GET /points/tiers

Récupère les paliers de fidélité par commerçant.

RÈGLES PALIERS

Bronze : +0% (défaut)
Silver : +5%
Gold : +10%
Platine : +15%
Diamant : +20%

Calcul sur 12 mois glissants par commerçant. Recalcul quotidien à 2h00.

POST /points/redeem

Convertit des points en virement bancaire.

RÈGLE

Minimum 100 points requis (= 9,50€ après conversion)

Requête

JSON

{
  "pointsAmount": 1000,
  "bankAccountId": "bank_acc_123"
}

Réponse 201 Created

JSON

{
  "success": true,
  "data": {
    "withdrawalId": "wdl_abc123",
    "pointsAmount": 1000,
    "euroAmount": 95.00,
    "status": "PENDING",
    "estimatedCompletionDate": "2025-12-15T00:00:00.000Z",
    "bankAccount": {
      "id": "bank_acc_123",
      "iban": "FR76****1234",
      "bankName": "BNP Paribas"
    }
  },
  "message": "Demande de virement enregistrée. Délai : 2-3 semaines."
}

7

ENDPOINTS QR CODES

RÈGLES QR CODE

Validité : 60 secondes
Usage : UNIQUE
Minimum : 10 points
Points bloqués immédiatement

POST /qr-codes/generate

Génère un QR code de paiement pour utiliser des points chez un partenaire.

Requête

JSON

{
  "pointsAmount": 500
}

Réponse 201 Created

JSON

{
  "success": true,
  "data": {
    "qrCodeId": "qr_xyz789abc",
    "qrCodeData": "REWAPP:PAY:qr_xyz789abc:500:52.50:1732443000:sig_hmac_abc123",
    "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "pointsAmount": 500,
    "euroAmount": 52.50,
    "generatedAt": "2025-11-24T10:30:00.000Z",
    "expiresAt": "2025-11-24T10:31:00.000Z",
    "validitySeconds": 60,
    "status": "ACTIVE"
  }
}

GET /qr-codes/:id/status

Vérifie le statut d'un QR code généré.

Statuts possibles :

ACTIVE : QR code valide et en attente de scan
SCANNED : QR code scanné avec succès
EXPIRED : QR code expiré (60s dépassées)
CANCELLED : QR code annulé par l'utilisateur

DELETE /qr-codes/:id

Annule un QR code actif avant son expiration.

GET /qr-codes/history

Liste l'historique des QR codes générés.

POST /qr-codes/scan

Endpoint utilisé par le dashboard partenaire pour scanner et valider un QR code client.

Requête

JSON

{
  "qrCodeData": "REWAPP:PAY:qr_xyz789abc:500:52.50:1732443000:sig_hmac_abc123"
}

Réponse 200 OK

JSON

{
  "success": true,
  "data": {
    "transactionId": "txn_scan_123",
    "qrCodeId": "qr_xyz789abc",
    "pointsDebited": 500,
    "euroAmount": 52.50,
    "customerFirstName": "Jean",
    "customerTier": "GOLD",
    "status": "COMPLETED"
  },
  "message": "Paiement validé avec succès !"
}

Erreurs Possibles

QR_INVALID : QR code invalide ou malformé
QR_EXPIRED : QR code expiré (> 60 secondes)
QR_ALREADY_USED : QR code déjà scanné
QR_SIGNATURE_INVALID : Signature cryptographique invalide

8

ENDPOINTS TRANSACTIONS

GET /transactions

Récupère l'historique des transactions de l'utilisateur.

Query Parameters : page, limit, startDate, endDate, merchantId, status

Réponse 200 OK

JSON

{
  "success": true,
  "data": [
    {
      "id": "txn_abc123",
      "type": "PURCHASE",
      "amount": 85.00,
      "currency": "EUR",
      "merchant": {
        "id": "merchant_123",
        "name": "Restaurant Le Bistrot",
        "category": "RESTAURANT",
        "logo": "https://cdn.rewapp.fr/merchants/bistrot.png"
      },
      "cashback": {
        "rate": 4.0,
        "tierBonus": 10,
        "effectiveRate": 4.4,
        "pointsEarned": 37,
        "euroValue": 3.74
      },
      "status": "COMPLETED",
      "cardLast4": "1234",
      "transactionDate": "2025-11-24T12:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 234,
    "totalPages": 12
  }
}

GET /transactions/:id

Récupère les détails complets d'une transaction.

GET /transactions/stats

Récupère les statistiques de transactions.

Query Parameters : period (WEEK, MONTH, YEAR, ALL)

9

ENDPOINTS PARTENAIRES

GET /partners

Récupère la liste des partenaires actifs (endpoint public).

Query Parameters : page, limit, category, search, lat, lng, radius (mètres)

GET /partners/:id

Récupère les détails d'un partenaire (endpoint public).

GET /partners/search

Recherche des partenaires par nom ou catégorie.

Query Parameters : q (requis), category, limit

GET /partners/nearby

Récupère les partenaires proches d'une position.

Query Parameters : lat (requis), lng (requis), radius (max 50000m), category

GET /partners/categories

Récupère la liste des catégories de partenaires.

10

ENDPOINTS BANCAIRES

GET /banking/cards

Liste les cartes bancaires liées au compte.

POST /banking/cards/link

Initie le processus de liaison d'une nouvelle carte bancaire via OpenBanking.

Requête

JSON

{
  "provider": "BUDGET_INSIGHT",
  "returnUrl": "rewapp://banking/callback"
}

Réponse 200 OK

JSON

{
  "success": true,
  "data": {
    "linkingSessionId": "session_xyz789",
    "authorizationUrl": "https://connect.budget-insight.com/auth?session=xyz789",
    "expiresAt": "2025-11-24T11:30:00.000Z"
  },
  "message": "Veuillez compléter l'authentification bancaire."
}

DELETE /banking/cards/:id

Supprime une carte bancaire liée.

GET /banking/accounts

Liste les comptes bancaires enregistrés pour les virements (IBAN).

POST /banking/accounts

Ajoute un compte bancaire pour les virements.

Requête

JSON

{
  "iban": "FR7630006000011234567890189",
  "holderName": "Jean Dupont",
  "setAsDefault": true
}

DELETE /banking/accounts/:id

Supprime un compte bancaire.

POST /banking/withdrawals

Crée une demande de virement (conversion points → euros).

RÈGLE

Minimum 100 points requis

GET /banking/withdrawals

Liste l'historique des demandes de virement.

DELETE /banking/withdrawals/:id

Annule une demande de virement en attente.

Possible uniquement si status = PENDING

11

ENDPOINTS NOTIFICATIONS

GET /notifications

Récupère les notifications de l'utilisateur.

Query Parameters : page, limit, unreadOnly

Types de Notifications

Type	Description
`POINTS_CREDITED`	Points crédités suite à transaction
`QR_PAYMENT_SUCCESS`	Paiement QR validé
`WITHDRAWAL_COMPLETED`	Virement effectué
`WITHDRAWAL_FAILED`	Virement échoué
`TIER_UPGRADE`	Passage palier supérieur
`POINTS_EXPIRING`	Points bientôt expirés
`PROMOTION`	Offre promotionnelle
`SYSTEM`	Message système

PUT /notifications/:id/read

Marque une notification comme lue.

PUT /notifications/read-all

Marque toutes les notifications comme lues.

DELETE /notifications/:id

Supprime une notification.

POST /notifications/register-device

Enregistre le token FCM pour les notifications push.

Requête

JSON

{
  "deviceToken": "fcm_token_abc123xyz",
  "platform": "IOS",
  "deviceId": "device_xyz789"
}

12

ENDPOINTS DASHBOARD PARTENAIRE

GET /merchant/profile

Récupère le profil du partenaire connecté.

PUT /merchant/profile

Met à jour le profil partenaire.

PUT /merchant/cashback-rate

Configure le taux de cashback du partenaire.

RÈGLE

Taux UNIQUE pour tous les produits (pas de différenciation par catégorie)

Requête

JSON

{
  "cashbackRate": 5.0,
  "tierThresholds": {
    "silver": 500,
    "gold": 1500,
    "platinum": 3000,
    "diamond": 10000
  }
}

GET /merchant/stats

Récupère les statistiques du partenaire.

Query Parameters : period (TODAY, WEEK, MONTH, YEAR), startDate, endDate

POST /merchant/qr-scan

Scanne et valide un QR code client.

GET /merchant/transactions

Liste les transactions du partenaire.

GET /merchant/campaigns

Liste les campagnes promotionnelles du partenaire.

POST /merchant/campaigns

Crée une nouvelle campagne promotionnelle.

FONCTIONNALITÉ PREMIUM

Disponible uniquement pour les partenaires Premium

13

ENDPOINTS ADMINISTRATION

ACCÈS RESTREINT

Tous les endpoints de cette section nécessitent un rôle ADMIN ou SUPER_ADMIN.

GET /admin/users

Liste tous les utilisateurs avec filtres.

Query Parameters : page, limit, search, status, sortBy, order

GET /admin/users/:id

Récupère les détails complets d'un utilisateur.

PUT /admin/users/:id/status

Suspend ou réactive un compte utilisateur.

Requête

JSON

{
  "status": "SUSPENDED",
  "reason": "Activité suspecte détectée",
  "notifyUser": true
}

GET /admin/merchants/pending

Liste les demandes d'inscription partenaire en attente de validation.

RÈGLE

Validation manuelle OBLIGATOIRE avant activation

PUT /admin/merchants/:id/approve

Approuve une demande d'inscription partenaire.

PUT /admin/merchants/:id/reject

Rejette une demande d'inscription partenaire.

GET /admin/transactions

Liste toutes les transactions du système.

Query Parameters : page, limit, userId, merchantId, type, status, minAmount, maxAmount, flagged

GET /admin/withdrawals

Liste toutes les demandes de virement.

PUT /admin/withdrawals/:id/process

Approuve ou rejette une demande de virement.

Requête

JSON

{
  "action": "APPROVE",
  "notes": "Vérification effectuée"
}

GET /admin/stats/dashboard

Récupère les indicateurs clés pour le dashboard admin.

GET /admin/audit-logs

Récupère les logs d'audit des actions administratives.

14

SCHÉMAS DE DONNÉES

Cette section décrit les schémas de données utilisés par l'API (Components/Schemas OpenAPI).

User

Schéma utilisateur

Attribut	Type	Contraintes
`id`	`UUID`	format: uuid
`email`	`string`	format: email
`firstName`	`string`	2-50 caractères
`lastName`	`string`	2-50 caractères
`phoneNumber`	`string`	pattern: E.164
`status`	`enum`	PENDING_VERIFICATION, ACTIVE, SUSPENDED, DELETED
`role`	`enum`	USER, MERCHANT, ADMIN, SUPER_ADMIN

PointsBalance

Solde de points

Attribut	Type	Description
`available`	`integer`	Points disponibles
`pending`	`integer`	Points en attente de validation
`blocked`	`integer`	Points bloqués (QR actif ou virement)
`total`	`integer`	Total des points

Transaction

Transaction de paiement

Attribut	Type	Valeurs
`type`	`enum`	PURCHASE, QR_PAYMENT, WITHDRAWAL, REFUND, BONUS
`amount`	`decimal`	Montant en euros
`status`	`enum`	PENDING, PROCESSING, COMPLETED, CANCELLED, FAILED

QRCode

QR Code de paiement

Attribut	Type	Contraintes
`qrCodeId`	`string`	Identifiant unique
`pointsAmount`	`integer`	minimum: 10
`status`	`enum`	ACTIVE, SCANNED, EXPIRED, CANCELLED
`validitySeconds`	`integer`	default: 60

Merchant

Partenaire commercial

Attribut	Type	Contraintes
`cashbackRate`	`number`	min: 1, max: 20
`status`	`enum`	PENDING, APPROVED, REJECTED, SUSPENDED, INACTIVE

Withdrawal

Demande de virement

Attribut	Type	Contraintes
`pointsAmount`	`integer`	minimum: 100
`conversionRate`	`number`	default: 0.095
`status`	`enum`	PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED

15

CODES D'ERREUR ET RÉPONSES

15.1 Codes HTTP Standardisés

Codes HTTP

Code	Signification	Utilisation
200	OK	GET, PUT, PATCH réussis
201	Created	POST création réussie
204	No Content	DELETE réussi
400	Bad Request	Validation échouée
401	Unauthorized	Token manquant/expiré
403	Forbidden	Permissions insuffisantes
404	Not Found	Ressource introuvable
409	Conflict	Email déjà utilisé
422	Unprocessable Entity	Erreur métier (solde insuffisant)
429	Too Many Requests	Rate limit dépassé
500	Internal Server Error	Bug interne

15.2 Codes d'Erreur Métier

Authentification (AUTH_)

Code	Message	HTTP
`AUTH_INVALID_CREDENTIALS`	Email ou mot de passe incorrect	401
`AUTH_ACCOUNT_LOCKED`	Compte verrouillé (trop de tentatives)	423
`AUTH_TOKEN_EXPIRED`	Token JWT expiré	401
`AUTH_TOKEN_INVALID`	Token JWT invalide	401

Points (POINTS_)

Code	Message	HTTP
`POINTS_INSUFFICIENT_BALANCE`	Solde de points insuffisant	422
`POINTS_AMOUNT_TOO_LOW`	Montant inférieur au minimum	422
`POINTS_EXPIRED`	Points expirés	410
`POINTS_BLOCKED`	Points bloqués (opération en cours)	409

QR Code (QR_)

Code	Message	HTTP
`QR_INVALID`	QR code invalide ou malformé	400
`QR_EXPIRED`	QR code expiré (> 60 secondes)	410
`QR_ALREADY_USED`	QR code déjà scanné	409
`QR_SIGNATURE_INVALID`	Signature cryptographique invalide	400

Bancaire (BANK_)

Code	Message	HTTP
`BANK_CARD_LINKING_FAILED`	Liaison carte échouée	422
`BANK_IBAN_INVALID`	IBAN invalide	400
`BANK_WITHDRAWAL_MINIMUM`	Minimum 100 points non atteint	422

15.3 Format des Réponses d'Erreur

JSON

{
  "success": false,
  "error": {
    "code": "POINTS_INSUFFICIENT_BALANCE",
    "message": "Solde de points insuffisant. Vous avez 450 points, 500 requis.",
    "details": [
      {
        "field": "pointsAmount",
        "issue": "exceeds_available",
        "available": 450,
        "requested": 500
      }
    ],
    "timestamp": "2025-11-24T10:30:00.000Z",
    "traceId": "trace_abc123def456",
    "path": "/api/v1/qr-codes/generate"
  }
}

16

RATE LIMITING ET QUOTAS

16.1 Limites par Endpoint

Limites de Taux

Endpoint	Limite	Période	Action si dépassé
`/auth/login`	5 requêtes	15 min	Block IP + notification sécurité
`/auth/register`	3 requêtes	1 heure	Block IP
`/auth/forgot-password`	3 requêtes	1 heure	Block email
`/qr-codes/generate`	10 requêtes	1 min	Throttle 429
`/points/*`	100 requêtes	1 min	Throttle 429
`/banking/withdrawals`	5 requêtes	1 heure	Throttle 429
Général (authentifié)	1000 requêtes	1 min	Throttle 429
Général (non-auth)	100 requêtes	1 min	Block temporaire

16.2 Headers de Rate Limiting

Les réponses incluent des headers informatifs :

HTTP Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1732443060
Retry-After: 30

16.3 Réponse 429 Too Many Requests

JSON

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Trop de requêtes. Veuillez réessayer dans 30 secondes.",
    "retryAfter": 30,
    "limit": 1000,
    "period": "1 minute"
  }
}

17

WEBHOOKS

17.1 Événements Disponibles

Liste des Événements

Événement	Description
`transaction.created`	Nouvelle transaction détectée
`transaction.completed`	Transaction validée, points crédités
`points.credited`	Points crédités au compte
`points.debited`	Points débités (QR ou virement)
`withdrawal.requested`	Nouvelle demande de virement
`withdrawal.completed`	Virement effectué
`withdrawal.failed`	Virement échoué
`qr_code.scanned`	QR code scanné avec succès
`merchant.approved`	Partenaire validé
`user.registered`	Nouvel utilisateur inscrit

17.2 Format des Webhooks

JSON

{
  "id": "evt_abc123def456",
  "type": "transaction.completed",
  "apiVersion": "2025-11-01",
  "createdAt": "2025-11-24T10:30:00.000Z",
  "data": {
    "object": {
      "id": "txn_abc123",
      "type": "PURCHASE",
      "amount": 85.00,
      "pointsEarned": 37
    }
  },
  "signature": "sha256=abc123..."
}

17.3 Vérification de Signature

Tous les webhooks sont signés avec HMAC-SHA256. Vérifiez la signature avec votre webhook secret :

Pseudo-code

signature = HMAC-SHA256(webhook_secret, request_body)
header_signature = request.headers['X-REWAPP-Signature']
valid = compare_signatures(signature, header_signature)

17.4 Politique de Retry

Tentatives de Renvoi

Tentative	Délai	Comportement
1	Immédiat	Premier envoi
2	1 minute	Retry automatique
3	5 minutes	Retry automatique
4	30 minutes	Retry automatique
5	2 heures	Retry automatique
6+	-	Dead Letter Queue + alerte admin

18

BONNES PRATIQUES

18.1 Authentification

Stockez l'access token en mémoire uniquement (pas de localStorage)
Utilisez le refresh token pour renouveler silencieusement
Implémentez la déconnexion automatique après inactivité
Activez l'authentification biométrique quand disponible

18.2 Gestion des Erreurs

Toujours vérifier le champ "success" de la réponse
Afficher des messages d'erreur utilisateur-friendly
Logger les erreurs avec le traceId pour le support
Implémenter des retry avec exponential backoff (500ms, 1s, 2s)

18.3 Performance

Utilisez la pagination pour les listes
Cachez les données statiques (catégories, partenaires)
Implémentez un debounce sur les recherches (300ms)
Préchargez les données critiques au démarrage

18.4 Sécurité

Ne jamais logger les tokens ou données sensibles
Validez les entrées côté client ET serveur
Utilisez HTTPS exclusivement
Implémentez le certificate pinning sur mobile

18.5 Gestion du QR Code

Afficher un compteur visuel clair (60s)
Bloquer l'écran de veille pendant l'affichage du QR
Permettre l'annulation facile
Confirmer visuellement le succès du scan