☰ Menü · İşlemler
API referansı

İşlemler

Kasanın gönderdiği kapanmış fiş. Kazandırır, cashback harcatabilir, iptal edilebilir.

İşlem nesnesi

external_idstring
Sizin fiş numaranız. İşletme bazında benzersizdir.
statusstring
completed veya voided.
amountinteger
Fiş toplamı, en küçük para biriminde.
redeem_amountinteger
Cashback ile ödenen kısım.
net_amountinteger
amount − redeem_amount.
cashback_earned, stamps_earnedinteger
Fişin kazandırdıkları.
reward_unlockedboolean
Bu fiş bir damga kartını tamamladı.
currency, register_id, closed_atstring
Gönderildiği gibi.
locationobject
Yalnızca fiş kendi kuralları olan bir şubeye düştüğünde: {id, name, store_code, register_id, matched_by}. matched_by değeri register_id veya store_id olur. Bkz. şube ve kasa nasıl gönderilir.
cashierobject
Yalnızca fiş cashier ile gönderildiyse: {id, name}.
membernesne
Fişten sonraki haliyle, yeni bakiyesiyle üye.
amount_refundedinteger
Şu ana kadar yapılan kısmi iadelerin toplamı.
line_itemsdizi
Fişin satırları ve her birinin yaptığı: amount (satırın fişteki payı), cashback_earned, earn_percent (kategori kazandırmıyorsa null), redeemable (cashback ile ödenebilir miydi) ve quantity_refunded. Fiş satırsız geldiyse boştur.
line_items[].promoboolean
Yalnızca kampanya kuralları olan işletmelerde: satırın kampanyadaki ürün olarak gönderilip gönderilmediği.
displaynesne
Misafirin dilinde, basılmaya hazır cashier_text ve receipt_lines.
POST/v1/transactions
İzin: transactions:write

Kapanmış bir fişi işler. Aynı external_id tekrar gönderilirse kayıtlı sonuç 200 ile döner. card_number ve gross_amount, member ve amount alanlarının eşdeğeri olarak kabul edilir.

external_idstring, zorunlu
Sizin fiş numaranız, en fazla 128 karakter.
memberstring, zorunlu
Kart numarası, okunan değer, seri numarası, üye id'si veya telefon.
amountinteger, zorunlu
Cashback düşülmeden önceki fiş toplamı, en küçük para biriminde, sıfırdan büyük.
redeem_amountinteger
Misafirin bu fişte kullandığı cashback. Varsayılan 0. Bakiye ve programın redeem_max_percent değeriyle sınırlıdır.
currencystring
ISO 4217. Varsayılan: programın para birimi.
closed_atdatetime
Fişin kapandığı zaman, saat dilimi farkıyla ISO 8601. Varsayılan: şimdi.
register_idstring
Kasanızın veya şubenizin id'si. Raporlarda gösterilir. İşletme sahibi bu kodu bir şubeye bağladıysa fiş o şubenin cashback kurallarına uyar.
store_idstring
Muhasebe sisteminizdeki mağaza (şube) kodu, en fazla 64 karakter. register_id yoksa veya hiçbir şubeye bağlı değilse kullanılır. İkisi farklı şubeleri gösterirse register_id kazanır. Bkz. şube ve kasa nasıl gönderilir.
cashierstring or object
Fişi kimin kestiği, kasanızın tanıdığı şekliyle: bir metin (ad veya kod) ya da {id, name}. Fişle birlikte saklanır ve cashier içinde döner. Cashback'i asla değiştirmez ve idempotency kontrolüne girmez. İşletme sahibinin kasiyer sinyalleri, şüpheli bir fişi kimin kestiğini göstermek için bunu kullanır.
hold_iduuid
redeem_amount göndermek yerine bu rezervasyonu onaylayın.
discount_typestring
Bu fişteki indirim kodunuz (employee, discount_card, promo), en fazla 64 karakter. İndirim türleri açıksa sahibin kuralları uygulanır. Bir satır da kendi discount_type alanını taşıyabilir.
line_items[].promoboolean
Ürün kampanyadaysa true. O zaman işletme sahibinin kampanya kuralları satırın kazandırıp kazandırmayacağına ve cashback ile ödenip ödenemeyeceğine karar verir. İşletme kuralı açmadıysa yok sayılır.
line_itemsdizi
En fazla 500 adet {sku, name, quantity, unit_price, category}. Ürün raporları için fişle birlikte saklanır ve kategori kurallarında kullanılır: cashback kazandırmayan, cashback ile ödenemeyen (kampanyalı ürünler) veya kendi yüzdesi olan kategori. category yoksa kategoriyi katalogdan sku ile buluruz. Satır yoksa fişin tamamı misafirin seviyesine göre kazandırır.

