☰ Menü · İşletme kuralları ve limitler
Rehberler

İşletme kuralları ve limitler

İşletme, bağlı kasaların neler yapabileceğini nasıl belirler: cashback seviyeleri, ürün kategorileri, rezervasyonlar, fiş numaralandırma, geç gelen fişler, limitler ve kart okutma kontrolü.

Bu sayfadaki her şeyi işletme sahibi Geliştiriciler → Kasa kuralları bölümünde ayarlar. Kurallar işletmenin tüm API anahtarları için geçerlidir. Tek bir anahtar (bir kasa, bir kiosk) bunların her biri için kendi değerine sahip olabilir. Entegrasyonunuz hangi kurallarla çalıştığını GET /v1/account yanıtındaki settings alanından okur.

JSON
"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"
}

Cashback seviyeleri

Bir cashback programının seviyeleri olabilir: örneğin Temel %5, ikinci ziyaretten itibaren Gümüş %7, 1000,00 harcamadan itibaren Altın %10. Seviyeler ziyaret sayısına, toplam harcamaya ya da hangisi önce gelirse ona göre hesaplanır. İşletme sahibi bunları sadakat programında ayarlar. Kasa tarafında bir şey yapmanız gerekmez: her fiş, misafirin o fişten sonraki seviyesine göre kazandırır ve her üye nesnesi misafirin hangi seviyede olduğunu gösterir.

JSON
"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 ve next_level.spent_left doğrudan misafire gösterilebilir ("Gümüş seviyeye 2 ziyaret kaldı"). display.receipt_lines bu satırı misafirin dilinde hazır olarak içerir.

Ürün kategorileri

Ürünlerinizi kategorileriyle bir kez yükleyin, sonra yalnızca değişiklikleri gönderin. Kategoriler işletme sahibinin panelinde görünür. Orada her kategori için şunlar seçilebilir: cashback kazandırmasın (tütün, alkol), cashback ile ödenemesin (zaten kampanyada olan ürünler) ya da misafirin seviyesi yerine kendi oranıyla kazandırsın (kahve %10). API ürün ve kategori oluşturabilir, adlarını değiştirebilir, ancak bu kuralları yalnızca işletme sahibi değiştirir.

curl
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 }

Ardından her fişle birlikte line_items gönderin. Bir satır category içerebilir ya da yalnızca sku taşıyabilir: bu durumda kategoriyi katalogdan buluruz. Satır toplamları fiş tutarına oranlanır, böylece kasa tarafında yapılan indirimler satırlara adil şekilde dağılır. Kuralı olmayan kategorilerdeki satırlar misafirin seviyesine göre kazandırır. Her işlem ve POST /v1/checks/calculate, her satırın kazandırdığını içeren line_items döndürür; bir iade de iade edilen satırları adlandırabilir. Sahip, bir kategorinin kuralını tek bir üründe de geçersiz kılabilir; kalıcı olarak veya yalnızca iki tarih arasında (kampanya).

curl
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

Ayrıntılı kural sırası açık olan işletmelerde category, sahibin katalogda gördüğü kategori adı da olabilir (yalnızca "106" değil "Bira" da, büyük küçük harf fark etmez): satır o kategorinin kurallarına göre işlenir. Bir kategori adı hiçbir zaman yeni kategori oluşturmaz. Katalogda olmayan bir değer, sku ile ürünün kategorisine düşer; yalnızca ürünün kategorisi yoksa değer yeni bir kategori olarak görünür. En özel kural kazanır: ürün, sonra kategorisi, sonra program veya seviye; kendi yüzdesi olan ürün, kazanç vermeyen bir kategoride bile bu yüzdeyi alır. Programın asgari tutarının altındaki bir fişte veya kazanç vermeyen bir konumda her satır earn_percent: null ve cashback_earned: 0 döner, asgari tutarın altında fişin kendisi de earn_rate: 0 döner.

Rezervasyonla cashback ödemesi

