Mekante Geliştirici

Kasa akışı

Müşteri sadakat kartını telefonundaki cüzdan uygulamasında açar ve bir QR kod gösterir. Kasa yazılımın bu kodu okur ve aşağıdaki adımları izler.

QR okut ──► POST /scan ──► (puan önizle) ──► POST /earn      puan yaz
                      └──────────────────► POST /redeem    ödül düş

Puan yazma

  1. QR'ı okut. Kodun içeriği bir metindir (token). Bunu POST /scan ile gönder. Yanıttaki scanId ve üye bilgisi (ad, maskeli telefon, bakiye, seviye) ekranda gösterilebilir.
  2. İstersen önizle. POST /earn/preview ile tutara göre kaç puan yazılacağını göster. Bu istek hiçbir şey kaydetmez.
  3. Puanı yaz. POST /earn ile scanId ve tutarı gönder. Idempotency-Key başlığı zorunludur.

Ödül düşme

Ödül düşmenin iki yolu vardır:

  1. Kasiyer seçer. Müşterinin normal QR kodunu POST /scan ile okut. Yanıtın rewards alanı müşterinin alabileceği (ve alamayacağı, nedeniyle birlikte) ödülleri listeler. Kasiyer birini seçer; POST /redeem ile scanId ve seçilen rewardId'yi gönder.
  2. Müşteri seçer. Müşteri uygulamada bir ödül seçer ve o ödül için ayrı bir QR üretir. Aynı şekilde POST /scan ile okut: yanıttaki intent değeri redeem olur ve reward alanında ödül görünür. Bu durumda rewardId göndermen gerekmez; gönderirsen aynı ödül olmalıdır (400 REWARD_MISMATCH).

Yanıtta müşteriye verilecek 6 karakterlik code döner. Müşteriye anında "ödül kullanıldı" bildirimi gider ve işlemi yapan kasiyer kayda yazılır. Bir kasiyer ya da API anahtarı günde en fazla işletmenin belirlediği sayıda ödül kullandırabilir (429 CASHIER_DAILY_LIMIT).

Önemli kurallar

QR kodun ömrü 30 saniyedir. Süresi dolan kod QR_EXPIRED hatası verir. Müşteriden ekranı yenilemesini iste.

Her QR yalnızca bir kez okutulabilir. İkinci okutma 409 QR_ALREADY_USED döner. Bu, kodun fotoğrafının çekilip tekrar kullanılmasını engeller.

Okutma 5 dakika geçerlidir. POST /scan başarılı olduktan sonra scanId ile puan yazma ya da ödül düşme için 5 dakikan vardır. Süre dolarsa ya da scanId kullanıldıysa 409 SCAN_INVALID döner; kodu yeniden okut. Sayfa yenilense bile okutmayı GET /scans/:id ile tekrar okuyabilirsin.

Tutar kuruş cinsinden bir tam sayıdır. 15000 = 150 TL. Ondalık ya da sıfır/negatif değer reddedilir. En fazla 100000000 gönderilebilir; işletmenin kendi üst sınırı daha düşük olabilir (Limitler).

Idempotency-Key: aynı satışı iki kez yazma

Ağ kesilirse isteğin işlenip işlenmediğini bilemezsin. Aynı isteği aynı Idempotency-Key ile tekrar gönderirsen puan ikinci kez yazılmaz; ilk yanıt replayed: true ile döner.

  • Anahtarı satış başına bir kez üret ve satışa bağla (örneğin fiş numarasından: pos-2026-000123).
  • Uzunluğu 8 ile 100 karakter arasında olmalı.
  • Aynı anahtarı başka bir işlem için kullanırsan 409 DUPLICATE_REQUEST alırsın.
  • Aynı satış için receiptNo göndermek ek bir koruma sağlar: aynı fiş numarası ikinci kez yazılmaz (409 DUPLICATE_RECEIPT).
İlk istek     → 201 Created      "replayed": false
Yeniden dene  → 200 OK           "replayed": true  (aynı kayıt, ikinci puan yok)

Yanlış girişi geri alma

POST /ledger/:id/void bir puan kazanımını ya da ödül kullanımını geri alır. API anahtarı kasiyer gibi çalıştığı için yalnızca kendi girişlerini ve ilk 15 dakika içinde iptal edebilir. Kazanılan puanlar bu arada harcandıysa iptal edilemez (409 POINTS_ALREADY_SPENT).