Kiosklar ve tarayıcılar

Kasası olmayan cihazlar: girişteki tarayıcı, misafirlerin kayıt olduğu tablet, ödül veren tezgah tarayıcısı.

Her cihaza yalnızca devices:write iznine sahip ayrı bir anahtar verin. Cihaz kart okutabilir, ziyaret kaydedebilir, misafir kaydedebilir ve ödül verebilir, ancak üyeleri listeleyemez veya fiş gönderemez. Tablet çalınırsa yalnızca o anahtarı iptal edin.

Her şeyi okutun

Tarayıcının ürettiği değeri olduğu gibi POST /v1/scans uç noktasına gönderin. Farklı biçimleri biz çözümleriz: kart numarası, kart QR'ı, ]C1 sembol önekli Code 128, klavye emülasyonlu tarayıcıdan gelen Enter veya Tab, kart sayfası bağlantısı ya da kioskta yazılan telefon numarası.

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

Yanıt · 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, bu cihazın bu misafir için sonraki adımda yapabileceklerini listeler. Böylece ekran, programın kurallarını bilmeden doğru butonları gösterebilir. Misafiri bekleyen bir ödül varsa, çağrılacak yolu içeren bir redeem_reward işlemi görünür.

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

Fiş olmadan ziyarete damga basın

Damga ve ziyaret programlarında bir giriş kaydı yeterlidir: spor salonu kapısı, oto yıkama peronu, kasası olmayan bir kahve tezgahı. POST /v1/visits programın ziyaret başına ödülünü verir. Her giriş için benzersiz bir external_id gönderin (örneğin cihaz adı ve bir sayaç). Tekrarlar yok sayılır.

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

Yanıt · 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 programları ziyaretle değil harcamayla kazandırır, bu yüzden cashback üyesi için gönderilen ziyaret 400 visit_not_supported ile reddedilir. Bu üyeler için tarama yanıtındaki actions hiçbir zaman visit önermez.

Misafir arka arkaya iki kez okuttuğunda çift damga basılmaması için external_id değerini üye ve zaman aralığından oluşturun, örneğin door-1-4285324286429-2026-10-06T18: saatte en fazla bir damga.

Girişteki tablet telefon ve ad ister, gizlilik koşullarını gösterir ve ancak misafir onayladıktan sonra consent: true ile POST /v1/members çağırır. Ardından wallet.apple_url veya wallet.google_url bağlantısını QR olarak gösterin: misafir okutur ve kart doğrudan Wallet'ına eklenir.

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

Telefon zaten kayıtlıysa istek mevcut üyeyi 200 ile döndürür. Kartını kaybeden misafir kartını yeniden almış olur.

Kiosklar ve tarayıcılar

Her şeyi okutun

Fiş olmadan ziyarete damga basın

Kayıt kioskü