Şube ve kasa nasıl gönderilir

Her fişle (POST /v1/transactions), hesaplamayla (POST /v1/checks/calculate) ve rezervle (POST /v1/holds) iki isteğe bağlı metin gönderin: register_id kasanın kodudur, store_id muhasebe sisteminizdeki mağazanın (şubenin) kodudur, en fazla 64 karakter. İşletme sahibi iki kodu da Şubeler bölümüne girer. Şube önce register_id ile aranır; kasa kodu yoksa veya hiçbir şubeye bağlı değilse store_id ile. İkisi de gönderilir ve farklı şubeleri gösterirse register_id kazanır. Hiçbir şey eşleşmezse fiş genel kurallara göre hesaplanır ve bilinmeyen kodlar işletme sahibine "bağlanmamış" listesinde görünür. Kodlar, işletmede şube kuralları açıkken çalışır; aksi halde alanlar yok sayılır. Tek şube olsa bile her fişle iki alanı da gönderin.

İstek · POST /v1/transactions
{
  "external_id": "000131",
  "member": "2000111703779",
  "amount": 12550,
  "store_id": "122927",
  "register_id": "122930",
  "line_items": [
    { "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "category": "106" },
    { "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 5550 }
  ]
}

Bu durumda hesaplama ve işlemde, fişin hesaplandığı şubeyle bir location nesnesi bulunur: id, name, store_code, register_id ve matched_by (register_id veya store_id). Yanıtta location yoksa fiş genel kurallara göre hesaplanmıştır.

Yanıt · 201 (kısaltılmış)
{
  "object": "transaction",
  "external_id": "000131",
  "register_id": "122930",
  ...
  "location": {
    "object": "location",
    "id": "3c1f5a7e-2b9d-4e60-8f14-6a0d2c7b9e35",
    "name": "Store 1",
    "store_code": "122927",
    "register_id": "122930",
    "matched_by": "register_id"
  }
}
curl
curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CHK-2026-000123",
    "member": "2000111703779",
    "amount": 25000,
    "currency": "MDL",
    "register_id": "POS-1",
    "store_id": "S-1",
    "closed_at": "2026-10-06T18:17:00+03:00",
    "line_items": [
      { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee" },
      { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts" }
    ]
  }'
Yanıt · 201
{
  "object": "transaction",
  "id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
  "external_id": "CHK-2026-000123",
  "status": "completed",
  "amount": 25000,
  "redeem_amount": 0,
  "cashback_earned": 1250,
  "stamps_earned": 0,
  "reward_unlocked": false,
  "net_amount": 25000,
  "currency": "MDL",
  "register_id": "POS-1",
  "closed_at": "2026-10-06T15:17:00+00:00",
  "livemode": false,
  "created_at": "2026-10-06T18:17:17.921+00:00",
  "voided_at": null,
  "amount_refunded": 0,
  "line_items": [
    { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee", "amount": 8000, "earn_percent": 5, "cashback_earned": 400, "redeemable": true, "quantity_refunded": 0 },
    { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts", "amount": 17000, "earn_percent": 5, "cashback_earned": 850, "redeemable": true, "quantity_refunded": 0 }
  ],
  "member": {
    "object": "member",
    "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
    "card_number": "2000111703779",
    "cashback": { "balance": 1250, "currency": "MDL", "earn_rate": 5, ... },
    ...
  }
}
GET/v1/transactions/{external_id}
İzin: transactions:write

Fiş numaranıza göre tek bir işlemi döndürür.

POST/v1/transactions/{external_id}/void
İzin: transactions:write

Fişi geri alır: kazanılan cashback ve damgalar geri alınır, harcanan cashback iade edilir. İki kez iptal etmek zarar vermez.

curl
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
  -H "Authorization: Bearer sk_test_..."
Yanıt · 200
{
  "object": "transaction",
  "id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
  "external_id": "CHK-2026-000123",
  "status": "voided",
  "amount": 25000,
  "cashback_earned": 1250,
  "voided_at": "2026-10-06T18:17:21.003+00:00",
  "member": {
    "object": "member",
    "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
    "card_number": "2000111703779",
    "cashback": { "balance": 0, "currency": "MDL", "earn_rate": 5, ... },
    ...
  },
  ...
}
POST/v1/transactions/{external_id}/refunds
İzin: transactions:write

Cashback'li bir fişin bir kısmını amount veya line_items ile iade eder. Tutara göre cashback fişle orantılı hesaplanır. Satırlara göre cashback her satırın gerçekten kazandırdığını izler: hiçbir şey kazandırmayan kampanyalı ürün hiçbir şey geri almaz, misafirin harcadığı cashback ise yalnızca onunla ödenebilen satırlar için geri gelir. İadenin kendi external_id değerini gönderin; tekrarlamak güvenlidir. Bir fişe birden fazla iade yapılabilir; sonuncusu kalanları tam kapatır. Damga ve ziyaret programlarının fişleri iptalle bütün olarak iade edilir.

external_idstring, zorunlu
Bu iadenin sizdeki id'si, en fazla 128 karakter.
amountinteger
İade edilen tutar, en küçük birimle. İade edileni line_items anlatıyorsa göndermeyin.
line_itemsdizi
İade edilen satırlar: fişteki gibi {sku, quantity} veya {name, quantity}. Zaten iade edilen birimler sayılır; fazlasını istemek refund_exceeds_line ve refundable ile yanıtlanır. Satırsız gönderilen fiş no_line_items yanıtı verir: onu tutara göre iade edin.
line_items[].promoboolean
Kabul edilir ve yok sayılır: iade, orijinal satırın kazandırdığını ve ödeyebildiğini izler.
register_idstring
Kasanızın id'si, kasa bazlı numaralandırma için.
store_idstring
Mağaza kodunuz. Fişle tutarlılık için kabul edilir; iade, asıl fişin şubesine göre yapılır.
curl
# the guest returns 50.00 of a 200.00 check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000124/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000017", "amount": 5000 }'

# or: the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000018", "line_items": [{ "sku": "1001", "quantity": 1 }] }'

# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back
Yanıt · 201
{
  "object": "refund",
  "id": "c41d2f7a-3b9e-4c11-8e0f-6a2d5b7c9e13",
  "external_id": "RET-2026-000017",
  "transaction": "CHK-2026-000124",
  "amount": 5000,
  "cashback_reversed": 200,
  "redeem_restored": 1000,
  "line_items": [],
  "livemode": false,
  "created_at": "2026-10-06T18:40:02.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 5000, "member": { ... }, ... }
}

// by lines
{
  "object": "refund",
  "external_id": "RET-2026-000018",
  "transaction": "CHK-2026-000130",
  "amount": 4500,
  "cashback_reversed": 450,
  "redeem_restored": 0,
  "line_items": [
    { "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
  ],
  ...
}
POST/v1/transactions/{external_id}/returns
İzin: transactions:write

Bir fişin bir veya birkaç satırını iade eder: misafir üç üründen birini geri getirir. Bu satırlarda kazanılan cashback geri alınır, onları ödediği cashback ise geri verilir; her satırın gerçekten kazandırdığına ve neyle ödenebildiğine göre, asla fişle orantılı değil. Yanıt, object: "return" ile iadeyle aynı nesnedir. İadenin kendi external_id değerini gönderin; tekrarlamak güvenlidir. line_items olmadan gönderilen fişler satır bazında iade edilemez: onları amount ile iade edin.

external_idstring, zorunlu
Bu iadenin sizdeki id'si, en fazla 128 karakter.
line_itemsdizi, zorunlu
İade edilen satırlar: fişteki gibi {sku, quantity} veya {name, quantity}. Zaten iade edilen birimler sayılır; fazlasını istemek refund_exceeds_line ve refundable ile yanıtlanır.
line_items[].promoboolean
Kabul edilir ve yok sayılır: iade, orijinal satırın kazandırdığını ve ödeyebildiğini izler.
register_idstring
Kasanızın id'si, kasa bazlı numaralandırma için.
store_idstring
Mağaza kodunuz. Fişle tutarlılık için kabul edilir; iade, asıl fişin şubesine göre yapılır.
curl
# the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/returns \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000019", "line_items": [{ "sku": "1001", "quantity": 1 }] }'

# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back
"Yanıt · 201"
{
  "object": "return",
  "id": "9f1c2b8e-5d7a-4e3f-9b21-0c4d6e8f1a23",
  "external_id": "RET-2026-000019",
  "transaction": "CHK-2026-000130",
  "amount": 4500,
  "cashback_reversed": 450,
  "redeem_restored": 0,
  "line_items": [
    { "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
  ],
  "livemode": false,
  "created_at": "2026-11-06T09:12:40.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 4500, "line_items": [ ... ], "member": { ... }, ... }
}
GET/v1/transactions
İzin: transactions:write

İşlemleri en yeniden eskiye listeler. ?member= ile filtreleyin. Sayfalıdır.

Entegrasyonla ilgili sorularınız için: api@loyaltyfy.io. Bir iş günü içinde yanıt veriyoruz.