Мекеме ережелері мен лимиттері

Бұл беттегінің бәрін мекеме иесі Әзірлеушілерге → Кассаларға арналған ережелер бөлімінде баптайды. Ережелер мекеменің барлық API кілтіне қолданылады, ал жеке кілтке (бір касса, бір киоск) олардың кез келгеніне өз мәнін беруге болады. Интеграцияңыз қай ережелермен жұмыс істейтінін GET /v1/account жауабындағы settings ішінен оқиды.

"settings": {
  "redemption": "hold",
  "hold_minutes": 30,
  "check_numbering": "per_register",
  "offline_max_hours": 72,
  "redeem_max_per_check": 50000,
  "redeem_max_per_day": null,
  "require_scan": true,
  "scan_window_minutes": 30,
  "allow_adjustments": false,
  "adjustment_max": 50000
}

Кэшбэк деңгейлері

Кэшбэк бағдарламасында деңгейлер болуы мүмкін: мысалы, Базалық 5%, екінші келуден бастап Күміс 7%, 1000.00 жұмсалғаннан бастап Алтын 10%. Деңгейлер келу саны бойынша, жалпы сома бойынша немесе қайсысы бұрын орындалса, сол бойынша есептеледі. Оларды мекеме иесі адалдық бағдарламасында баптайды. Касса жағында ештеңе істеудің керегі жоқ: әр чек қонақтың осы чектен кейінгі деңгейі бойынша есептеледі, ал қатысушы объектісі қонақтың қай деңгейде тұрғанын көрсетеді.

"cashback": {
  "balance": 10200,
  "held": 0,
  "available": 10200,
  "currency": "MDL",
  "earn_rate": 7,
  "level": "Silver",
  "level_basis": "any",
  "levels": [
    { "name": "Base", "earn_rate": 5, "min_visits": null, "min_spent": null },
    { "name": "Silver", "earn_rate": 7, "min_visits": 2, "min_spent": null },
    { "name": "Gold", "earn_rate": 10, "min_visits": null, "min_spent": 100000 }
  ],
  "next_level": { "name": "Gold", "earn_rate": 10, "visits_left": null, "spent_left": 80000 },
  ...
}

next_level.visits_left және next_level.spent_left мәндерін қонаққа бірден көрсетуге болады ("Күміске дейін тағы 2 келу"). display.receipt_lines ішінде бұл жол қонақтың тілінде дайын тұр.

Тауар санаттары

Тауарларыңызды санатымен бір рет жүктеп, кейін тек өзгерістерді жіберіңіз. Санаттар мекеме иесінің басқару панелінде пайда болады, онда әр санатқа мыналарды орнатуға болады: кэшбэк бермейді (темекі, алкоголь), кэшбэкпен төлеуге болмайды (акциядағы тауарлар) немесе қонақтың деңгейінің орнына өз пайызын береді (кофе 10%). API тауарлар мен санаттарды жасап, атауын өзгерте алады, бірақ бұл ережелерді тек мекеме иесі өзгертеді.

curl https://loyaltyfy.io/api/v1/catalog/products/bulk \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      { "sku": "4840001", "name": "Marlboro Gold", "category": "TOB", "category_name": "Tobacco", "price": 6500 },
      { "sku": "1001", "name": "Latte", "category": "COF", "category_name": "Coffee", "price": 4500 },
      { "sku": "2040", "name": "Zeama", "category": "KIT", "category_name": "Kitchen", "price": 6500 }
    ]
  }'

# { "object": "catalog_sync", "upserted": 3 }

Содан кейін әр чекпен line_items жіберіңіз. Жолда category болуы мүмкін немесе тек sku: санатты каталогтан өзіміз табамыз. Жолдардың сомалары чек сомасына сәйкестендіріледі, сондықтан касса жасаған жеңілдіктер әділ бөлінеді. Ережесі жоқ санаттағы жолдар қонақтың деңгейі бойынша есептеледі.

curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CHK-2026-000130",
    "member": "2000111703779",
    "amount": 17500,
    "line_items": [
      { "sku": "4840001", "quantity": 1, "unit_price": 6500 },
      { "sku": "1001", "quantity": 1, "unit_price": 4500 },
      { "sku": "2040", "quantity": 1, "unit_price": 6500 }
    ]
  }'