Fişin içinde seçeneğinde (varsayılan) kasa redeem_amount değerini kapanan fişle birlikte gönderir. Rezervasyonla seçeneğinde kasa, misafir cashback ile ödemek istediğinde tutarı ayırır, kapanan fiş de bunu onaylar. Fiş hiç gelmezse (bağlantı koptu, satış iptal edildi) rezervasyon işletme sahibinin belirlediği süreden sonra kalkar ve para misafirde kalır. Bakiyeden düşülmeden hiçbir indirim verilmez.

  1. 1
    Rezerve edin

    Üye, tutar ve fiş toplamıyla POST /v1/holds gönderin. Fişteki limitlerin aynısı uygulanır. Yanıtta rezervasyonun id değeri bulunur.

  2. 2
    Onaylayın

    hold_id ile POST /v1/transactions gönderin. Rezervasyonun tamamını kullanmak için redeem_amount göndermeyin ya da daha küçük bir tutar gönderin.

  3. 3
    Ya da kaldırın

    Satış iptal edildiğinde POST /v1/holds/{id}/release çağırın. İki kez kaldırmak zarar vermez.

curl
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" }'
Rezervasyonlar her yerde hesaba katılır: üyenin cashback.available değerinde, limitlerde ve işletmenin kendi kasiyer uygulamasında. Böylece aynı para iki kez harcanamaz.

Kasa bazında fiş numaraları

Her kasa fişleri 1'den saymaya başlıyorsa Her kasa kendi numarasını verir seçeneğini seçin. Bu durumda register_id zorunludur ve fişi <register_id>:<external_id> olarak saklarız, örneğin R3:15. Fişi okumak, iptal etmek veya iade etmek için bu birleşik id'yi kullanın.

Kart numarası ön eki

Bizim verdiğimiz kartlar 13 haneli bir numara alır. Kasa sadakat kartlarını ilk rakamlardan tanıyorsa Geliştiriciler → Kasa kuralları bölümünde bir ön ek belirleyin: yeni kartlar onunla başlar. Rakamlar 13 karakterin içinde kalır (2999 ön eki 2999 ve 9 rakam daha verir), harfler öne konur. Daha önce verilen kartlar numaralarını korur; POST /v1/members ile gönderilen card_number her zaman önceliklidir. Ön ek GET /v1/account içinde settings.card_prefix olarak döner.

Geç gönderilen fişler

Bir kesintiden sonra kasa kuyruğundaki fişleri gönderir. Limit örneğin 72 saat ise closed_at değeri bundan eski olan fişler check_too_old ile reddedilir. Böylece eski bir yedekten geri yüklenen kasa işletmeye eski fişler yağdıramaz. Gelecekte 10 dakikadan daha ileri bir closed_at her zaman reddedilir.

Cashback kullanım limitleri

İşletme sahibi, programın fiş başına oranına ek olarak fiş başına ve misafir başına günlük en fazla cashback tutarını belirleyebilir (tüm kasalar birlikte, işletmenin saat dilimine göre). Daha fazlasını isteyen bir fiş izin verilen kadarını kullanır ve yanıt gerçek redeem_amount değerini gösterir. Daha fazlasını isteyen bir rezervasyon limited_by ile reddedilir. Misafire kesin tutarı önceden göstermek için hesaplama uç noktasını kullanın.

Şube bazında kurallar

İşletme sahibi kasa kodlarını Şubeler bölümünde bir şubeye bağlar. Kod, kasanızın fişler, hesaplamalar ve rezervlerle gönderdiği register_id değeridir. Bir şube kazanımı kapatabilir, kendi yüzdesini belirleyebilir, cashback ile ödemeyi yasaklayabilir veya fişin cashback ile ödenebilecek kendi payını belirleyebilir. İşletme sahibi, ürünün (kategorinin), şubenin ve müşteri seviyesinin her birinin yüzdesi olduğunda hangisinin geçerli olacağını da seçer: ürün, şube, seviye; şube, ürün, seviye; veya müşteri seviyesi şubeden önce (bu durumda şube yüzdesi yalnızca temel seviyenin yerini alır). Kazandırmayan bir kategori her sırada hariç kalır. Cashback ile ödemenin yasak olduğu yerde POST /v1/checks/calculate max_redeem: 0 ve redeem_blocked_reason döndürür, cashback içeren fiş veya rezerv 400 redeem_not_allowed_here ile reddedilir. register_id olmayan veya hiçbir şubeye bağlı olmayan kodlu fiş genel kurallara uyar; bilinmeyen kodlar işletme sahibine bağlaması için listelenir.

Kuralların sırası

