Documentation Fidelioo

Bienvenue dans la documentation officielle de Fidelioo, la plateforme N°1 pour fidéliser, engager et récompenser vos clients en Afrique de l'Ouest.

La plateforme Fidelioo

Fidelioo est une plateforme SaaS multi-tenant de gestion de la fidélité client. Elle permet aux commerces et entreprises (appelés Partenaires) de créer et gérer des programmes de fidélité digitaux accessibles à leurs clients (appelés Membres) via une application mobile ou un portail web.

Architecture générale

La plateforme repose sur une hiérarchie à quatre niveaux :

Plans d'abonnement

Fidelioo propose plusieurs plans adaptés à la taille de votre entreprise :

Partenaires

Un Partenaire est une entité commerciale (restaurant, salon de coiffure, boutique, chaîne de magasins, etc.) qui utilise Fidelioo pour fidéliser ses clients. Chaque partenaire dispose d'un espace de gestion dédié accessible sur fidelioo.co/fr-fr/partner.

Inscription d'un partenaire

L'inscription se fait en deux étapes :

1. Remplissage du formulaire d'inscription avec les informations de l'entreprise (nom, secteur, numéro de téléphone)
2. Vérification OTP par SMS — un code à 6 chiffres est envoyé sur le numéro renseigné

Une fois l'inscription validée, un abonnement d'essai gratuit de 3 jours est automatiquement créé, et un email de bienvenue est envoyé au partenaire.

Tableau de bord partenaire

Le tableau de bord offre une vue d'ensemble des indicateurs clés :

• Nombre total de membres inscrits
• Points distribués et échangés sur la période
• Tampons validés (pour les cartes tampons)
• Bons de réduction actifs et utilisés
• Activité récente (transactions, inscriptions)

Paiement des abonnements

Les abonnements sont réglés via Feexpay, la solution de paiement Mobile Money leader en Afrique de l'Ouest. Les opérateurs acceptés sont :

• MTN Mobile Money
• Moov Africa
• Orange Money

Le paiement est sécurisé et confirmé instantanément par webhook. L'abonnement est activé dès réception de la confirmation de paiement.

Clubs

Un Club représente un programme de fidélité au sein d'une enseigne partenaire. Un partenaire peut créer plusieurs clubs (selon son plan d'abonnement), par exemple un club pour chaque point de vente ou pour chaque type de clientèle.

Structure d'un club

Cartes associées à un club

Chaque club peut contenir plusieurs types de cartes :

• Carte de fidélité — Système de points avec niveaux et récompenses
• Carte tampon — Système de punch card digital (X tampons = 1 récompense)
• Bon de réduction — Codes promo et offres spéciales

Rôles utilisateurs

Fidelioo définit quatre rôles distincts avec des niveaux d'accès différents :

Permissions granulaires du Staff

Les membres du staff peuvent se voir attribuer des permissions spécifiques par le partenaire :

• scan_stamps — Autorisation de scanner et valider des tampons
• add_points — Autorisation d'ajouter des points manuellement
• redeem_rewards — Autorisation de traiter les échanges de récompenses
• validate_coupons — Autorisation de valider les bons de réduction
• view_members — Autorisation de consulter la liste des membres

Authentification — Vue d'ensemble

Fidelioo utilise un système d'authentification sans mot de passe (passwordless) basé sur des codes OTP (One-Time Password) envoyés par SMS. Cette approche garantit une meilleure sécurité et simplifie l'expérience utilisateur, particulièrement dans un contexte où les SMS sont le principal canal de communication digital.

Chaque type d'utilisateur dispose de son propre flux d'authentification et de son guard Laravel dédié, assurant une isolation complète des sessions et des données.

Système OTP

Le flux OTP de Fidelioo fonctionne en deux appels API distincts :

Étape 1 — Demande de code OTP

POST /api/fr-fr/v1/partner/auth/send-otp
Content-Type: application/json

{
  "phone": "+22961000000"
}

Un code OTP à 6 chiffres est envoyé par SMS au numéro renseigné. Le code est valide pendant 10 minutes. Après 3 tentatives échouées, le compte est temporairement bloqué pendant 15 minutes.

Étape 2 — Vérification et authentification

POST /api/fr-fr/v1/partner/auth/verify-otp
Content-Type: application/json

{
  "phone": "+22961000000",
  "otp": "482917"
}

{
  "success": true,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "partner": {
    "id": 42,
    "name": "Boulangerie Central",
    "phone": "+22961000000",
    "subscription_status": "active",
    "plan": "business"
  }
}

Sécurité OTP

• Les codes OTP sont générés de manière cryptographiquement aléatoire
• Chaque code est à usage unique et invalidé dès sa première utilisation
• Les codes expirent automatiquement après 10 minutes
• Le nombre de tentatives est limité à 3 par tranche de 15 minutes

Membres anonymes

