Fidelioo
api.fidelioo.co

API REST Fidelioo

Référence complète de l'API REST Fidelioo. Intégrez la fidélité client dans vos applications, systèmes de caisse et plateformes e-commerce.

URL de base
https://fidelioo.co/api/{locale}/v1
Remplacez {locale} par le code de langue souhaité : fr-fr, en-us, etc.

Conventions générales

PropriétéValeur
FormatJSON (Content-Type: application/json)
EncodageUTF-8
AuthentificationBearer Token (Authorization: Bearer {token})
PaginationParamètres page et per_page (défaut : 20)
DatesFormat ISO 8601 : YYYY-MM-DDTHH:MM:SSZ
Fuseaux horairesAfrica/Porto-Novo (UTC+1) par défaut

Structure de réponse standard

JSON — Succès
{
  "success": true,
  "data": { ... },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 98
  }
}
JSON — Erreur
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Le champ téléphone est requis.",
    "details": {
      "phone": ["Le champ téléphone est requis."]
    }
  }
}

Authentification — Token Bearer

L'API REST Fidelioo utilise des tokens Bearer pour authentifier les requêtes. Le token doit être inclus dans le header HTTP Authorization de chaque requête protégée.

HTTP Header
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2ZpZGVsaW9vLmNvIiwic3ViIjo0MiwiaWF0IjoxNzQwMDAwMDAwLCJleHAiOjE3NDAzNjAwMDB9.xxxxx

Durée de validité des tokens

Type d'utilisateurDuréeRenouvellement
Admin24 heuresVia POST /admin/auth/refresh
Partenaire7 joursVia POST /partner/auth/refresh
Staff12 heuresVia POST /staff/auth/refresh
Membre30 joursVia POST /member/auth/refresh
Sécurité : Ne stockez jamais vos tokens dans le code source ou dans des dépôts publics. Utilisez des variables d'environnement et des coffres-forts de secrets.

Obtenir un token

Chaque type d'utilisateur dispose de son propre flux d'authentification. Le processus général en deux étapes (envoi OTP puis vérification) s'applique aux partenaires, staff et membres.

cURL — Étape 1 : Demande OTP
curl -X POST https://fidelioo.co/api/fr-fr/v1/partner/auth/send-otp \
  -H "Content-Type: application/json" \
  -d '{"phone": "+22961000000"}'
cURL — Étape 2 : Vérification OTP et obtention du token
curl -X POST https://fidelioo.co/api/fr-fr/v1/partner/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+22961000000",
    "otp": "482917"
  }'
JSON — Réponse
{
  "success": true,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 604800,
  "partner": {
    "id": 42,
    "name": "Boulangerie Central",
    "phone": "+22961000000",
    "subscription_status": "active",
    "plan": "business"
  }
}

Admin — Connexion

Les administrateurs Fidelioo s'authentifient avec un email et un mot de passe (pas d'OTP).

MéthodeEndpointDescription
POST/api/fr-fr/v1/admin/auth/loginConnexion administrateur (email + mot de passe)
POST/api/fr-fr/v1/admin/auth/logoutDéconnexion et révocation du token
POST/api/fr-fr/v1/admin/auth/refreshRenouvellement du token
GET/api/fr-fr/v1/admin/auth/meInformations du compte admin connecté
cURL — Connexion admin
curl -X POST https://fidelioo.co/api/fr-fr/v1/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@fidelioo.co",
    "password": "motdepasse_securise"
  }'

Admin — Gestion des partenaires

Tous ces endpoints nécessitent un token admin valide.

MéthodeEndpointDescription
GET/api/fr-fr/v1/admin/partnersLister tous les partenaires (paginé)
GET/api/fr-fr/v1/admin/partners/{id}Détails d'un partenaire
POST/api/fr-fr/v1/admin/partnersCréer un partenaire manuellement
PUT/api/fr-fr/v1/admin/partners/{id}Mettre à jour un partenaire
DELETE/api/fr-fr/v1/admin/partners/{id}Supprimer un partenaire
PATCH/api/fr-fr/v1/admin/partners/{id}/suspendSuspendre un compte partenaire
PATCH/api/fr-fr/v1/admin/partners/{id}/activateRéactiver un compte partenaire
GET/api/fr-fr/v1/admin/partners/{id}/statsStatistiques d'un partenaire
GET/api/fr-fr/v1/admin/partners/{id}/subscriptionAbonnement actuel d'un partenaire
POST/api/fr-fr/v1/admin/partners/{id}/subscriptionModifier l'abonnement d'un partenaire
GET/api/fr-fr/v1/admin/subscription-plansLister tous les plans d'abonnement
POST/api/fr-fr/v1/admin/subscription-plansCréer un nouveau plan
PUT/api/fr-fr/v1/admin/subscription-plans/{id}Modifier un plan
GET/api/fr-fr/v1/admin/transactionsToutes les transactions de paiement
GET/api/fr-fr/v1/admin/stats/overviewStatistiques globales de la plateforme

