☰ Меню · Правила и лимиты заведения
Правила и лимиты заведения
Как заведение управляет тем, что могут подключённые кассы: уровни кэшбэка, категории товаров, резервы, нумерация чеков, поздние чеки, лимиты и проверка скана.
Всё, что описано на этой странице, владелец заведения настраивает в разделе Разработчикам → Правила для касс. Правила действуют для всех ключей 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%, на точке «Чеканы» для «Алкоголя» 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