☰ Menü · İşlemler
İş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
completedveyavoided.- 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_bydeğeriregister_idveyastore_idolur. Bkz. şube ve kasa nasıl gönderilir. - cashierobject
- Yalnızca fiş
cashierile 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) vequantity_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_textvereceipt_lines.
/v1/transactionsKapanmış 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_percentdeğ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_idyoksa veya hiçbir şubeye bağlı değilse kullanılır. İkisi farklı şubeleri gösterirseregister_idkazanı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 vecashieriç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_amountgö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 kendidiscount_typealanı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.categoryyoksa kategoriyi katalogdanskuile 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.
{
"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.
{
"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 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" }
]
}'{
"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, ... },
...
}
}/v1/transactions/{external_id}Fiş numaranıza göre tek bir işlemi döndürür.
/v1/transactions/{external_id}/voidFişi geri alır: kazanılan cashback ve damgalar geri alınır, harcanan cashback iade edilir. İki kez iptal etmek zarar vermez.
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
-H "Authorization: Bearer sk_test_..."{
"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, ... },
...
},
...
}/v1/transactions/{external_id}/refundsCashback'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_itemsanlatı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ı istemekrefund_exceeds_lineverefundableile yanıtlanır. Satırsız gönderilen fişno_line_itemsyanı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.
# 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{
"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 }
],
...
}/v1/transactions/{external_id}/returnsBir 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ı istemekrefund_exceeds_lineverefundableile 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.
# 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{
"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": { ... }, ... }
}/v1/transactionsİşlemleri en yeniden eskiye listeler. ?member= ile filtreleyin. Sayfalıdır.