FideliaDéveloppeurs · API caisseEnglish

Démarrage rapide

Il vous faut la clé du bac à sable (fk_test_…) et la feuille de cartes de test envoyée par Fidelia. Les exemples utilisent curl ; définissez votre clé une fois :

export FIDELIA_KEY=fk_test_...

1. Qui suis-je ?

curl https://api.fidelia.se/pos/v1/me -H "Authorization: Bearer $FIDELIA_KEY"

Vous recevez le commerce de test (devise, langues), son établissement et six programmes de carte, un par type, avec leurs récompenses et les articles de caisse liés.

2. Scanner une carte

Scannez Bruno sur la feuille de test (ou tapez son numéro de carte : votre feuille a ses propres numéros, ceux ci-dessous sont des exemples). Il a 9 tampons sur 10, et le palier de la carte (un biscuit à 5 tampons) l’attend : essayez aussi rewards/milestone:cookie/redeem.

curl https://api.fidelia.se/pos/v1/cards/1138395626754?lang=fr \
  -H "Authorization: Bearer $FIDELIA_KEY"
{
  "card": {
    "card_number": "1138395626754",
    "type": "stamps",
    "customer": { "first_name": "Bruno", "locale": "fr" },
    "stamps": { "count": 9, "required": 10, "reward_ready": false, "reward": "Café offert" },
    "rewards_available": [{ "id": "milestone:cookie", "label": "Biscuit offert" }]
  }
}

3. Clôturer un ticket

Chaque POST exige un Idempotency-Key : un nouvel UUID par action (une nouvelle tentative le réutilise).

curl -X POST https://api.fidelia.se/pos/v1/cards/1138395626754/sale \
  -H "Authorization: Bearer $FIDELIA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1250, "receipt_ref": "T1-000001" }'

La réponse contient "applied": true, "event": "reward_ready" et la carte à jour : Bruno a maintenant 10/10 et rewards_available contient ready (à côté du biscuit qu’il n’a pas utilisé).

4. Utiliser la récompense

curl -X POST https://api.fidelia.se/pos/v1/cards/1138395626754/rewards/ready/redeem \
  -H "Authorization: Bearer $FIDELIA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "receipt_ref": "T1-000002" }'

La réponse contient "product": { "ref": "SKU-COFFEE", "value": 350 } : ajoutez cet article au ticket gratuitement.

5. Rembourser

curl -X POST https://api.fidelia.se/pos/v1/receipts/T1-000002/reverse \
  -H "Authorization: Bearer $FIDELIA_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

La récompense revient sur la carte de Bruno. Annuler aussi T1-000001 retire le tampon.

Ensuite