☰ Меню · Правила й ліміти закладу
Правила й ліміти закладу
Як заклад керує тим, що можуть робити підключені каси: рівні кешбеку, категорії товарів, резерви, нумерація чеків, чеки, надіслані пізніше, ліміти та перевірка скану.
Усе, що описано на цій сторінці, власник закладу налаштовує в розділі Розробникам → Правила для кас. Правила діють для всіх ключів 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% з другого візиту, Золотий 10% після 1000.00 покупок. Рівні рахуються за візитами, за сумою покупок або за тим, що настане раніше. Власник задає їх у програмі лояльності. На боці каси нічого робити не потрібно: кожен чек нараховує кешбек за рівнем, який гість має після цього чека, а в кожному об’єкті учасника видно, на якому рівні гість.
"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Підтвердження
POST /v1/transactionsзhold_id. Не передавайте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 цифр), літери ставляться попереду. Уже випущені картки зберігають номери, а card_number, переданий у POST /v1/members, завжди головніший. Префікс повертається в settings.card_prefix у GET /v1/account.
Чеки, надіслані пізніше
Після збою каса надсилає накопичену чергу. Якщо ліміт становить, скажімо, 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%, на точці «Чеканi» для «Алкоголю» 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 (залишок копійок іде в найбільший рядок). Режим віддається в settings.redeem_accounting у GET /v1/account (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", а POST /v1/transactions з redeem_amount або hold_id відхиляється з 400 discount_redeem_not_allowed. Тоді у відповіді є і discount_type (тип і його правила), а в кожної позиції свій discount_type. Заклади без типів знижок теж можуть передавати поле: воно ігнорується.
Позиції в акції
Позначте рядок чека як товар в акції полем line_items[].promo: true у POST /v1/checks/calculate, POST /v1/transactions і POST /v1/holds. Для таких рядків власник ставить два правила в Розробникам → Правила для кас → Позиції в акції: нараховувати кешбек (за замовчуванням увімк) і оплачувати кешбеком (за замовчуванням вимк). Вимкнене правило сильніше за будь-які правила товару, категорії й точки для цього рядка: рядок нічого не нараховує (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 лей, пляшка вина) або за перехід на рівень кешбеку. Коли чек переходить поріг або переводить гостя на цей рівень, подарунок відкривається й чекає гостя. Один подарунок за кожним правилом на гостя назавжди; якщо один чек перейшов кілька порогів, відкриється кілька подарунків. Гості, які пройшли поріг до ввімкнення правила, нічого не отримають, а повернення чека подарунок не забирає. Подарунок може мати строк очікування, після нього він 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 штамп за кожну одиницю товару з вибраних категорій (ваговий товар рахується однією одиницею), плюс мінімальна сума чека для штампа. Категорії це коди category з ваших line_items або каталогу. Режимам за категоріями потрібні line_items у POST /v1/transactions і POST /v1/checks/calculate; чек без позицій дає 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