☰ Meniu · Regulile localului și limite
Regulile localului și limite
Cum controlează localul ce pot face casele conectate: niveluri de cashback, categorii de produse, rezervări, numerotarea bonurilor, bonuri trimise mai târziu, limite și verificarea scanării.
Tot ce este pe această pagină se setează de proprietarul localului în Dezvoltatori → Reguli pentru case. Regulile se aplică tuturor cheilor API ale localului; o singură cheie (o casă, un chioșc) poate avea valori proprii pentru oricare dintre ele. Integrarea ta citește regulile după care lucrează din GET /v1/account, în 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"
}Niveluri de cashback
Un program de cashback poate avea niveluri: de exemplu De bază 5%, Silver 7% de la a doua vizită, Gold 10% de la 1000,00 cheltuiți. Nivelurile se calculează după vizite, după suma cheltuită sau după ce se atinge primul. Proprietarul le setează în programul de fidelitate. Pe partea casei nu trebuie făcut nimic: fiecare bon acumulează la nivelul pe care oaspetele îl are după acel bon, iar fiecare obiect member îți arată unde se află oaspetele.
"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 și next_level.spent_left pot fi afișate direct oaspetelui ("încă 2 vizite până la Silver"). display.receipt_lines conține deja acest rând în limba oaspetelui.
Categorii de produse
Încarcă o dată produsele cu categoria lor, apoi trimite doar modificările. Categoriile apar în panoul proprietarului, unde fiecare poate fi setată să nu acorde cashback (tutun, alcool), să nu poată fi plătită cu cashback (produse deja la promoție) sau să acorde un procent propriu în locul nivelului oaspetelui (cafea 10%). API-ul poate crea și redenumi produse și categorii, dar numai proprietarul schimbă aceste reguli.
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 }Apoi trimite line_items cu fiecare bon. O linie poate avea category sau doar sku: căutăm categoria în catalog. Totalurile liniilor sunt scalate la suma bonului, așa că reducerile făcute pe casă se distribuie corect. Liniile din categorii fără reguli acumulează la nivelul oaspetelui. Fiecare tranzacție și POST /v1/checks/calculate returnează line_items cu ce a acumulat fiecare poziție, iar o returnare poate numi pozițiile returnate. Proprietarul poate suprascrie regula unei categorii și pe un singur produs, definitiv sau doar între două date (promoție).
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": 775La localurile cu ordinea detaliată a regulilor activată, category poate fi și numele categoriei, așa cum îl vede proprietarul în catalog („Bere”, nu doar „106”, indiferent de majuscule): linia urmează atunci regulile acelei categorii. Numele unei categorii nu creează niciodată o categorie nouă. O valoare pe care catalogul nu o cunoaște este înlocuită cu categoria produsului după sku; doar dacă produsul nu are categorie, valoarea apare ca o categorie nouă. Câștigă regula cea mai concretă: produsul, apoi categoria lui, apoi programul sau nivelul; un produs cu procentul lui îl primește chiar și într-o categorie fără acumulare. Pe un bon sub suma minimă a programului sau într-o locație fără acumulare, fiecare linie răspunde earn_percent: null și cashback_earned: 0, iar sub minim bonul răspunde earn_rate: 0.
Plata cu cashback prin rezervare
Cu În bon (implicit), casa trimite redeem_amount împreună cu bonul închis. Cu Prin rezervare, casa pune suma deoparte când oaspetele cere să plătească cu cashback, iar bonul închis o confirmă. Dacă bonul nu mai vine (a căzut rețeaua, vânzarea a fost anulată), rezervarea se eliberează după timpul stabilit de proprietar, iar banii rămân la oaspete. Nicio reducere nu se acordă fără să fie scăzută din sold.
- 1Rezervă
POST /v1/holdscu membrul, suma și totalul bonului. Se aplică aceleași plafoane ca la un bon. Răspunsul conțineid-ul rezervării. - 2Confirmă
POST /v1/transactionscuhold_id. Omiteredeem_amountca să folosești toată rezervarea sau trimite o sumă mai mică. - 3Sau eliberează
POST /v1/holds/{id}/releasecând vânzarea este anulată. O eliberare repetată nu are niciun efect.
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 al membrului, în limite și în aplicația de casă a localului, așa că aceiași bani nu pot fi cheltuiți de două ori.Numerele bonurilor pe fiecare casă
Dacă fiecare casă numără bonurile de la 1, alege Fiecare casă are numerotarea ei. Atunci register_id devine obligatoriu, iar bonul este salvat ca <register_id>:<external_id>, de exemplu R3:15. Folosește acest id combinat ca să citești, să anulezi sau să returnezi bonul.
Prefixul numărului de card
Cardurile emise de noi primesc un număr de 13 cifre. Dacă casa recunoaște cardurile de fidelitate după primele cifre, setați un prefix în Dezvoltatori → Reguli pentru case: cardurile noi vor începe cu el. Cifrele rămân în cele 13 caractere (prefixul 2999 dă 2999 și încă 9 cifre), literele se pun în față. Cardurile deja emise își păstrează numerele, iar un card_number trimis cu POST /v1/members are mereu prioritate. Prefixul se returnează în settings.card_prefix din GET /v1/account.
Bonuri trimise mai târziu
După o întrerupere, casa își trimite coada. Cu o limită de, să zicem, 72 de ore, bonurile al căror closed_at este mai vechi sunt refuzate cu check_too_old, așa că o casă restaurată dintr-o copie de rezervă veche nu poate umple localul cu bonuri expirate. Un closed_at cu mai mult de 10 minute în viitor este refuzat întotdeauna.
Limite de folosire
Pe lângă partea din bon stabilită de program, proprietarul poate seta suma maximă de cashback pe bon și pe oaspete pe zi (toate casele împreună, după fusul orar al localului). Un bon care cere mai mult folosește cât este permis, iar răspunsul arată redeem_amount real; o rezervare care cere mai mult este refuzată cu limited_by. Folosește calculul ca să-i arăți mai întâi oaspetelui suma exactă.
Reguli pe locații
Proprietarul leagă codurile caselor de o locație în Locații. Codul este register_id pe care casa îl trimite cu bonurile, calculele și rezervările. O locație poate opri acumularea, poate avea procent propriu, poate interzice plata cu cashback sau poate avea propria parte din bon care se poate plăti cu cashback. Proprietarul alege și ce câștigă când un produs (categorie), locația și nivelul clientului au fiecare un procent: produs, locație, nivel; locație, produs, nivel; sau nivelul clientului înaintea locației (atunci procentul locației înlocuiește doar nivelul de bază). O categorie fără acumulare rămâne exclusă în orice ordine. Unde plata cu cashback nu e permisă, POST /v1/checks/calculate răspunde max_redeem: 0 cu redeem_blocked_reason, iar un bon sau o rezervare cu cashback este refuzată cu 400 redeem_not_allowed_here. Un bon fără register_id sau cu un cod nelegat urmează regulile generale; codurile necunoscute apar într-o listă pentru proprietar.
Ordinea regulilor
Dacă localul folosește excepții pe locații, fiecare linie a bonului urmează regula cea mai specifică: excepția locației pentru produs, apoi excepția locației pentru categorie, apoi regula produsului, regula categoriei, procentul propriu al locației și, la final, nivelul oaspetelui sau procentul programului. Fiecare câmp (procent, acumulare, plată cu cashback) se ia din prima regulă care îl stabilește. Exemplu: programul 5%, categoria Alcool 3%, la locația Ciocana pentru Alcool 2%. La Ciocana linia cu alcool primește 2%, la celelalte locații 3%, restul produselor 5%. Excepțiile se aplică doar bonurilor cu register_id legat de o locație. Acumularea sau achitarea oprite la locație și limita de achitare a locației se aplică mereu. Excepțiile se citesc cu GET /v1/catalog/location-rules.
Cashback ca plată sau ca reducere
Contabilul localului alege în Dezvoltatori → Reguli pentru case cum înregistrează casa plata cu cashback. Ca plată (implicit): cashback-ul este un mod de plată, o singură sumă alături de numerar și card; prețurile produselor și TVA-ul nu se schimbă. Ca reducere: cashback-ul micșorează prețurile produselor și TVA-ul se calculează din prețul după reducere. În acest mod fiecare linie din POST /v1/checks/calculate și POST /v1/transactions are și redeem_allocated (unități minore): partea din redeem_amount care revine liniei, proporțional cu suma ei. Liniile care nu pot fi plătite cu cashback primesc 0, iar liniile dau mereu exact redeem_amount (banii rămași merg la cea mai mare linie). Modul este în settings.redeem_accounting din GET /v1/account (payment sau discount). Fără line_items nu se împarte nimic.
{
"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 }
]
}Tipuri de reduceri
Trimiteți reducerea aplicată de casă în discount_type, un cod de până la 64 de caractere, de exemplu employee, discount_card sau promo, pe tot bonul și, la nevoie, pe linii separate (line_items[].discount_type). Fiecare cod nou apare singur în Dezvoltatori → Tipuri de reduceri, unde proprietarul îi dă un nume și decide dacă un astfel de bon acumulează cashback și dacă poate fi plătit cu cashback. Un tip nou acumulează și permite plata până când proprietarul îl schimbă. Un tip de bon fără acumulare dă 0 cashback pe tot bonul; un tip de linie fără acumulare dă 0 doar pe acea linie. Unde plata cu cashback nu este permisă, POST /v1/checks/calculate răspunde max_redeem: 0 cu limited_by: "discount_type" și redeem_blocked_reason: "discount_redeem_not_allowed", iar POST /v1/transactions cu redeem_amount sau hold_id este refuzat cu 400 discount_redeem_not_allowed. Răspunsurile au atunci și discount_type (tipul și regulile lui), iar fiecare linie propriul discount_type. Localurile fără tipuri de reduceri pot trimite câmpul: este ignorat.
Produse în promoție
Marcați o linie a bonului ca produs în promoție cu line_items[].promo: true în POST /v1/checks/calculate, POST /v1/transactions și POST /v1/holds. Proprietarul setează două reguli pentru aceste linii în Dezvoltatori → Reguli pentru case → Produse în promoție: acumulează cashback (pornit implicit) și plată cu cashback (oprit implicit). O regulă oprită are prioritate față de orice regulă a produsului, categoriei și locației pentru acea linie: linia nu acumulează nimic (earn_percent: null, cashback_earned: 0) sau nu poate fi plătită cu cashback (redeemable: false). O regulă pornită nu schimbă nimic, linia urmează regulile obișnuite. Partea bonului care poate fi plătită cu cashback, max_redeem și, la plata ca reducere, redeem_allocated nu includ liniile în promoție, deci împărțiți cashback-ul doar pe liniile cu redeemable: true. Fiecare linie a răspunsului poartă atunci promo (true sau false), bonul îl păstrează, iar GET /v1/account întoarce regulile în settings.promo_earn și settings.promo_redeem. O valoare alta decât true, false sau null răspunde 400 parameter_invalid. Un retur urmează ce a făcut linia inițială, deci acolo promo nu e necesar. Localurile fără această regulă pot trimite câmpul: este ignorat.
{
"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 }
],
...
}Cadouri care așteaptă predarea
Proprietarul setează regulile pe pagina Cadouri: un cadou pentru suma cumpărăturilor (de exemplu 5000 MDL, o sticlă de vin) sau pentru atingerea unui nivel de cashback. Când un bon trece pragul sau duce oaspetele la acel nivel, cadoul se deschide și îl așteaptă. Fiecare oaspete primește un cadou pe regulă, o singură dată; mai multe praguri trecute de un bon deschid mai multe cadouri. Oaspeții care au trecut pragul înainte de pornirea regulii nu primesc nimic, iar un retur nu ia cadoul înapoi. Un cadou poate avea un termen de așteptare; după el cadoul este expired.
Pașii pentru casă: 1) POST /v1/checks/calculate răspunde cu gifts.pending (deja în așteptare) și gifts.unlocks (ce va deschide acest bon, cu id: null), iar prima linie din display.cashier_text este cadoul, arătați-o casierului. 2) POST /v1/transactions răspunde cu gifts.unlocked (deschise de acest bon, cu id) și gifts.pending. 3) Casierul predă cadoul și apasă Cadou predat: apelați POST /v1/members/{member}/gifts/{gift_id}/give. Obiectul member conține și gifts.pending. Se trimit evenimentele gift.unlocked și gift.given. Localurile fără cadouri nu primesc câmpul gifts, iar adresele cadourilor răspund 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" }'Moduri de ștampile
Implicit un program cu ștampile dă 1 ștampilă pe bon. Proprietarul unui magazin poate schimba asta pe pagina Program: 1 ștampilă pe bonul care are un produs din categoriile alese sau 1 ștampilă pentru fiecare unitate de produs din categoriile alese (un produs cântărit contează ca o unitate), plus o sumă minimă a bonului pentru ștampilă. Categoriile sunt codurile category din line_items sau din catalogul dvs. Modurile pe categorii au nevoie de line_items în POST /v1/transactions și POST /v1/checks/calculate; un bon fără poziții dă 1 ștampilă, iar suma minimă se aplică oricărui bon. stamps_earned arată câte ștampile a dat bonul; când ele trec pragul cardului de mai multe ori, se deblochează mai multe recompense deodată, iar calculate răspunde și cu rewards_unlocked. Anularea retrage exact ștampilele rămase. În modul pe unitate un bon poate fi returnat pe poziții cu POST /v1/transactions/{external_id}/refunds: ștampilele pentru unitățile returnate se retrag (din recompensele nefolosite la nevoie, niciodată sub zero), iar răspunsul conține stamps_reversed. Celelalte bonuri cu ștampile se returnează în continuare integral prin anulare. Localurile fără moduri de ștampile păstrează 1 ștampilă pe bon.
Cardul trebuie scanat
Cu această regulă, un bon, o vizită, o rezervare sau o recompensă pentru un card sunt acceptate doar dacă aceeași cheie a trimis cardul la POST /v1/scans cu puțin înainte. Un număr de card tastat de mână pe casă este refuzat cu scan_required. Trimite la /v1/scans ce a produs scanerul, fără modificări, apoi continuă ca de obicei.
Corecții manuale
Dezactivate implicit. Când proprietarul le permite, o cheie cu permisiunea members:adjust poate adăuga sau scădea cashback cu un motiv, până la limita stabilită de proprietar pentru o corecție. Fiecare corecție apare în istoricul membrului și trimite 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