Fidelioo supporte les membres anonymes, permettant à un client d'accumuler des points ou des tampons sans avoir à créer un compte complet dès le départ. Cette fonctionnalité est particulièrement utile pour réduire les frictions lors du premier achat.

Fonctionnement

Un membre anonyme est identifié uniquement par son numéro de téléphone. Il peut :

• Recevoir des points de fidélité attribués par le staff
• Accumuler des tampons
• Recevoir des bons de réduction

Lorsque le membre souhaite consulter son solde ou échanger ses récompenses, il lui suffit de vérifier son numéro de téléphone via OTP pour accéder à son compte.

Cartes de fidélité — Vue d'ensemble

Le système de cartes de fidélité de Fidelioo permet aux partenaires de récompenser leurs clients avec des points à chaque achat. Ces points peuvent être échangés contre des récompenses (remises, produits gratuits, services) selon des règles définies par le partenaire.

Caractéristiques principales

• Taux d'accumulation flexible — Définissez le nombre de points par montant dépensé (ex. : 1 point pour 100 XOF)
• Niveaux de fidélité — Argent, Or, Platine avec avantages progressifs
• Récompenses multiples — Créez autant de récompenses que vous souhaitez
• Expiration des points — Configurez une durée de validité optionnelle
• Double validation — L'échange de récompense est validé par un code PIN membre

Cycle de vie d'un point

Créer une carte de fidélité

La création d'une carte de fidélité se fait depuis le tableau de bord partenaire, rubrique Cartes → Nouvelle carte → Carte de fidélité.

Paramètres de base

Exemple de configuration

{
  "name": "Carte Fidélité Premium",
  "description": "Gagnez des points à chaque achat et échangez-les contre des réductions",
  "color": "#2563eb",
  "points_per_unit": 1,
  "unit_type": "amount",
  "unit_value": 500,
  "points_expiry_days": 365,
  "club_id": 12
}

Avec cette configuration, le client gagne 1 point pour chaque tranche de 500 XOF dépensée. Un achat de 2 500 XOF rapporte donc 5 points.

Récompenses

Les récompenses sont les avantages que les membres peuvent obtenir en échangeant leurs points. Chaque carte de fidélité peut comporter un nombre illimité de récompenses.

Types de récompenses

Paramètres d'une récompense

{
  "card_id": 5,
  "name": "Café offert",
  "description": "Un café de votre choix offert",
  "type": "free_product",
  "points_required": 50,
  "is_active": true,
  "stock": null,
  "max_per_member": 1,
  "valid_from": null,
  "valid_until": "2026-12-31"
}

Niveaux de fidélité

Les niveaux de fidélité permettent de segmenter les membres selon leur engagement et de leur offrir des avantages progressifs. Plus un membre accumule de points, plus il monte en niveau et bénéficie de meilleures conditions.

Configuration des niveaux

Le multiplicateur de niveau s'applique automatiquement lors de l'attribution des points. Un membre Or qui effectue un achat de 1 000 XOF recevra le double des points habituels.

Attribuer des points

Les points peuvent être attribués de plusieurs manières :

1. Attribution automatique (recommandée)

Le staff entre le montant de l'achat dans l'interface Fidelioo, et les points sont calculés et crédités automatiquement selon la règle de la carte.

Montant de l'achat : 3 500 XOF
Règle de la carte : 1 point par 500 XOF
Points calculés : 7 points
Niveau membre : Or (multiplicateur x2)
Points crédités : 14 points

2. Attribution manuelle

Le partenaire ou le staff peut attribuer un nombre de points précis manuellement, par exemple pour compenser une réclamation ou récompenser un comportement spécifique (parrainage, avis laissé, etc.).

3. Attribution via API

Pour les intégrations avec des systèmes de caisse ou des plateformes e-commerce, Fidelioo propose une API REST et une Agent API permettant d'attribuer des points programmatiquement.

curl -X POST https://fidelioo.co/api/fr-fr/v1/staff/members/points \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": 123,
    "card_id": 5,
    "amount": 3500,
    "note": "Achat en caisse #4892"
  }'

Traiter les échanges

Lorsqu'un membre souhaite utiliser ses points pour obtenir une récompense, le staff doit valider l'échange en suivant ce processus :

1. Le membre sélectionne la récompense souhaitée dans son application
2. Un QR code de demande d'échange est généré
3. Le staff scanne le QR code ou saisit le code d'échange
4. Le membre confirme avec son PIN à 4 chiffres
5. Les points sont débités et la récompense est accordée
6. Un reçu de transaction est généré pour les deux parties

Cartes tampons — Vue d'ensemble

La carte tampon digitale (ou punch card) est une version numérique du traditionnel carnet à tamponner. Après un nombre défini de tampons collectés, le membre reçoit automatiquement une récompense.

C'est la solution idéale pour les commerces qui souhaitent encourager les visites répétées : cafés, restaurants, coiffeurs, boulangeries, laveries, etc.

Avantages par rapport à la carte physique

