À la caisse

Le scan

Les cartes Fidelia affichent soit un QR code (le numéro de série de la carte, 32 caractères 0-9a-f), soit un code-barres (Code 128 du numéro de carte à 13 chiffres), selon le choix du commerce dans les réglages de la carte. Passez ce que le scanner a lu comme {code} : l’API accepte les deux, tout comme l’app scanner Fidelia.

La plupart des scanners de caisse se comportent comme un clavier et finissent par Entrée : quand la saisie fait 13 chiffres ou 32 caractères hexadécimaux, traitez-la comme une carte Fidelia.
Un code qui n’est pas une carte Fidelia de ce commerce répond 404 card_not_found : continuez la vente normalement.
Le numéro de carte est aussi imprimé sous le code-barres, le caissier peut donc le taper.

Le déroulé recommandé

Scan → GET /cards/{code}. Affichez customer.first_name et un court résumé de la carte (voir le tableau ci-dessous).
Abonnement : si membership.active, appliquez membership.discount_percent au panier. Sinon, proposez Renouveler (POST …/membership/renew) ou indiquez au client qu’il a expiré.
Récompenses : si rewards_available n’est pas vide, demandez « Utiliser la récompense maintenant ? » (une carte à tampons peut avoir des récompenses intermédiaires, les paliers, d’id milestone:<id> ; la carte continue de se remplir après). Si oui, POST …/rewards/{id}/redeem et ajoutez product.ref au ticket gratuitement (product.value est son prix normal, pour vos rapports). Si le commerce n’a pas lié d’article, product vaut null : laissez le caissier choisir l’article.
Solde : pour cashback et prepaid, proposez Payer avec le solde de la carte : POST …/balance/spend avec "amount": "all" (ou un montant saisi) et receipt_total. Ajoutez spent comme ligne de paiement ; le client paie le reste autrement.
Clôture du ticket → POST …/sale avec le total réellement payé et le numéro de ticket. Envoyez-le même quand rien ne semble s’appliquer : Fidelia décide.

Utilisez le même receipt_ref pour tous les appels d’un ticket : les remboursements et le calcul du cashback en dépendent.

À quoi ressemble une carte

`type`	Afficher	Champs
`stamps`	« 7 / 10 tampons »	`stamps.count`, `stamps.required`, `stamps.reward_ready`, `stamps.reward`, `stamps.milestones[]`
`points`	« 120 points »	`points.balance`, `points.rewards[]` avec `available`
`cashback`	« Solde 5,00 »	`balance.amount`, `balance.percent`
`prepaid`	« Solde 22,00 »	`balance.amount`, `balance.bonus_percent`
`membership`	« Membre · 10 % de remise »	`membership.active`, `discount_percent`, `valid_until`, `perk`
`pack`	« Encore 8 cafés »	`pack.items_left`, `pack.active`, `pack.item`

Chaque carte peut aussi avoir un niveau VIP dans tier (nom et avantage).

La vente

POST /cards/{code}/sale
{ "amount": 1250, "receipt_ref": "T1-000042" }

Ce que fait Fidelia, selon le type et les réglages de caisse du commerce :

Type	Effet
`stamps`	+1 tampon si les tampons automatiques sont activés et que `amount` atteint le minimum du commerce. Une carte pleine passe en `reward_ready`.
`points`	`earned_points` = montant ÷ `spend_per_point` du programme. `reward_available` nomme une récompense qui vient de se débloquer.
`cashback`	`earned_balance` = pourcentage du montant moins le solde utilisé sur le même ticket.
`membership`	Un passage, si l’abonnement est actif.
`prepaid`, `pack`	Rien (`not_applicable`).

Une vente n’échoue jamais à cause de l’état de la carte. Elle répond 200 avec "applied": false et une reason :

`reason`	Signification
`cooldown`	Un tampon / passage a été donné il y a quelques minutes (réglage du commerce).
`reward_ready`	La carte à tampons est pleine : utilisez d’abord la récompense, puis les tampons reprennent.
`below_min_amount`	Sous le ticket minimum du commerce pour un tampon.
`auto_stamp_off`	Le commerce tamponne à la main, pas à chaque vente.
`nothing_to_earn`	Tout a été payé avec le solde de la carte, ou le montant était 0.
`membership_expired`, `membership_inactive`	Pas un membre actif.
`not_applicable`	Les cartes prépayées et carnets ne gagnent rien sur une vente.
`program_inactive`, `subscription_inactive`	La carte ou l’abonnement du commerce s’est arrêté ; rien à faire à la caisse.

Autres actions

Appel	Pour	Corps
`POST …/rewards/ready/redeem`	carte à tampons pleine	`also_stamp: true` tamponne aussi le passage du jour
`POST …/rewards/milestone:<id>/redeem`	palier d’une carte à tampons	une fois par tour de tampons ; `already_claimed` ensuite
`POST …/rewards/{id}/redeem`	points	`id` venant de `points.rewards[]`
`POST …/balance/spend`	cashback, prépayée	`amount` (ou `"all"`), `receipt_total`
`POST …/balance/topup`	prépayée	`amount` payé ; `credited` inclut le bonus
`POST …/membership/renew`	abonnement	renouvelle, ou active un abonnement en attente de paiement
`POST …/pack/sell`	carnet	active un carnet en attente, ou ajoute `count` carnets
`POST …/pack/use`	carnet	`count` articles (1–10)

Chaque réponse renvoie la card à jour, pour que la caisse affiche aussitôt le nouvel état.