Kiosks και σαρωτές

Συσκευές χωρίς ταμείο: σαρωτής στην είσοδο, tablet όπου εγγράφονται οι πελάτες, σαρωτής στον πάγκο που δίνει επιβραβεύσεις.

Δώστε σε κάθε συσκευή δικό της κλειδί μόνο με το δικαίωμα devices:write. Μπορεί να σαρώνει κάρτες, να καταγράφει επισκέψεις, να εγγράφει πελάτες και να δίνει επιβραβεύσεις, αλλά δεν μπορεί να βλέπει τη λίστα μελών ούτε να στέλνει αποδείξεις. Αν κλαπεί το tablet, ανακαλέστε μόνο αυτό το κλειδί.

Σαρώστε οτιδήποτε

Στείλτε στο POST /v1/scans ακριβώς ό,τι έδωσε ο σαρωτής. Χειριζόμαστε εμείς τις διαφορετικές μορφές: αριθμό κάρτας, QR κάρτας, Code 128 με το πρόθεμα συμβολογίας ]C1, Enter ή Tab στο τέλος από σαρωτή που λειτουργεί ως πληκτρολόγιο, σύνδεσμο προς τη σελίδα της κάρτας ή τηλέφωνο που πληκτρολογήθηκε σε kiosk.

curl

curl https://loyaltyfy.io/api/v1/scans \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "]C14285324286429\r", "device_id": "door-1" }'

Απάντηση · 200

{
  "object": "scan",
  "matched": true,
  "matched_by": "4285324286429",
  "device_id": "door-1",
  "mechanic": "stamps",
  "member": {
    "object": "member",
    "card_number": "4285324286429",
    "first_name": "Ana",
    "stamps": { "current": 1, "required": 5, "rewards_available": 0 },
    ...
  },
  "actions": [
    { "type": "visit", "method": "POST", "path": "/v1/visits" },
    { "type": "transaction", "method": "POST", "path": "/v1/transactions" }
  ]
}

Το actions απαριθμεί τι μπορεί να κάνει στη συνέχεια αυτή η συσκευή για τον συγκεκριμένο πελάτη, ώστε η οθόνη να δείχνει τα σωστά κουμπιά χωρίς να γνωρίζει τους κανόνες του προγράμματος. Όταν ο πελάτης έχει επιβράβευση που τον περιμένει, εμφανίζεται η ενέργεια redeem_reward με τη διαδρομή που πρέπει να καλέσετε.

JSON

"actions": [
  { "type": "visit", "method": "POST", "path": "/v1/visits" },
  { "type": "transaction", "method": "POST", "path": "/v1/transactions" },
  {
    "type": "redeem_reward",
    "method": "POST",
    "path": "/v1/members/4285324286429/rewards/redeem",
    "available": 1
  }
]

Σφραγίδα για επίσκεψη χωρίς απόδειξη

Στα προγράμματα σφραγίδων και επισκέψεων αρκεί ένα check-in: η πόρτα ενός γυμναστηρίου, μια θέση πλυντηρίου αυτοκινήτων, ένας πάγκος καφέ χωρίς ταμείο. Το POST /v1/visits δίνει την επιβράβευση ανά επίσκεψη του προγράμματος. Στείλτε μοναδικό external_id για κάθε check-in (για παράδειγμα το όνομα της συσκευής και έναν μετρητή)· μια επανάληψη αγνοείται.

curl

curl https://loyaltyfy.io/api/v1/visits \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "door-1-2026-10-06-0042",
    "member": "4285324286429",
    "device_id": "door-1"
  }'

Απάντηση · 201

{
  "object": "visit",
  "id": "feb2ad75-ac7b-4bb6-8b64-192323b7f6ea",
  "external_id": "door-1-2026-10-06-0042",
  "status": "completed",
  "amount": 0,
  "stamps_earned": 1,
  "reward_unlocked": false,
  "register_id": "door-1",
  "livemode": false,
  "created_at": "2026-10-06T18:17:28.209+00:00",
  "member": {
    "object": "member",
    "card_number": "4285324286429",
    "stamps": { "current": 2, "required": 5, "rewards_available": 0 },
    ...
  },
  ...
}

Τα προγράμματα cashback κερδίζουν από χρήματα, όχι από επισκέψεις, οπότε μια επίσκεψη για μέλος cashback απορρίπτεται με 400 visit_not_supported. Τα actions μιας σάρωσης δεν προσφέρουν ποτέ visit για τέτοια μέλη.

Για να μη δοθεί διπλή σφραγίδα όταν ο πελάτης σαρώσει δύο φορές στη σειρά, φτιάξτε το external_id από το μέλος και το χρονικό παράθυρο, για παράδειγμα door-1-4285324286429-2026-10-06T18: το πολύ μία σφραγίδα την ώρα.

Ένα tablet στην είσοδο ζητά τηλέφωνο και όνομα, δείχνει τους όρους απορρήτου και καλεί POST /v1/members με consent: true μόνο αφού συμφωνήσει ο πελάτης. Στη συνέχεια δείξτε το wallet.apple_url ή το wallet.google_url ως QR: ο πελάτης το σαρώνει και η κάρτα μπαίνει κατευθείαν στο Wallet του.

curl

curl https://loyaltyfy.io/api/v1/members \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kiosk-3-0193" \
  -d '{ "phone": "+306912345678", "first_name": "Eleni", "language": "el", "consent": true }'

# show response.wallet.apple_url or google_url as a QR on the kiosk screen

Αν το τηλέφωνο είναι ήδη εγγεγραμμένο, η κλήση επιστρέφει το υπάρχον μέλος με 200, οπότε ένας πελάτης που έχασε την κάρτα απλώς την παίρνει ξανά.