API Parrainage - Loyalty
Points de terminaison pour gérer les programmes de parrainage - validation des codes, suivi des statistiques et application des parrainages pour l'API Loyalty.
/api/v1/loyalty/referrals/
Flux de Parrainage
Voici comment fonctionne le système de parrainage :
Le Parrain Partage le Code
Un membre existant partage son code de parrainage unique avec des amis.
Valider le Code
Lorsqu'un nouvel utilisateur saisit un code, validez-le en utilisant /referrals/validate-code.
Appliquer le Parrainage
Après l'inscription du nouvel utilisateur, appliquez le parrainage via /referrals/apply.
Points Bonus Attribués
Le parrain et le filleul reçoivent tous deux leurs points bonus configurés.
Obtenir les Statistiques de Parrainage
/api/v1/loyalty/cards/{card_id}/referral-stats
Obtenir les statistiques de parrainage pour une carte, y compris les parrainages totaux, réussis et en attente.
Cas d'Usage
- Afficher les métriques du programme de parrainage sur un tableau de bord
- Suivre l'efficacité des campagnes
- Surveiller les tendances de parrainage au fil du temps
Réponse
{
"success": true,
"data": {
"stats": {
"total_referrals": 150,
"successful_referrals": 120,
"pending_referrals": 30,
"conversion_rate": 80.0
},
"period": "30d"
}
}Lister les Meilleurs Parrains
/api/v1/loyalty/cards/{card_id}/referrers
Obtenir la liste des meilleurs parrains pour une carte, triée par parrainages réussis.
Cas d'Usage
- Créer un classement de parrainage
- Identifier les ambassadeurs de la marque
- Récompenser les plus performants
Paramètres de Requête
limit=10
period=30d
limit (integer, optionnel) - Nombre de résultats (défaut: 10)
period (string, optionnel) - Période: 7d, 30d, 90d, all
Réponse
{
"success": true,
"data": {
"referrers": [
{
"member_id": 123,
"name": "Ahmed Ben Ali",
"email": "ahmed@example.com",
"total_referrals": 25,
"successful_referrals": 22
}
],
"total": 10
}
}Obtenir les Parrainages du Parrain
/api/v1/loyalty/cards/{card_id}/referrers/{member_id}/referrals
Obtenir tous les parrainages effectués par un membre spécifique.
Paramètres d'URL :
card_id (entier, requis) - L'ID de la carte
member_id (entier, requis) - L'ID du membre parrain
Réponse
{
"success": true,
"data": {
"referrals": [
{
"id": 1001,
"referee_name": "Fatmi Tarek",
"referee_email": "fatmi@example.com",
"status": "completed",
"bonus_points": 50,
"created_at": "2025-01-15T10:30:00Z"
}
],
"total": 22
}
}Valider le Code de Parrainage
/api/v1/loyalty/referrals/validate-code
Vérifier si un code de parrainage est valide pour une carte spécifique.
Valider Avant d'Appliquer
Validez toujours les codes avant de les appliquer pour fournir un retour immédiat aux utilisateurs.
Corps de la Requête
{
"referral_code": "AHMED2024",
"card_id": 5
}
referral_code (string, requis) - Code de parrainage à valider
card_id (integer, requis) - ID de la carte
Réponse
{
"success": true,
"data": {
"is_valid": true,
"referrer": {
"id": 123,
"name": "Ahmed Ben Ali",
"bonus_info": {
"referrer_bonus": 50,
"referee_bonus": 25
}
}
}
}Appliquer le Parrainage
/api/v1/loyalty/referrals/apply
Appliquer un code de parrainage à un nouveau membre et attribuer des points bonus aux deux parties.
Application Unique
Les parrainages ne peuvent être appliqués qu'une seule fois par membre. Les tentatives ultérieures renverront une erreur.
Corps de la Requête
{
"referral_code": "AHMED2024",
"card_id": 5,
"referee_member_id": 456
}
referral_code (string, requis) - Code de parrainage
card_id (integer, requis) - ID de la carte
referee_member_id (integer, requis) - ID du nouveau membre
Réponse
{
"success": true,
"message": "Parrainage appliqué avec succès",
"data": {
"referral": {
"id": 1001,
"referrer_id": 123,
"referee_id": 456,
"referrer_bonus": 50,
"referee_bonus": 25,
"created_at": "2025-01-20T14:30:00Z"
}
}
}