FideliaDevelopers · POS APIFrançais

Quickstart

You need the sandbox key (fk_test_…) and the test card sheet Fidelia sent you. The examples use curl; set your key once:

export FIDELIA_KEY=fk_test_...

1. Who am I?

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

You get the sandbox shop (currency, languages), its location and six card programs, one per type, with their rewards and the POS products linked to them.

2. Scan a card

Scan Bruno on the test sheet (or type his card number: your sheet has its own numbers, the ones below are examples). He has 9 of 10 stamps, and the card’s milestone (a cookie at 5 stamps) is waiting: try rewards/milestone:cookie/redeem too.

curl https://api.fidelia.se/pos/v1/cards/1138395626754?lang=en \
  -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": "Free coffee" },
    "rewards_available": [{ "id": "milestone:cookie", "label": "Free cookie" }]
  }
}

3. Close a receipt

Every POST needs an Idempotency-Key: a fresh UUID per action (a retry reuses it).

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" }'

The answer has "applied": true, "event": "reward_ready" and the updated card: Bruno now has 10/10 and rewards_available lists ready (next to the cookie he hasn’t used).

4. Use the reward

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" }'

The answer includes "product": { "ref": "SKU-COFFEE", "value": 350 }: add that product to the receipt at no charge.

5. Refund

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

The reward is back on Bruno’s card. Reversing T1-000001 too takes the stamp away.

Next