API caisse Fidelia

L’API caisse Fidelia permet à une caisse enregistreuse de travailler avec les cartes de fidélité des commerces Fidelia. Le caissier scanne la carte du client (dans Apple Wallet, Google Wallet ou sur une page web) et la caisse la met à jour : pas de second appareil, rien à taper.

Le fonctionnement à la caisse

Le caissier scanne la carte. Votre scanner lit un QR code (un numéro de série de 32 caractères) ou un code-barres (un numéro de carte à 13 chiffres), selon le choix du commerce.
La caisse appelle GET /cards/{code} et affiche le prénom du client, ce qu’il y a sur la carte et toute récompense disponible. Les abonnements renvoient la remise à appliquer au panier.
Si une récompense est disponible, la caisse demande « Utiliser la récompense maintenant ? ». Un appui appelle POST /cards/{code}/rewards/{id}/redeem, et Fidelia renvoie l’article de caisse que le commerce a lié à cette récompense.
Pour les cartes cashback et prépayées, le caissier peut payer avec le solde de la carte (Tout utiliser ou un montant) : POST /cards/{code}/balance/spend. Traitez-le comme une ligne de paiement.
À la clôture du ticket, la caisse envoie POST /cards/{code}/sale avec le total et le numéro de ticket. Fidelia applique les règles du commerce : un tampon, des points, du cashback ou un passage.
Un remboursement dans les 24 heures appelle POST /receipts/{receipt_ref}/reverse, et tout ce que le ticket a fait est annulé.

Types de cartes

Type	Sur une vente	Autres actions
`stamps`	+1 tampon (à partir du montant minimum du commerce)	utiliser la récompense quand la carte est pleine
`points`	des points selon le montant dépensé	utiliser une récompense
`cashback`	un crédit, un pourcentage de ce qui a été payé en argent	payer avec le solde
`membership`	un passage ; appliquer `discount_percent` tant que l’abonnement est actif	renouveler / activer
`prepaid`	rien	payer avec le solde, recharger (avec bonus)
`pack`	rien	utiliser des articles, vendre / activer un carnet

Pas besoin de gérer chaque type pour commencer : sale fait ce qu’il faut pour chaque carte. Les détails sont dans À la caisse.

L’essentiel

URL de base : https://api.fidelia.se/pos/v1
JSON sur HTTPS. Chaque réponse a un en-tête X-Request-Id (donnez-le-nous quand vous demandez de l’aide).
Authentification : Authorization: Bearer fk_live_…, une clé par caisse. Les caisses reçoivent leur clé par jumelage avec un code à 6 chiffres.
Les montants sont des entiers en unités mineures de la devise du commerce (centimes d’euro, öre) : 1250 vaut 12,50.
Les textes (noms des cartes et récompenses) existent dans les langues du commerce ; demandez-en une avec ?lang=fr ou Accept-Language.
Le commerce doit avoir Fidelia Pro ; sinon l’API répond 402 plan_required.

Obtenir un accès

Écrivez à support@fidelia.se. Vous recevez un identifiant partenaire (envoyé lors du jumelage, pour que les commerces que vous amenez vous soient attribués) et un bac à sable : un commerce de test avec une carte de chaque type, une clé fk_test_ et une feuille de cartes de test à scanner. Suivez ensuite le démarrage rapide.