# Tobacco earns nothing, Coffee has its own 10%, Kitchen earns at the guest's level (5%):
# 0 + 450 + 325 = "cashback_earned": 775

Кэшбэкпен резерв арқылы төлеу

Чектің ішінде режимінде (әдепкі) касса redeem_amount мәнін жабылған чекпен бірге жібереді. Резерв арқылы режимінде қонақ кэшбэкпен төлегісі келгенде касса соманы бөліп қояды, ал жабылған чек оны растайды. Чек келмесе (желі үзілді, сату тоқтатылды), резерв иесі белгілеген уақыттан кейін алынады және ақша қонақта қалады. Жеңілдік ешқашан баланстан алынбай берілмейді.

1. 1
   Резервтеу

   Қатысушымен, сомамен және чек сомасымен POST /v1/holds шақырыңыз. Чектегідей шектер қолданылады. Жауапта резервтің id мәні болады.

2. 2
   Растау

   hold_id көрсетіп POST /v1/transactions шақырыңыз. Бүкіл резервті пайдалану үшін redeem_amount жібермеңіз немесе кішірек соманы жіберіңіз.

3. 3
   Немесе босату

   Сату тоқтатылса, POST /v1/holds/{id}/release шақырыңыз. Екі рет босату зиян келтірмейді.

curl https://loyaltyfy.io/api/v1/holds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hold-R3-000131" \
  -d '{ "member": "2000111703779", "amount": 3000, "check_amount": 20000, "register_id": "R3" }'

# at payment: the check captures it
curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "000131", "register_id": "R3", "member": "2000111703779",
        "amount": 20000, "hold_id": "5b0d6c1e-8f3a-4d7e-9a61-2c4b8e0f7d19" }'

Әр кассаның чек нөмірлері

Әр касса чектерді 1-ден бастап санаса, Әр кассаның өз нөмірлері параметрін таңдаңыз. Сонда register_id міндетті болады, ал чекті <register_id>:<external_id> түрінде сақтаймыз, мысалы R3:15. Чекті оқу, болдырмау немесе қайтару үшін осы біріктірілген id-ді пайдаланыңыз.

Кешіктіріп жіберілген чектер

Байланыс үзілгеннен кейін касса жиналған кезегін жібереді. Лимит, мысалы, 72 сағат болса, closed_at мәні одан ескі чектер check_too_old арқылы қабылданбайды. Сондықтан ескі сақтық көшірмеден қалпына келтірілген касса мекемеге ескірген чектерді жаудыра алмайды. closed_at болашаққа 10 минуттан көп ығысқан болса, чек әрқашан қабылданбайды.

Кэшбэкпен төлеу лимиттері

Бағдарламадағы чек үлесіне қосымша, мекеме иесі бір чекке және бір қонаққа күніне (барлық кассалар бірге, мекеменің уақыт белдеуі бойынша) ең көп кэшбэкті белгілей алады. Көбірек сұраған чек рұқсат етілген соманы ғана жұмсайды, ал жауап нақты redeem_amount мәнін көрсетеді. Көбірек сұраған резерв limited_by арқылы қабылданбайды. Қонаққа нақты соманы алдын ала көрсету үшін есептеуді пайдаланыңыз.

Картаны міндетті сканерлеу

Бұл ереже қосулы болса, картаға арналған чек, келу, резерв немесе сыйлық сол кілт осы картаны жақында ғана POST /v1/scans эндпоинтіне жіберген болса ғана қабылданады. Кассада қолмен терілген карта нөмірі scan_required арқылы қабылданбайды. Сканер берген мәнді өзгертпестен /v1/scans эндпоинтіне жіберіп, әрі қарай әдеттегідей жұмыс істеңіз.

Қолмен түзету

Әдепкі бойынша өшірулі. Мекеме иесі рұқсат берсе, members:adjust құқығы бар кілт себебін көрсетіп кэшбэкті қоса немесе алып тастай алады, бір түзетуге иесі белгілеген лимитке дейін. Әр түзету қатысушының тарихына жазылады және balance.adjusted жібереді.

curl https://loyaltyfy.io/api/v1/members/2000111703779/adjustments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "ADJ-2026-0009", "amount": 2000, "reason": "Goodwill after a complaint" }'

# a negative amount takes cashback away