☰ Мәзір · Мекеме ережелері мен лимиттері
Мекеме ережелері мен лимиттері
Мекеме қосылған кассалардың не істей алатынын қалай басқарады: кэшбэк деңгейлері, тауар санаттары, резервтер, чек нөмірлері, кешіккен чектер, лимиттер және сканерлеуді тексеру.
Бұл беттегінің бәрін мекеме иесі Әзірлеушілерге → Кассаларға арналған ережелер бөлімінде баптайды. Ережелер мекеменің барлық 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,
"card_prefix": "2999"
}Кэшбэк деңгейлері
Кэшбэк бағдарламасында деңгейлер болуы мүмкін: мысалы, Базалық 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: санатты каталогтан өзіміз табамыз. Жолдардың сомалары чек сомасына сәйкестендіріледі, сондықтан касса жасаған жеңілдіктер әділ бөлінеді. Ережесі жоқ санаттағы жолдар қонақтың деңгейі бойынша есептеледі. Әр транзакция және POST /v1/checks/calculate әр позицияның есептегенін көрсететін line_items қайтарады, ал қайтару қайтарылған позицияларды атай алады. Иесі санат ережесін бір тауарда да өзгерте алады: тұрақты немесе тек екі күн арасында (акция).
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Ережелердің толық реті қосылған мекемелерде category иесі каталогта көретін санат атауы да бола алады («106» ғана емес, «Сыра» да, әріп регистрі маңызды емес): жол сол санаттың ережелерімен есептеледі. Санат атауы ешқашан жаңа санат жасамайды. Каталогта жоқ мән sku бойынша тауардың санатымен ауыстырылады; тауарда санат болмаса ғана мән жаңа санат ретінде пайда болады. Ең нақты ереже жеңеді: тауар, содан кейін оның санаты, содан кейін бағдарлама немесе деңгей; өз пайызы бар тауар есептелмейтін санатта да сол пайызды алады. Бағдарламаның ең аз сомасынан төмен чекте немесе есептемейтін нүктеде әр жол earn_percent: null және cashback_earned: 0 қайтарады, ал ең аз сомадан төмен чектің өзі earn_rate: 0 қайтарады.
Кэшбэкпен резерв арқылы төлеу
Чектің ішінде режимінде (әдепкі) касса redeem_amount мәнін жабылған чекпен бірге жібереді. Резерв арқылы режимінде қонақ кэшбэкпен төлегісі келгенде касса соманы бөліп қояды, ал жабылған чек оны растайды. Чек келмесе (желі үзілді, сату тоқтатылды), резерв иесі белгілеген уақыттан кейін алынады және ақша қонақта қалады. Жеңілдік ешқашан баланстан алынбай берілмейді.
- 1Резервтеу
Қатысушымен, сомамен және чек сомасымен
POST /v1/holdsшақырыңыз. Чектегідей шектер қолданылады. Жауапта резервтіңidмәні болады. - 2Растау
hold_idкөрсетіпPOST /v1/transactionsшақырыңыз. Бүкіл резервті пайдалану үшінredeem_amountжібермеңіз немесе кішірек соманы жіберіңіз. - 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" }'cashback.available мәнінде, лимиттерде және мекеменің өз касса қосымшасында. Сондықтан бір ақшаны екі рет жұмсау мүмкін емес.Әр кассаның чек нөмірлері
Әр касса чектерді 1-ден бастап санаса, Әр кассаның өз нөмірлері параметрін таңдаңыз. Сонда register_id міндетті болады, ал чекті <register_id>:<external_id> түрінде сақтаймыз, мысалы R3:15. Чекті оқу, болдырмау немесе қайтару үшін осы біріктірілген id-ді пайдаланыңыз.
Карта нөмірінің префиксі
Біз шығаратын карталар 13 цифрлы нөмір алады. Касса адалдық карталарын алғашқы цифрлар бойынша танитын болса, Әзірлеушілерге → Кассаларға арналған ережелер бөлімінде префикс қойыңыз: жаңа карталар онымен басталады. Цифрлар 13 белгінің ішінде қалады (2999 префиксі 2999 және тағы 9 цифр береді), әріптер алдына қойылады. Бұрын шығарылған карталар нөмірлерін сақтайды, ал POST /v1/members арқылы жіберілген card_number әрқашан басым. Префикс GET /v1/account ішінде settings.card_prefix ретінде қайтарылады.
Кешіктіріп жіберілген чектер
Байланыс үзілгеннен кейін касса жиналған кезегін жібереді. Лимит, мысалы, 72 сағат болса, closed_at мәні одан ескі чектер check_too_old арқылы қабылданбайды. Сондықтан ескі сақтық көшірмеден қалпына келтірілген касса мекемеге ескірген чектерді жаудыра алмайды. closed_at болашаққа 10 минуттан көп ығысқан болса, чек әрқашан қабылданбайды.
Кэшбэкпен төлеу лимиттері
Бағдарламадағы чек үлесіне қосымша, мекеме иесі бір чекке және бір қонаққа күніне (барлық кассалар бірге, мекеменің уақыт белдеуі бойынша) ең көп кэшбэкті белгілей алады. Көбірек сұраған чек рұқсат етілген соманы ғана жұмсайды, ал жауап нақты redeem_amount мәнін көрсетеді. Көбірек сұраған резерв limited_by арқылы қабылданбайды. Қонаққа нақты соманы алдын ала көрсету үшін есептеуді пайдаланыңыз.
Нүктелер бойынша ережелер
Иесі касса кодтарын Нүктелер бөлімінде нүктеге байлайды. Код дегеніміз касса чектермен, есептеулермен және резервтермен жіберетін register_id. Нүкте есептеуді өшіре алады, өз пайызын қоя алады, кэшбэкпен төлеуге тыйым сала алады немесе чектің кэшбэкпен төленетін өз үлесін қоя алады. Иесі тауардың (санаттың), нүктенің және клиент деңгейінің әрқайсысында пайыз болса, қайсысы басым екенін де таңдайды: тауар, нүкте, деңгей; нүкте, тауар, деңгей; немесе клиент деңгейі нүктеден басым (онда нүкте пайызы тек базалық деңгейді алмастырады). Есептемейтін санат кез келген ретте шығарылған күйде қалады. Кэшбэкпен төлеуге тыйым салынған жерде POST /v1/checks/calculate max_redeem: 0 және redeem_blocked_reason қайтарады, ал кэшбэкпен төленетін чек немесе резерв 400 redeem_not_allowed_here арқылы қабылданбайды. register_id жоқ немесе ешбір нүктеге байланбаған кодты чек жалпы ережелермен есептеледі; белгісіз кодтар иесіне байлау үшін тізіммен көрсетіледі.
Ережелер реті
Егер мекеме нүктелердегі ерекшеліктерді қолданса, чектің әр жолы ең нақты ережеге бағынады: нүктенің тауарға арналған ерекшелігі, содан кейін нүктенің санатқа арналған ерекшелігі, содан кейін тауар ережесі, санат ережесі, нүктенің өз пайызы және соңында қонақтың деңгейі немесе бағдарлама пайызы. Әр өріс (пайыз, есептеу, кэшбэкпен төлеу) оны белгілеген бірінші ережеден алынады. Мысал: бағдарлама 5%, «Алкоголь» санаты 3%, «Чеканы» нүктесінде «Алкоголь» үшін 2%. Чеканыда алкоголь жолы 2% алады, басқа нүктелерде 3%, қалған тауарлар 5%. Ерекшеліктер тек register_id нүктеге байланған чектерге қолданылады. Нүктеде өшірілген есептеу не есептен шығару және нүктенің есептен шығару лимиті әрқашан қолданылады. Ерекшеліктерді GET /v1/catalog/location-rules арқылы оқыңыз.
Кэшбэк төлем немесе жеңілдік ретінде
Мекеменің бухгалтері Әзірлеушілерге → Касса ережелері бөлімінде касса кэшбэкпен төлеуді қалай өткізетінін таңдайды. Төлем ретінде (әдепкі): кэшбэк қолма-қол ақша мен картаның қасындағы бір сомалы төлем тәсілі; тауар бағалары мен ҚҚС өзгермейді. Жеңілдік ретінде: кэшбэк тауар бағаларын төмендетеді, ҚҚС жеңілдіктен кейінгі бағадан есептеледі. Бұл режимде POST /v1/checks/calculate және POST /v1/transactions жауабының әр жолында redeem_allocated (кіші бірліктерде) бар: redeem_amount сомасының жол сомасына пропорционал түрде сол жолға келетін бөлігі. Кэшбэкпен төлеуге болмайтын жолдар 0 алады, ал жолдардың қосындысы әрқашан дәл redeem_amount болады (артық тиындар ең үлкен жолға кетеді). Режим GET /v1/account жауабындағы settings.redeem_accounting өрісінде (payment немесе discount). line_items болмаса, бөлу жоқ.
{
"amount": 10000,
"redeem_amount": 1000,
"net_amount": 9000,
"line_items": [
{ "sku": "LATTE", "amount": 6000, "redeemable": true, "redeem_allocated": 600 },
{ "sku": "CAKE", "amount": 3000, "redeemable": true, "redeem_allocated": 300 },
{ "sku": "WATER", "amount": 1000, "redeemable": true, "redeem_allocated": 100 }
]
}Жеңілдік түрлері
Касса берген жеңілдікті discount_type ішінде жіберіңіз: 64 таңбаға дейінгі код, мысалы employee, discount_card немесе promo, бүкіл чекке және қажет болса жеке жолдарға (line_items[].discount_type). Әр жаңа код Әзірлеушілерге → Жеңілдік түрлері бөлімінде өздігінен пайда болады, онда иесі оған атау береді және мұндай чекке кэшбэк есептеле ме, оны кэшбэкпен төлеуге бола ма, соны шешеді. Жаңа түр иесі өзгерткенше есептейді және төлеуге рұқсат береді. Есептемейтін чек түрі бүкіл чекке 0 кэшбэк береді; есептемейтін жол түрі тек сол жолға 0 береді. Кэшбэкпен төлеуге болмаса, POST /v1/checks/calculate max_redeem: 0, limited_by: "discount_type" және redeem_blocked_reason: "discount_redeem_not_allowed" қайтарады, ал redeem_amount немесе hold_id бар POST /v1/transactions 400 discount_redeem_not_allowed қатесімен қабылданбайды. Сонда жауаптарда discount_type (түр және оның ережелері), әр жолда өз discount_type болады. Жеңілдік түрлерін қоспаған мекемелер де өрісті жібере алады: ол еленбейді.
Акциядағы тауарлар
Чек жолын POST /v1/checks/calculate, POST /v1/transactions және POST /v1/holds сұрауларында line_items[].promo: true өрісімен акциядағы тауар деп белгілеңіз. Иесі осындай жолдарға Әзірлеушілерге → Кассаларға арналған ережелер → Акциядағы тауарлар бөлімінде екі ереже қояды: кэшбэк есептеу (әдепкі бойынша қосулы) және кэшбэкпен төлеу (әдепкі бойынша өшірулі). Өшірулі ереже осы жол үшін тауардың, санаттың және нүктенің кез келген ережесінен күшті: жол ештеңе есептемейді (earn_percent: null, cashback_earned: 0) немесе оны кэшбэкпен төлеуге болмайды (redeemable: false). Қосулы ереже ештеңені өзгертпейді, жол әдеттегі ережелерімен жүреді. Чектің кэшбэкпен төленетін бөлігі, max_redeem және жеңілдік ретінде есептен шығарғанда redeem_allocated акциядағы жолдарды есепке алмайды, сондықтан кэшбэкті тек redeemable: true жолдарына бөліңіз. Сонда жауаптың әр жолында promo (true немесе false) болады, чек оны сақтайды, ал GET /v1/account ережелерді settings.promo_earn және settings.promo_redeem ішінде қайтарады. true, false немесе null емес мән 400 parameter_invalid жауабын береді. Қайтару бастапқы жолдың істегенімен жүреді, сондықтан онда promo қажет емес. Бұл ережені қоспаған мекемелер өрісті жібере алады: ол еленбейді.
{
"member": "2000111703779",
"amount": 10000,
"line_items": [
{ "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "promo": true },
{ "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 3000 }
]
}{
"object": "check_calculation",
"amount": 10000,
"max_redeem": 900,
"cashback_earned": 500,
"earn_rate": 5,
"line_items": [
{ "sku": "4840001", "amount": 7000, "earn_percent": 5, "cashback_earned": 350, "redeemable": false, "promo": true },
{ "sku": "2040", "amount": 3000, "earn_percent": 5, "cashback_earned": 150, "redeemable": true, "promo": false }
],
...
}Беруді күтетін сыйлықтар
Иесі ережелерді Сыйлықтар бетінде қояды: сатып алу сомасы үшін сыйлық (мысалы 5000 MDL, бір бөтелке шарап) немесе кэшбэк деңгейіне жету үшін. Чек шектен асқанда немесе қонақты сол деңгейге көтергенде сыйлық ашылып, қонақты күтеді. Әр қонақ әр ереже бойынша бір рет қана сыйлық алады; бір чек бірнеше шектен асса, бірнеше сыйлық ашылады. Ереже қосылғанға дейін шектен өткен қонақтар ештеңе алмайды, ал қайтару сыйлықты алып қоймайды. Сыйлықтың күту мерзімі болуы мүмкін; одан кейін ол expired.
Касса үшін тәртіп: 1) POST /v1/checks/calculate gifts.pending (күтіп тұрғандар) және gifts.unlocks (осы чек ашатындар, id: null) қайтарады, ал display.cashier_text бірінші жолы сыйлық, оны кассирге көрсетіңіз. 2) POST /v1/transactions gifts.unlocked (осы чек ашқандар, id-мен) және gifts.pending қайтарады. 3) Кассир сыйлықты беріп, Сыйлық берілді түймесін басады: POST /v1/members/{member}/gifts/{gift_id}/give шақырыңыз. Member нысанында да gifts.pending бар. gift.unlocked және gift.given оқиғалары жіберіледі. Сыйлығы жоқ мекемелер gifts өрісін ешқашан алмайды, ал сыйлық мекенжайлары 404 endpoint_not_found қайтарады.
{
"object": "check_calculation",
"amount": 120000,
"cashback_earned": 6000,
"gifts": {
"pending": [],
"unlocks": [
{ "object": "gift", "id": null, "title": "Bottle of wine", "source": "spend_threshold", "threshold": 500000, "level": null, "cashier_note": "From the shelf by the till", "status": "pending", "expires_at": "2026-12-16T10:00:00.000Z" }
]
},
"display": {
"cashier_text": "Gift: Bottle of wine (hand it to the guest) · Cashback earned: 60.00 MDL · Cashback balance: 210.00 MDL",
"receipt_lines": ["Gift: Bottle of wine (hand it to the guest)", "Cashback earned: 60.00 MDL", "..."]
},
...
}"gifts": {
"unlocked": [
{ "object": "gift", "id": "6f1c0b7e-3a2d-4b8e-9c55-0d2e7a91f4b2", "title": "Bottle of wine", "source": "spend_threshold", "threshold": 500000, "level": null, "status": "pending", "unlocked_at": "2026-11-16T10:00:00.000Z", "expires_at": "2026-12-16T10:00:00.000Z", "given_at": null }
],
"pending": [ ... the same gift and any older ones still waiting ... ]
}curl -X POST https://loyaltyfy.io/api/v1/members/4285324286429/gifts/6f1c0b7e-3a2d-4b8e-9c55-0d2e7a91f4b2/give \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: give-6f1c0b7e" \
-H "Content-Type: application/json" \
-d '{ "register_id": "401", "cashier": "Ana" }'Мөр режимдері
Әдепкіде мөр бағдарламасы бір чекке 1 мөр береді. Дүкен иесі мұны Бағдарлама бетінде өзгерте алады: таңдалған санаттардан тауар бар чекке 1 мөр немесе таңдалған санаттардағы тауардың әр бірлігіне 1 мөр (өлшенетін тауар бір бірлік саналады), сондай-ақ мөр үшін чектің ең аз сомасы. Санаттар сіздің line_items немесе каталогыңыздағы category кодтары. Санат режимдеріне POST /v1/transactions және POST /v1/checks/calculate ішінде line_items қажет; позициясыз чек 1 мөр береді, ал ең аз сома кез келген чекке қолданылады. stamps_earned чектің неше мөр бергенін көрсетеді; мөрлер карта шегінен бірнеше рет өтсе, бірден бірнеше сыйлық ашылады және calculate rewards_unlocked те қайтарады. Болдырмау қалған мөрлерді дәл алып тастайды. «Әр бірлікке» режимінде чекті POST /v1/transactions/{external_id}/refunds арқылы позициялар бойынша қайтаруға болады: қайтарылған бірліктердің мөрлері алынады (қажет болса пайдаланылмаған сыйлықтардан, ешқашан нөлден төмен емес), ал жауапта stamps_reversed болады. Басқа мөр чектері бұрынғыдай болдырмау арқылы толық қайтарылады. Мөр режимі жоқ мекемелерде бір чекке 1 мөр қалады.
Картаны міндетті сканерлеу
Бұл ереже қосулы болса, картаға арналған чек, келу, резерв немесе сыйлық сол кілт осы картаны жақында ғана 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