Admin — Permissions

MéthodeEndpointDescription
GET/api/fr-fr/v1/admin/adminsLister les comptes administrateurs
POST/api/fr-fr/v1/admin/adminsCréer un compte administrateur
PUT/api/fr-fr/v1/admin/admins/{id}Modifier un administrateur
DELETE/api/fr-fr/v1/admin/admins/{id}Supprimer un administrateur
GET/api/fr-fr/v1/admin/rolesLister les rôles disponibles
POST/api/fr-fr/v1/admin/admins/{id}/rolesAssigner un rôle à un admin

Partenaire — Connexion

MéthodeEndpointDescription
POST/api/fr-fr/v1/partner/auth/send-otpEnvoyer un OTP par SMS
POST/api/fr-fr/v1/partner/auth/verify-otpVérifier OTP et obtenir le token
POST/api/fr-fr/v1/partner/auth/registerInscription d'un nouveau partenaire
POST/api/fr-fr/v1/partner/auth/logoutDéconnexion
POST/api/fr-fr/v1/partner/auth/refreshRenouveler le token
GET/api/fr-fr/v1/partner/auth/meProfil du partenaire connecté
PUT/api/fr-fr/v1/partner/auth/meMettre à jour le profil partenaire

Abonnement partenaire

MéthodeEndpointDescription
GET/api/fr-fr/v1/partner/subscriptionAbonnement actuel
GET/api/fr-fr/v1/partner/subscription/plansPlans disponibles
POST/api/fr-fr/v1/partner/subscription/checkoutInitier un paiement d'abonnement
GET/api/fr-fr/v1/partner/subscription/historyHistorique des paiements

Partenaire — Clubs

MéthodeEndpointDescription
GET/api/fr-fr/v1/partner/clubsLister tous les clubs
POST/api/fr-fr/v1/partner/clubsCréer un club
GET/api/fr-fr/v1/partner/clubs/{id}Détails d'un club
PUT/api/fr-fr/v1/partner/clubs/{id}Modifier un club
DELETE/api/fr-fr/v1/partner/clubs/{id}Supprimer un club (si vide)
GET/api/fr-fr/v1/partner/clubs/{id}/statsStatistiques du club
PATCH/api/fr-fr/v1/partner/clubs/{id}/toggleActiver / désactiver un club
cURL — Créer un club
curl -X POST https://fidelioo.co/api/fr-fr/v1/partner/clubs \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Club Fidèle Boulangerie Central",
    "description": "Programme de fidélité de la Boulangerie Central",
    "color": "#f59e0b"
  }'

Partenaire — Cartes de fidélité

MéthodeEndpointDescription
GET/api/fr-fr/v1/partner/cards/loyaltyLister les cartes de fidélité
POST/api/fr-fr/v1/partner/cards/loyaltyCréer une carte de fidélité
GET/api/fr-fr/v1/partner/cards/loyalty/{id}Détails d'une carte
PUT/api/fr-fr/v1/partner/cards/loyalty/{id}Modifier une carte
DELETE/api/fr-fr/v1/partner/cards/loyalty/{id}Supprimer une carte
GET/api/fr-fr/v1/partner/cards/loyalty/{id}/rewardsLister les récompenses d'une carte
POST/api/fr-fr/v1/partner/cards/loyalty/{id}/rewardsAjouter une récompense
PUT/api/fr-fr/v1/partner/cards/loyalty/{id}/rewards/{rid}Modifier une récompense
DELETE/api/fr-fr/v1/partner/cards/loyalty/{id}/rewards/{rid}Supprimer une récompense
GET/api/fr-fr/v1/partner/cards/loyalty/{id}/levelsNiveaux de fidélité
POST/api/fr-fr/v1/partner/cards/loyalty/{id}/levelsCréer un niveau
PUT/api/fr-fr/v1/partner/cards/loyalty/{id}/levels/{lid}Modifier un niveau
GET/api/fr-fr/v1/partner/cards/loyalty/{id}/statsStatistiques de la carte

