Documentation API Fidoren

L'API Fidoren v1 permet d'intégrer la gestion de fidélité à vos applications.

URL de base : https://votre-domaine.com/api/v1/

Formats supportés

Requêtes : application/json
Réponses : application/json

Authentification

L'API supporte deux méthodes d'authentification :

1. API Key (recommandé pour les intégrations)

Utilisez votre clé API et secret dans le header Authorization :

// Format
Authorization: ApiKey <api_key>:<api_secret>

// Exemple
Authorization: ApiKey lf_a1b2c3d4e5f6g7h8:secret123abc456def789...
            

2. JWT (pour les applications mobiles)

Obtenez un token via /api/v1/auth/login/ puis utilisez-le :

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Important : Ne partagez jamais votre secret API. Utilisez des variables d'environnement côté serveur.

Rate Limits

Les limites par défaut pour les clés API sont :

Limite	Valeur par défaut
Requêtes par heure	1 000
Requêtes par jour	10 000

Les headers de réponse incluent les informations de rate limit :

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1234567890
            

Gestion des erreurs

L'API utilise les codes HTTP standards :

Code	Description
`200`	Succès
`201`	Ressource créée
`400`	Requête invalide
`401`	Non authentifié
`403`	Permission refusée
`404`	Ressource non trouvée
`429`	Trop de requêtes (rate limit)
`500`	Erreur serveur

Format des erreurs :

{
  "success": false,
  "error": "Description de l'erreur",
  "code": "ERROR_CODE"
}
            

Endpoints Auth

POST /api/v1/auth/login/

Authentification et obtention d'un token JWT.

// Request
{
  "username": "user@example.com",
  "password": "secret123"
}

// Response 200
{
  "access_token": "eyJhbGci...",
  "refresh_token": "eyJhbGci...",
  "user": { ... }
}
              

POST /api/v1/auth/refresh/

Renouvellement du token d'accès.

GET /api/v1/auth/me/

Informations sur l'utilisateur connecté.

Endpoints Loyalty

POST /api/v1/loyalty/stamps/add/

Ajouter des tampons à un client.

// Request
{
  "store_id": 1,
  "customer_id": 42,
  "stamps": 1,
  "amount": 15.50  // optionnel
}

// Response 200
{
  "success": true,
  "stamps_added": 1,
  "new_balance": 8,
  "stamps_for_reward": 10,
  "reward_available": false
}
              

POST /api/v1/loyalty/points/add/

Ajouter des points à un client.

// Request
{
  "store_id": 1,
  "customer_id": 42,
  "points": 100,
  "reason": "Achat en magasin"
}
              

POST /api/v1/loyalty/scan/

Scanner le QR code d'un client.

// Request
{
  "qr_code": "uuid-du-client",
  "store_id": 1
}

// Response 200
{
  "customer": {
    "id": 42,
    "name": "Marie Dupont",
    "email": "marie@example.com"
  },
  "loyalty": {
    "stamps": 7,
    "points": 145,
    "rewards_available": 1
  }
}
              

POST /api/v1/loyalty/redeem/

Échanger une récompense.

GET /api/v1/loyalty/balance/

Consulter le solde fidélité d'un client.

Endpoints Stores

GET /api/v1/stores/

Liste des stores publics.

GET /api/v1/stores/{id}/

Détails d'un store.

GET /api/v1/stores/{id}/products/

Catalogue produits d'un store.

GET /api/v1/stores/{id}/rewards/

Récompenses disponibles d'un store.

Endpoints Merchant

GET /api/v1/merchant/stores/

Liste des stores du marchand connecté.

GET /api/v1/merchant/stats/

Statistiques globales du marchand.

GET /api/v1/merchant/customers/

Liste des clients du marchand.

Endpoints Customers

GET /api/v1/customers/profile/

Profil du client connecté.

GET /api/v1/customers/enrollments/

Inscriptions fidélité du client.

GET /api/v1/customers/transactions/

Historique des transactions du client.

Fidélisation

Marketing

Pilotage