• Pas de risque de perte ou d'oubli de la carte physique
• Impossible à falsifier (validation par QR code sécurisé)
• Historique complet des tampons consultable à tout moment
• Notification push automatique à chaque tampon validé
• Récompense accordée instantanément à l'atteinte du seuil

Créer un programme tampon

La création d'un programme tampon se fait depuis Cartes → Nouvelle carte → Carte tampon.

Programme : "10ème café offert"
stamps_required: 10
reward_description: "Votre café au choix offert"
stamps_per_visit: 1
reset_after_reward: true
expiry_days: 90

Scanner les tampons

La validation des tampons se fait via l'application staff de Fidelioo ou via l'interface web staff.

Processus de validation

1. Le membre présente son QR code personnel (disponible dans l'app)
2. Le staff scanne le QR code avec l'application staff
3. L'application confirme l'identité du membre et affiche son compteur actuel
4. Le staff valide le tampon (un seul clic)
5. Le membre reçoit une notification instantanée
6. Si le seuil est atteint, la récompense est accordée automatiquement

Bons de réduction — Vue d'ensemble

Les bons de réduction (coupons) permettent aux partenaires de créer et distribuer des codes promotionnels à leurs membres. Ils peuvent être utilisés en complément des cartes de fidélité ou de manière totalement indépendante.

Cas d'usage

• Offre de bienvenue pour les nouveaux membres
• Promotion saisonnière (Noël, Fête des Mères, etc.)
• Récompense de parrainage
• Récupération de clients inactifs
• Promotion d'un nouveau produit ou service
• Célébration de l'anniversaire d'un membre

Types de réduction

Conditions d'utilisation

Chaque bon peut être soumis à des conditions :

• min_purchase — Montant minimum d'achat requis
• max_discount — Plafond de réduction (pour les bons en %)
• valid_from / valid_until — Période de validité
• max_uses — Nombre maximum d'utilisations total
• max_uses_per_member — Nombre maximum par membre
• applicable_products — Restriction à certains produits/catégories

Génération en masse

Fidelioo permet de générer des lots de bons de réduction avec des codes uniques pour chaque destinataire. Cette fonctionnalité est idéale pour les campagnes marketing à grande échelle.

Configuration de la génération en masse

{
  "campaign_name": "Promo Fête Nationale 2026",
  "type": "percent",
  "value": 15,
  "quantity": 500,
  "code_prefix": "BENIN26",
  "code_length": 8,
  "min_purchase": 5000,
  "valid_from": "2026-08-01",
  "valid_until": "2026-08-31",
  "max_uses_per_member": 1,
  "distribution": "sms"
}

Fidelioo génère 500 codes uniques de la forme BENIN26XXXXXXXX et peut les envoyer directement par SMS aux membres ciblés.

Formats d'export

Les codes générés peuvent être exportés en :

• CSV — Pour import dans un CRM ou tableur
• PDF — Pour impression ou envoi par email
• Distribution SMS directe — Envoi automatique aux membres ciblés

Ciblage avancé

Le moteur de ciblage de Fidelioo permet d'envoyer des bons aux segments de membres les plus pertinents, maximisant ainsi l'impact de chaque campagne.

Critères de ciblage disponibles

Membres — Vue d'ensemble

Les Membres sont les clients finaux qui bénéficient des programmes de fidélité créés par les Partenaires. Ils interagissent avec la plateforme principalement via l'application mobile Fidelioo ou le portail web membre.

Profil d'un membre

Un membre peut être inscrit à plusieurs clubs (de différents partenaires) avec un seul et même compte Fidelioo, identifié par son numéro de téléphone.

Gestion des membres

Le partenaire dispose d'une interface complète pour gérer ses membres depuis le tableau de bord.

Actions disponibles

• Inscription manuelle — Ajouter un membre directement depuis le back-office (sans OTP)
• Ajustement de points — Ajouter ou déduire des points avec une note justificative
• Changement de niveau — Modifier manuellement le niveau de fidélité
• Blocage / Déblocage — Suspendre l'accès d'un membre
• Fusion de comptes — Fusionner deux profils en double
• Export CSV — Exporter la liste complète des membres avec leurs statistiques

Import en masse

Vous pouvez importer une liste de membres existants via un fichier CSV. Le format attendu est :

phone,first_name,last_name,email,birth_date,points
+22961000001,Kouassi,Attiogbe,k.attiogbe@email.com,1990-05-15,250
+22961000002,Aïcha,Dembélé,,1985-11-22,0
+22961000003,Jean-Baptiste,Hounkpatin,jb@email.com,,150

Statistiques par membre

Pour chaque membre, Fidelioo fournit un tableau de bord détaillé :

• Solde de points actuel et historique
• Niveau de fidélité et progression vers le niveau suivant
• Liste complète des transactions (points gagnés et échangés)
• Tampons collectés et récompenses obtenues
• Bons de réduction utilisés
• Date de première inscription et dernière activité
• Valeur totale des achats enregistrés