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

  1. Le titulaire du commerce ouvre son espace Fidelix, Réglages → API, et crée une clé. Elle n'est affichée qu'une fois.
  2. Le développeur la range dans les variables secrètes de son serveur.
  3. 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

  1. 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.
  2. Un champ « Code fidélité » au moment de la commande.
  3. 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.
  4. 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é.

HTTPCodeQuand
400requete_invalide · code_invalideLe corps ou le code client n'a pas la bonne forme.
401cle_invalideClé absente, mal formée, inconnue ou révoquée.
402abonnement_requis · limite_gratuite_atteinteLe compte du commerce est fermé : rien n'est crédité.
404client_introuvable · achat_introuvableAucun client de ce commerce avec ce code, ou aucune commande sous cette référence.
409deja_annuleeCette commande a déjà été annulée.
422minimum_non_atteint · aucun_pointLe montant est sous le minimum du programme, ou ne rapporte aucun point.
429trop_de_requetesPlus de 120 appels en une minute pour cette clé. Attendez la durée indiquée par Retry-After.
500erreurIncident 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