Développeurs
L'API Fidelix
Reliez une boutique en ligne (Shopify, WooCommerce, YouCan…) ou un logiciel de caisse à Fidelix. À chaque commande payée, le client gagne ses points sur la même carte qu'en boutique, et son téléphone se met à jour tout seul.
Démarrer
- Le titulaire du commerce ouvre son espace Fidelix, Réglages → API, et crée une clé. Elle n'est affichée qu'une fois.
- Le développeur la range dans les variables secrètes de son serveur.
- Chaque appel envoie la clé en en-tête, en HTTPS, vers
https://fidelix.ma/api/v1.
Les clients sont désignés par leur code client (C-XXXXXX), affiché sur leur carte Fidelix. L'API ne reçoit et ne renvoie aucune donnée personnelle : ni nom, ni email, ni téléphone.
Authentification et sécurité
Authorization: Bearer fdx_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX- Serveur uniquement. Jamais dans le code d'une page web, d'un thème ou d'une application mobile : l'API refuse les appels venant d'un navigateur (aucune autorisation CORS).
- Fidelix ne garde que l'empreinte de la clé. Perdue ou exposée : révoquez-la dans Réglages → API et créez-en une autre. La révocation est immédiate.
- Une clé agit pour un seul point de vente, et ne voit que les clients de son enseigne.
- 120 appels par minute et par clé. Au-delà : réponse 429 et en-tête Retry-After.
Lire le solde d'un client
GET/api/v1/clients/{code_client}
curl https://fidelix.ma/api/v1/clients/C-7K4M2P \
-H "Authorization: Bearer $FIDELIX_API_KEY"{
"code_client": "C-7K4M2P",
"unite": "points",
"solde": 85,
"recompenses_accessibles": [{ "titre": "Café offert", "cout": 50 }],
"prochaine_recompense": { "titre": "Brunch offert", "cout": 100, "manquant": 15 }
}Créditer un achat
POST/api/v1/achats
curl -X POST https://fidelix.ma/api/v1/achats \
-H "Authorization: Bearer $FIDELIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "code_client": "C-7K4M2P", "montant": 240, "reference": "CMD-1042" }'{
"statut": "credite",
"code_client": "C-7K4M2P",
"reference": "CMD-1042",
"unite": "points",
"gagne": 24,
"solde": 109
}- montant : le total payé, dans la devise du programme. Les points sont calculés avec les règles du commerce (taux, minimum d'achat), exactement comme en caisse. Un programme à tampons ajoute un tampon par achat.
- reference : votre numéro de commande (lettres, chiffres,
- _ # . / :, 100 caractères au plus). Envoyée deux fois, la même référence ne crédite qu'une fois : la seconde réponse vaut"statut": "deja_enregistre". Vous pouvez donc renvoyer sans risque après une coupure. - Réponse 201 au premier crédit, 200 pour un renvoi déjà enregistré.
Annuler un achat remboursé
POST/api/v1/achats/annulation
curl -X POST https://fidelix.ma/api/v1/achats/annulation \
-H "Authorization: Bearer $FIDELIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "reference": "CMD-1042" }'{ "statut": "annule", "reference": "CMD-1042", "unite": "points", "retire": 24, "solde": 85 }Retire ce que la commande avait rapporté, sans jamais descendre sous zéro. Une seule annulation par référence (sinon 409).
Le parcours conseillé en boutique en ligne
- Un lien « Rejoindre le programme de fidélité » vers la page d'inscription Fidelix du commerce. Le client y crée sa carte en quelques secondes et reçoit son code.
- Un champ « Code fidélité » au moment de la commande.
- Créditez quand la commande est payée (ou livrée, pour un paiement à la livraison), pas quand elle est passée : un colis refusé ne doit pas rapporter de points.
- Remboursement ou retour : appelez l'annulation avec la même référence.
Erreurs
Toute erreur a la même forme : { "error": { "code": "…", "message": "…" } }. Le message est écrit pour être lu ; le code, pour être testé.
| HTTP | Code | Quand |
|---|---|---|
| 400 | requete_invalide · code_invalide | Le corps ou le code client n'a pas la bonne forme. |
| 401 | cle_invalide | Clé absente, mal formée, inconnue ou révoquée. |
| 402 | abonnement_requis · limite_gratuite_atteinte | Le compte du commerce est fermé : rien n'est crédité. |
| 404 | client_introuvable · achat_introuvable | Aucun client de ce commerce avec ce code, ou aucune commande sous cette référence. |
| 409 | deja_annulee | Cette commande a déjà été annulée. |
| 422 | minimum_non_atteint · aucun_point | Le montant est sous le minimum du programme, ou ne rapporte aucun point. |
| 429 | trop_de_requetes | Plus de 120 appels en une minute pour cette clé. Attendez la durée indiquée par Retry-After. |
| 500 | erreur | Incident de notre côté. Réessayez : la même référence ne créditera jamais deux fois. |
Une question, une intégration à faire ensemble ? contact@fidelix.ma