Partenaire — Cartes tampons

MéthodeEndpointDescription
GET/api/fr-fr/v1/partner/cards/stampLister les programmes tampons
POST/api/fr-fr/v1/partner/cards/stampCréer un programme tampon
GET/api/fr-fr/v1/partner/cards/stamp/{id}Détails d'un programme
PUT/api/fr-fr/v1/partner/cards/stamp/{id}Modifier un programme
DELETE/api/fr-fr/v1/partner/cards/stamp/{id}Supprimer un programme
GET/api/fr-fr/v1/partner/cards/stamp/{id}/statsStatistiques tampons
PATCH/api/fr-fr/v1/partner/cards/stamp/{id}/toggleActiver / désactiver

Partenaire — Staff

MéthodeEndpointDescription
GET/api/fr-fr/v1/partner/staffLister les membres du staff
POST/api/fr-fr/v1/partner/staffAjouter un membre au staff
GET/api/fr-fr/v1/partner/staff/{id}Détails d'un membre du staff
PUT/api/fr-fr/v1/partner/staff/{id}Modifier un membre du staff
DELETE/api/fr-fr/v1/partner/staff/{id}Retirer un membre du staff
GET/api/fr-fr/v1/partner/staff/{id}/permissionsPermissions d'un staff
PUT/api/fr-fr/v1/partner/staff/{id}/permissionsModifier les permissions
PATCH/api/fr-fr/v1/partner/staff/{id}/suspendSuspendre un compte staff
cURL — Ajouter un membre au staff
curl -X POST https://fidelioo.co/api/fr-fr/v1/partner/staff \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+22966000001",
    "first_name": "Koffi",
    "last_name": "Mensah",
    "club_ids": [12, 15],
    "permissions": ["scan_stamps", "add_points", "validate_coupons"]
  }'

Partenaire — Membres

MéthodeEndpointDescription
GET/api/fr-fr/v1/partner/membersLister tous les membres
POST/api/fr-fr/v1/partner/membersInscrire un membre manuellement
GET/api/fr-fr/v1/partner/members/{id}Profil complet d'un membre
PUT/api/fr-fr/v1/partner/members/{id}Modifier le profil d'un membre
DELETE/api/fr-fr/v1/partner/members/{id}Supprimer un membre
GET/api/fr-fr/v1/partner/members/{id}/pointsSolde et historique de points
POST/api/fr-fr/v1/partner/members/{id}/points/adjustAjuster les points (+ ou -)
GET/api/fr-fr/v1/partner/members/{id}/stampsTampons collectés
GET/api/fr-fr/v1/partner/members/{id}/couponsBons de réduction
GET/api/fr-fr/v1/partner/members/{id}/transactionsHistorique des transactions
PATCH/api/fr-fr/v1/partner/members/{id}/blockBloquer un membre
PATCH/api/fr-fr/v1/partner/members/{id}/unblockDébloquer un membre
GET/api/fr-fr/v1/partner/members/exportExporter la liste en CSV
POST/api/fr-fr/v1/partner/members/importImporter des membres via CSV

Partenaire — Bons de réduction

MéthodeEndpointDescription
GET/api/fr-fr/v1/partner/couponsLister les campagnes de bons
POST/api/fr-fr/v1/partner/couponsCréer une campagne de bons
GET/api/fr-fr/v1/partner/coupons/{id}Détails d'une campagne
PUT/api/fr-fr/v1/partner/coupons/{id}Modifier une campagne
DELETE/api/fr-fr/v1/partner/coupons/{id}Supprimer une campagne
GET/api/fr-fr/v1/partner/coupons/{id}/codesLister les codes générés
POST/api/fr-fr/v1/partner/coupons/{id}/generateGénérer de nouveaux codes
POST/api/fr-fr/v1/partner/coupons/{id}/distributeDistribuer les codes par SMS
GET/api/fr-fr/v1/partner/coupons/{id}/statsStatistiques d'utilisation
GET/api/fr-fr/v1/partner/coupons/validate/{code}Vérifier la validité d'un code
cURL — Créer une campagne de bons
curl -X POST https://fidelioo.co/api/fr-fr/v1/partner/coupons \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_name": "Promo Rentrée 2026",
    "type": "percent",
    "value": 20,
    "min_purchase": 5000,
    "max_discount": 10000,
    "valid_from": "2026-09-01",
    "valid_until": "2026-09-30",
    "max_uses": 200,
    "max_uses_per_member": 1,
    "club_id": 12
  }'

