Кіоски та сканери

Пристрої без каси: сканер біля входу, планшет для реєстрації гостей, сканер на стійці, що видає нагороди.

Видайте кожному пристрою окремий ключ лише з правом devices:write. Такий ключ дає змогу сканувати картки, фіксувати візити, реєструвати гостей і видавати нагороди, але не дає доступу до списку учасників і не дозволяє надсилати чеки. Якщо планшет украдуть, відкличте лише цей ключ.

Скануйте що завгодно

Надсилайте в POST /v1/scans рівно те, що видав сканер. Різні формати ми обробляємо самі: номер картки, QR картки, Code 128 з префіксом символіки ]C1, Enter або Tab у кінці від сканера в режимі емуляції клавіатури, посилання на сторінку картки чи номер телефону, введений на кіоску.

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

Штамп за візит без чека

Для програм зі штампами та візитами достатньо відмітки про візит: двері спортзалу, бокс автомийки, кавова стійка без каси. POST /v1/visits нараховує винагороду за візит згідно з програмою. Передавайте унікальний external_id для кожної відмітки (наприклад, назву пристрою та лічильник). Повтор ігнорується.

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 },
    ...
  },
  ...
}

У програмах із кешбеком нарахування йде за гроші, а не за візити, тому візит для такого учасника відхиляється з 400 visit_not_supported. Серед actions сканування такі учасники ніколи не отримують visit.

Щоб не ставити два штампи, коли гість сканує картку двічі поспіль, формуйте external_id з учасника та часового вікна, наприклад door-1-4285324286429-2026-10-06T18: не більше одного штампа на годину.

Планшет біля входу запитує телефон та ім’я, показує умови обробки персональних даних і викликає POST /v1/members з consent: true лише після згоди гостя. Потім покажіть wallet.apple_url або wallet.google_url у вигляді QR: гість сканує його, і картка одразу потрапляє в гаманець.

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, тож гість, який загубив картку, просто отримає її знову.

Кіоски та сканери

Скануйте що завгодно

Штамп за візит без чека

Кіоск реєстрації