Chioșcuri și scanere

Dispozitive fără casă de marcat: un scaner la intrare, o tabletă la care oaspeții se înscriu, un scaner la tejghea care acordă recompense.

Dă fiecărui dispozitiv propria cheie, doar cu permisiunea devices:write. Poate scana carduri, înregistra vizite, înscrie oaspeți și acorda recompense, dar nu poate lista membrii și nu poate trimite bonuri. Dacă tableta e furată, revoci doar acea cheie.

Scanează orice

Trimite la POST /v1/scans exact ce a produs scanerul. Ne ocupăm noi de formatele diferite: un număr de card, un QR de card, un Code 128 cu prefixul de simbologie ]C1, un Enter sau Tab la final de la un scaner în mod tastatură, un link către pagina cardului sau un număr de telefon introdus pe chioșc.

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

Răspuns · 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 arată ce poate face acest dispozitiv în continuare pentru acest oaspete, așa că ecranul poate afișa butoanele potrivite fără să cunoască regulile programului. Când oaspetele are o recompensă care îl așteaptă, apare acțiunea redeem_reward, cu calea de apelat.

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
  }
]

Ștampilă pentru vizită fără bon

Pentru programele cu ștampile și vizite, o simplă prezență este suficientă: ușa unei săli de sport, o boxă de spălătorie auto, o tejghea de cafea fără casă de marcat. POST /v1/visits acordă recompensa per vizită a programului. Trimite un external_id unic pentru fiecare prezență (de exemplu numele dispozitivului plus un contor); o repetare este ignorată.

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

Răspuns · 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 },
    ...
  },
  ...
}

Programele de cashback acumulează pe bani, nu pe vizite, așa că o vizită pentru un membru cu cashback este refuzată cu 400 visit_not_supported. actions dintr-o scanare nu oferă niciodată visit pentru astfel de membri.

Ca să nu pui două ștampile când oaspetele scanează de două ori la rând, construiește external_id din membru și intervalul de timp, de exemplu door-1-4285324286429-2026-10-06T18: cel mult o ștampilă pe oră.

O tabletă la intrare cere telefonul și numele, afișează condițiile de prelucrare a datelor și apelează POST /v1/members cu consent: true numai după ce oaspetele este de acord. Apoi afișează wallet.apple_url sau wallet.google_url ca QR: oaspetele îl scanează și cardul ajunge direct în 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

Dacă telefonul este deja înscris, apelul întoarce membrul existent cu 200, așa că un oaspete care și-a pierdut cardul pur și simplu îl primește din nou.

Chioșcuri și scanere

Scanează orice

Ștampilă pentru vizită fără bon

Chioșc de înscriere