İşletme şube istisnaları kullanıyorsa, fişin her satırı en özel kuralı izler: şubenin ürün istisnası, sonra şubenin kategori istisnası, sonra ürün kuralı, kategori kuralı, şubenin kendi yüzdesi ve son olarak misafirin seviyesi veya program yüzdesi. Her alan (yüzde, kazanım, cashback ile ödenebilirlik) onu belirleyen ilk kuraldan alınır. Örnek: program %5, Alkol kategorisi %3, Ciocana şubesinde Alkol %2. Ciocana'da alkol satırı %2 kazanır, diğer şubelerde %3, diğer ürünler %5. İstisnalar yalnızca register_id bir şubeye bağlı fişlerde geçerlidir. Şubede kapatılan kazanım veya harcama ve şubenin harcama limiti her zaman geçerlidir. İstisnaları GET /v1/catalog/location-rules ile okuyun.

Cashback ödeme veya indirim olarak

İşletmenin muhasebecisi Geliştiriciler → Kasa kuralları bölümünde kasanın cashback ödemesini nasıl kaydedeceğini seçer. Ödeme olarak (varsayılan): cashback nakit ve kartın yanında tek tutarlı bir ödeme yöntemidir; ürün fiyatları ve KDV değişmez. İndirim olarak: cashback ürün fiyatlarını düşürür ve KDV indirimden sonraki fiyat üzerinden hesaplanır. Bu modda POST /v1/checks/calculate ve POST /v1/transactions yanıtındaki her satırda ayrıca redeem_allocated (küçük birim) bulunur: redeem_amount tutarının satır tutarıyla orantılı olarak o satıra düşen kısmı. Cashback ile ödenemeyen satırlar 0 alır ve satırların toplamı her zaman tam olarak redeem_amount eder (artan kuruşlar en büyük satıra gider). Mod GET /v1/account yanıtında settings.redeem_accounting alanındadır (payment veya discount). line_items yoksa bölme yapılmaz.

JSON
{
  "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 }
  ]
}

İndirim türleri

Kasanın uyguladığı indirimi discount_type içinde gönderin: en fazla 64 karakterlik bir kod, örneğin employee, discount_card veya promo, tüm fişe ve gerekirse tek satırlara (line_items[].discount_type). Her yeni kod kendiliğinden Geliştiriciler → İndirim türleri bölümünde görünür; işletme sahibi orada ona ad verir ve böyle bir fişin cashback kazanıp kazanmadığını ve cashback ile ödenip ödenemeyeceğini seçer. Yeni bir tür, sahip değiştirene kadar kazandırır ve ödemeye izin verir. Kazandırmayan bir fiş türü tüm fiş için 0 cashback verir; kazandırmayan bir satır türü yalnızca o satır için 0 verir. Cashback ile ödemeye izin verilmediğinde POST /v1/checks/calculate max_redeem: 0, limited_by: "discount_type" ve redeem_blocked_reason: "discount_redeem_not_allowed" döner; redeem_amount veya hold_id içeren POST /v1/transactions 400 discount_redeem_not_allowed ile reddedilir. Yanıtlarda ayrıca discount_type (tür ve kuralları) ve her satırda kendi discount_type alanı bulunur. İndirim türlerini açmamış işletmeler alanı gönderebilir: yok sayılır.

Kampanyadaki ürünler

Bir fiş satırını POST /v1/checks/calculate, POST /v1/transactions ve POST /v1/holds isteklerinde line_items[].promo: true ile kampanyadaki ürün olarak işaretleyin. İşletme sahibi bu satırlar için Geliştiriciler → Kasa kuralları → Kampanyadaki ürünler altında iki kural belirler: cashback kazandır (varsayılan açık) ve cashback ile öde (varsayılan kapalı). Kapalı bir kural o satır için tüm ürün, kategori ve şube kurallarından üstündür: satır hiçbir şey kazandırmaz (earn_percent: null, cashback_earned: 0) veya cashback ile ödenemez (redeemable: false). Açık bir kural hiçbir şeyi değiştirmez, satır olağan kurallarını izler. Fişin cashback ile ödenebilen kısmı, max_redeem ve indirim olarak kullanımda redeem_allocated kampanyadaki satırları dışarıda bırakır; bu yüzden cashback'i yalnızca redeemable: true olan satırlara dağıtın. Yanıtın her satırı o zaman promo (true veya false) taşır, fiş bunu saklar ve GET /v1/account kuralları settings.promo_earn ve settings.promo_redeem içinde döndürür. true, false veya null dışındaki bir değer 400 parameter_invalid yanıtını verir. İade, orijinal satırın yaptığını izler, bu yüzden orada promo gerekmez. Bu kuralı açmamış işletmeler alanı gönderebilir: yok sayılır.