Partenaire — Récompenses

MéthodeEndpointDescription
GET/api/fr-fr/v1/partner/rewardsLister toutes les récompenses
POST/api/fr-fr/v1/partner/rewardsCréer une récompense
GET/api/fr-fr/v1/partner/rewards/{id}Détails d'une récompense
PUT/api/fr-fr/v1/partner/rewards/{id}Modifier une récompense
DELETE/api/fr-fr/v1/partner/rewards/{id}Supprimer une récompense
GET/api/fr-fr/v1/partner/rewards/{id}/redemptionsHistorique des échanges
PATCH/api/fr-fr/v1/partner/rewards/{id}/toggleActiver / désactiver

Partenaire — Transactions

MéthodeEndpointDescription
GET/api/fr-fr/v1/partner/transactionsToutes les transactions (paginé)
GET/api/fr-fr/v1/partner/transactions/{id}Détails d'une transaction
GET/api/fr-fr/v1/partner/transactions/pointsTransactions de points uniquement
GET/api/fr-fr/v1/partner/transactions/stampsTransactions de tampons uniquement
GET/api/fr-fr/v1/partner/transactions/redemptionsÉchanges de récompenses
GET/api/fr-fr/v1/partner/stats/dashboardStatistiques du tableau de bord
GET/api/fr-fr/v1/partner/stats/membersStatistiques des membres
GET/api/fr-fr/v1/partner/stats/revenueIndicateurs de revenu et rétention

Staff — Connexion

MéthodeEndpointDescription
POST/api/fr-fr/v1/staff/auth/send-otpEnvoyer un OTP
POST/api/fr-fr/v1/staff/auth/verify-otpVérifier OTP et obtenir le token
POST/api/fr-fr/v1/staff/auth/logoutDéconnexion
GET/api/fr-fr/v1/staff/auth/meProfil du staff connecté
GET/api/fr-fr/v1/staff/auth/permissionsPermissions accordées

Staff — Membres

MéthodeEndpointDescription
GET/api/fr-fr/v1/staff/membersRechercher un membre
GET/api/fr-fr/v1/staff/members/{id}Profil d'un membre
GET/api/fr-fr/v1/staff/members/{id}/cardsCartes d'un membre
GET/api/fr-fr/v1/staff/members/lookupRecherche par numéro de téléphone
POST/api/fr-fr/v1/staff/membersInscrire un nouveau membre
cURL — Rechercher un membre par téléphone
curl -X GET "https://fidelioo.co/api/fr-fr/v1/staff/members/lookup?phone=%2B22961000001" \
  -H "Authorization: Bearer {token}"

Staff — Opérations

MéthodeEndpointDescription
POST/api/fr-fr/v1/staff/members/pointsAttribuer des points (par montant)
POST/api/fr-fr/v1/staff/members/points/manualAttribution manuelle de points
POST/api/fr-fr/v1/staff/stamps/scanValider un tampon (QR code)
POST/api/fr-fr/v1/staff/rewards/redeemTraiter un échange de récompense
POST/api/fr-fr/v1/staff/coupons/validateValider un bon de réduction
GET/api/fr-fr/v1/staff/transactionsTransactions traitées par ce staff
cURL — Attribuer des points par montant d'achat
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": 7500,
    "note": "Achat caisse principale #12983"
  }'
cURL — Traiter un échange de récompense
curl -X POST https://fidelioo.co/api/fr-fr/v1/staff/rewards/redeem \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "redemption_code": "RDM-48291-K",
    "member_pin": "1234"
  }'

Membre — Connexion

MéthodeEndpointDescription
POST/api/fr-fr/v1/member/auth/send-otpEnvoyer un OTP
POST/api/fr-fr/v1/member/auth/verify-otpVérifier OTP et obtenir le token
POST/api/fr-fr/v1/member/auth/logoutDéconnexion
POST/api/fr-fr/v1/member/auth/refreshRenouveler le token
GET/api/fr-fr/v1/member/auth/meProfil du membre connecté
PUT/api/fr-fr/v1/member/auth/meModifier le profil
POST/api/fr-fr/v1/member/auth/pinDéfinir ou modifier le PIN
POST/api/fr-fr/v1/member/auth/pin/resetRéinitialiser le PIN via OTP

