API Points - Loyalty
Points de terminaison pour gagner, échanger et gérer les points de fidélité pour l'API Loyalty.
/api/v1/loyalty/points/
Gagner des Points
/api/v1/loyalty/points/earn
Attribuer des points à un membre basé sur un montant d'achat. Supporte l'identification par member_id, email ou téléphone. Crée automatiquement les membres si nécessaire.
Comment ça Marche
Configuration de la Carte
La carte de points a un ratio de points configuré (ex: 1 point par 10€ dépensés).
Envoyer la Transaction
Envoyez card_id, identifiant du membre et purchase_amount pour calculer les points.
Créditer les Points
Les points sont automatiquement crédités sur le solde du membre.
Corps de la Requête
{
"card_id": 10,
"member_id": 123,
"purchase_amount": 50.00,
"reference": "ORDER-12345"
}
card_id (integer, requis) - ID de la carte de points
member_id (integer, conditionnel) - ID du membre
email (string, conditionnel) - Email du membre (alternative à member_id)
phone (string, conditionnel) - Téléphone du membre (alternative à member_id)
member_name (string, optionnel) - Nom pour auto-création de membre
purchase_amount (number, requis) - Montant de l'achat
reference (string, optionnel) - Référence de transaction externe
Réponse
{
"success": true,
"data": {
"transaction_id": 456,
"points_earned": 50,
"new_balance": 150,
"member_id": 123,
"card_id": 10,
"is_new_member": false,
"notification_sent": "points_earned",
"reference": "ORDER-12345",
"earned_at": "2025-01-15T10:30:00Z"
}
}Échanger des Points
/api/v1/loyalty/points/redeem
Échanger des points contre une récompense. Le membre doit avoir suffisamment de points pour la récompense demandée.
X-Member-Token pour protéger les points du membre.
En-têtes
X-App-Id: app_abc123...
X-Api-Key: test_xyz789...
X-Member-Token: eyJ0eXAiOiJKV1QiLCJhbGc...Corps de la Requête
{
"card_id": 10,
"reward_id": 5,
"reference": "REDEEM-12345"
}
card_id (integer, requis) - ID de la carte de points
reward_id (integer, requis) - ID de la récompense à échanger
reference (string, optionnel) - Référence externe
Réponse
{
"success": true,
"data": {
"transaction_id": 457,
"reward_id": 5,
"reward_name": "Café Gratuit",
"points_redeemed": 100,
"new_balance": 50,
"member_id": 123,
"card_id": 10,
"reference": "REDEEM-12345",
"redeemed_at": "2025-01-15T11:00:00Z"
}
}Rembourser des Points
/api/v1/loyalty/points/refund
Annuler/déduire des points précédemment gagnés lors d'un remboursement de commande. Utilisez quand une commande est remboursée pour retirer les points correspondants.
Corps de la Requête
{
"card_id": 10,
"member_id": 123,
"refund_amount": 25.00,
"reference": "REFUND-ORDER-12345"
}
card_id (integer, requis) - ID de la carte de points
member_id (integer, conditionnel) - ID du membre
email (string, conditionnel) - Email du membre (alternative à member_id)
phone (string, conditionnel) - Téléphone du membre (alternative à member_id)
refund_amount (number, requis) - Montant remboursé
points_to_deduct (integer, optionnel) - Points explicites à déduire
reference (string, optionnel) - Référence de transaction
Réponse
{
"success": true,
"data": {
"transaction_id": 458,
"points_deducted": 25,
"refund_amount": 25.00,
"previous_balance": 150,
"new_balance": 125,
"member_id": 123,
"card_id": 10,
"reference": "REFUND-ORDER-12345",
"balance_warning": null,
"refunded_at": "2025-01-15T12:00:00Z"
}
}Solde de Points
/api/v1/loyalty/points/balance
Récupérer le solde de points actuel d'un membre sur une carte spécifique.
Paramètres de Requête
GET /api/v1/loyalty/points/balance?card_id=10&member_id=123
card_id (integer, requis) - ID de la carte de points
member_id (integer, requis) - ID du membre
Réponse
{
"success": true,
"data": {
"card_id": 10,
"member_id": 123,
"points_balance": 150,
"reward_system": "points",
"queried_at": "2025-01-15T10:30:00Z"
}
}Historique des Points
/api/v1/loyalty/points/history
Récupérer l'historique des transactions de points d'un membre avec pagination.
Paramètres de Requête
GET /api/v1/loyalty/points/history?card_id=10&member_id=123&limit=20&offset=0
card_id (integer, requis) - ID de la carte
member_id (integer, requis) - ID du membre
limit (integer, optionnel) - Nombre de résultats (défaut: 20, max: 100)
offset (integer, optionnel) - Décalage pour pagination
Réponse
{
"success": true,
"data": {
"card_id": 10,
"member_id": 123,
"transactions": [
{
"id": 456,
"points": 50,
"event": "staff_added_points",
"created_at": "2025-01-15T10:30:00Z"
},
{
"id": 457,
"points": -100,
"event": "staff_redeemed_reward",
"created_at": "2025-01-15T11:00:00Z"
}
],
"pagination": {
"limit": 20,
"offset": 0,
"total": 45,
"has_more": true
}
}
}