İstek · POST /v1/checks/calculate
{
  "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 }
  ]
}
Yanıt · 200 (alıntı): cashback ile ödeme kapalı
{
  "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 }
  ],
  ...
}

Teslim bekleyen hediyeler

İşletme sahibi kuralları Hediyeler sayfasında belirler: toplam alışveriş için bir hediye (örneğin 5000 MDL, bir şişe şarap) veya bir cashback seviyesine ulaşma için. Bir fiş eşiği geçtiğinde veya misafiri o seviyeye taşıdığında hediye açılır ve misafiri bekler. Her misafir kural başına yalnızca bir kez hediye alır; bir fişin geçtiği birkaç eşik birkaç hediye açar. Kural açılmadan önce eşiği geçmiş misafirler bir şey almaz ve iade hediyeyi geri almaz. Hediyenin bekleme süresi olabilir; sonrasında hediye expired olur.

Kasa için akış: 1) POST /v1/checks/calculate, gifts.pending (zaten bekleyenler) ve gifts.unlocks (bu fişin açacakları, id: null ile) döndürür; display.cashier_text içindeki ilk satır hediyedir, kasiyere gösterin. 2) POST /v1/transactions, gifts.unlocked (bu fişin açtıkları, id ile) ve gifts.pending döndürür. 3) Kasiyer hediyeyi verir ve Hediye verildi düğmesine basar: POST /v1/members/{member}/gifts/{gift_id}/give çağırın. Member nesnesi de gifts.pending taşır. gift.unlocked ve gift.given olayları gönderilir. Hediyesi olmayan işletmeler gifts alanını hiç almaz ve hediye adresleri 404 endpoint_not_found döndürür.

Yanıt · POST /v1/checks/calculate (alıntı)
{
  "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", "..."]
  },
  ...
}
Yanıt · POST /v1/transactions (alıntı)
"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 ... ]
}
İstek · hediye verildi
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" }'

Damga modları

Varsayılan olarak damga programı fiş başına 1 damga verir. Mağaza sahibi bunu Program sayfasında değiştirebilir: seçilen kategorilerden ürün içeren fiş başına 1 damga veya seçilen kategorilerdeki her ürün birimi için 1 damga (tartılan ürün bir birim sayılır), ayrıca damga için en düşük fiş tutarı. Kategoriler line_items veya kataloğunuzdaki category kodlarıdır. Kategori modları POST /v1/transactions ve POST /v1/checks/calculate içinde line_items ister; satırsız fiş 1 damga verir, en düşük tutar her fişe uygulanır. stamps_earned fişin kaç damga verdiğini söyler; damgalar kart eşiğini birden fazla kez geçerse aynı anda birkaç ödül açılır ve calculate ayrıca rewards_unlocked döner. İptal, kalan damgaları tam olarak geri alır. Birim modunda fiş POST /v1/transactions/{external_id}/refunds ile satır satır iade edilebilir: iade edilen birimlerin damgaları geri alınır (gerekirse kullanılmamış ödüllerden, asla sıfırın altına inmeden) ve yanıt stamps_reversed içerir. Diğer damga fişleri yine iptal ile tamamen iade edilir. Damga modu olmayan işletmelerde fiş başına 1 damga kalır.

Kart okutulmalı

Bu kural açıkken bir kart için fiş, ziyaret, rezervasyon veya ödül yalnızca aynı anahtar o kartı kısa süre önce POST /v1/scans uç noktasına gönderdiyse kabul edilir. Kasada elle yazılan kart numarası scan_required ile reddedilir. Tarayıcının ham çıktısını /v1/scans uç noktasına gönderin, sonra her zamanki gibi devam edin.

Elle düzeltmeler

Varsayılan olarak kapalıdır. İşletme sahibi izin verdiğinde members:adjust iznine sahip bir anahtar, bir neden belirterek ve sahibin düzeltme başına belirlediği limite kadar cashback ekleyip düşebilir. Her düzeltme üyenin geçmişinde görünür ve balance.adjusted gönderir.

curl
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
Entegrasyonla ilgili sorularınız için: api@loyaltyfy.io. Bir iş günü içinde yanıt veriyoruz.