Membre — Cartes

MéthodeEndpointDescription
GET/api/fr-fr/v1/member/cardsToutes les cartes du membre
GET/api/fr-fr/v1/member/cards/loyaltyCartes de fidélité uniquement
GET/api/fr-fr/v1/member/cards/loyalty/{id}Détails et solde de points
GET/api/fr-fr/v1/member/cards/loyalty/{id}/rewardsRécompenses disponibles
POST/api/fr-fr/v1/member/cards/loyalty/{id}/rewards/{rid}/requestDemander un échange de récompense
GET/api/fr-fr/v1/member/cards/loyalty/{id}/transactionsHistorique des points
GET/api/fr-fr/v1/member/cards/stampCartes tampons
GET/api/fr-fr/v1/member/cards/stamp/{id}Détails et compteur de tampons
GET/api/fr-fr/v1/member/qr-codeQR code personnel du membre
POST/api/fr-fr/v1/member/cards/join/{club_id}Rejoindre un club
JSON — Réponse cartes de fidélité membre
{
  "success": true,
  "data": [
    {
      "id": 5,
      "name": "Carte Fidélité Premium",
      "club": { "id": 12, "name": "Boulangerie Central" },
      "points_balance": 127,
      "level": {
        "name": "Or",
        "multiplier": 2,
        "next_level": "Platine",
        "points_to_next": 373
      },
      "color": "#2563eb",
      "available_rewards": 3
    }
  ]
}

Membre — Bons

MéthodeEndpointDescription
GET/api/fr-fr/v1/member/couponsTous les bons du membre
GET/api/fr-fr/v1/member/coupons/activeBons actifs et utilisables
GET/api/fr-fr/v1/member/coupons/{code}Détails d'un bon spécifique
POST/api/fr-fr/v1/member/coupons/redeemUtiliser un bon
GET/api/fr-fr/v1/member/notificationsNotifications du membre
PATCH/api/fr-fr/v1/member/notifications/{id}/readMarquer comme lu

Codes d'erreur

L'API Fidelioo retourne des codes d'erreur HTTP standards accompagnés d'un code d'erreur applicatif pour faciliter le débogage.

HTTPCode applicatifDescription
400VALIDATION_ERRORDonnées de la requête invalides ou manquantes
401UNAUTHENTICATEDToken absent, invalide ou expiré
403FORBIDDENAction non autorisée pour ce rôle ou cette ressource
403SUBSCRIPTION_REQUIREDAbonnement actif requis pour cette fonctionnalité
403PLAN_LIMIT_REACHEDLimite du plan atteinte (ex. : nombre de cartes max.)
404NOT_FOUNDRessource introuvable
409ALREADY_EXISTSLa ressource existe déjà
409OTP_ALREADY_SENTUn OTP a déjà été envoyé, patientez avant de renvoyer
422OTP_INVALIDCode OTP incorrect
422OTP_EXPIREDCode OTP expiré (délai de 10 minutes dépassé)
422PIN_INVALIDPIN membre incorrect
422INSUFFICIENT_POINTSPoints insuffisants pour cet échange
422COUPON_EXPIREDBon de réduction expiré
422COUPON_ALREADY_USEDBon déjà utilisé par ce membre
422COUPON_MAX_USES_REACHEDQuota d'utilisation de ce bon épuisé
422MEMBER_BLOCKEDCompte membre suspendu
429TOO_MANY_ATTEMPTSTrop de tentatives, patientez 15 minutes
500SERVER_ERRORErreur interne du serveur
503PAYMENT_GATEWAY_ERRORErreur de communication avec Feexpay

Rate limiting

L'API applique des limites de débit pour protéger la plateforme :

EndpointLimiteFenêtre
Envoi OTP3 requêtes15 minutes par numéro
Vérification OTP3 tentatives15 minutes par numéro
API générale (auth)60 requêtes1 minute par token
API générale (non auth)30 requêtes1 minute par IP
Les en-têtes de rate limiting sont inclus dans chaque réponse : X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.