Yazarkasanız siparişleri okusun.

Kullandığınız yazarkasa, muhasebe ya da adisyon programı QRSystema'daki siparişleri okumak istiyorsa bir API anahtarına ihtiyacı vardır. Anahtarı panelden siz oluşturur, entegrasyonu yapan firmaya verirsiniz. Bu sayfa hem sizin hem de firmanın yazılımcısı içindir: önce işletme sahibi adımları, sonra teknik ayrıntılar.

1. Anahtar oluşturun

1. Panelde Kasa & Cihazlar → Program bağlantısı sayfasını açın.
2. Anahtar oluştur düğmesine basın. Bağlantı adı alanına hangi sistem için verdiğinizi yazın (“Yazarkasa”). Bildirim adresi isteğe bağlıdır; boş bırakıp sonradan da girebilirsiniz.
3. Oluşturunca ekranda iki değer çıkar: Anahtar ve İmza sırrı (imza sırrı, bildirim kullanmayacaksanız da üretilir). İkisi de yalnızca bir kez gösterilir. Kopyala düğmesiyle kopyalayıp firmaya güvenli bir kanalla iletin.

Sayfadan ayrıldıktan sonra bu değerleri bir daha göremezsiniz; sistemde yalnız şifrelenmiş özet saklanır. Kaybederseniz yeni anahtar oluşturun. En fazla 10 anahtar tanımlayabilirsiniz; kullanmadıklarınızı silin. İstediğiniz an bir bağlantıyı Durdurabilir ya da silebilirsiniz; silince o anahtarı kullanan sistem bağlantısını kaybeder. “DoyHadi” adı DoyHadi bağlantısına ayrılmıştır, anahtara başka bir ad verin.

2. Bağlantıyı deneyin

Firmanın yazılımcısı (ya da siz) anahtarı bir istek başlığıyla gönderir. Kimlik doğrulama için X-API-Key başlığı ya da Authorization: Bearer biçimi kabul edilir:

curl -H "X-API-Key: qrs_xxxxxxxx" https://qrsystema.com/api/v1/me

İşletme bilgisi dönerse bağlantı çalışıyor demektir. Bağlantılar tablosunda anahtarın “Son kullanım” sütunu da güncellenir.

3. Okuma uçları

Adres	Ne döner
GET /api/v1/me	İşletme bilgisi, bağlantı testi için.
GET /api/v1/menu	Kategoriler, ürünler, porsiyonlar, ilaveler ve fiyatlar.
GET /api/v1/products/{id}	Tek ürün.
GET /api/v1/tables	Masa durumu: açık masalar ve birikmiş tutarlar.
GET /api/v1/orders	Masa siparişleri. ?status=open|pending|approved|closed|cancelled|all
GET /api/v1/orders/{id}	Tek sipariş, kalem kalem.
GET /api/v1/delivery-orders	Eve siparişler.
GET /api/v1/sales/summary	Gün sonu: masa ve paket cirosu, nakit/kart dağılımı.

Sınırlar: anahtar başına dakikada 120 istek (aşılırsa 429 döner); listeler page ve pageSize ile sayfalanır, varsayılan 50, en çok 200. Tarih süzgeci from ve to alır; saat dilimi yazılmazsa işletme saati, sonuna Z koyarsanız UTC kabul edilir. Sipariş tutarı için total alanı esas alınmalıdır: tutar sunucudaki güncel menü fiyatlarına göre hesaplanır.

4. Bildirimleri (webhook) açın

Dış sistemin sürekli sorgu atmasına gerek kalmadan olaylar ona gönderilsin istiyorsanız bağlantının Bildirim adresi alanına bir https adresi yazıp kaydedin. Bağlantı satırındaki Deneme bildirimi gönder düğmesi bir deneme bildirimi (test.ping) gönderir. Olaylar:

Olay	Ne zaman
order.created	Masadan yeni sipariş düştüğünde.
order.updated	Açık masaya yeni kalem eklendiğinde.
order.status_changed	Sipariş onaylandığında ya da iptal edildiğinde.
bill.requested	Masa hesap istediğinde.
bill.closed	Hesap kapandığında; ödeme türü ve tutar yer alır.
delivery.created / delivery.status_changed	Eve sipariş geldiğinde ve durumu ilerlediğinde.

Gövde şu alanları taşır: id, event, occurredAt, restaurantId, data.

5. Bildirimin imzasını doğrulayın

Her bildirimde üç başlık gelir: X-QRS-Event (olay adı), X-QRS-Delivery (bildirim kimliği) ve X-QRS-Signature. İmza başlığı t=1789045462,v1=9c1f… biçimindedir. Doğrulama adımları:

1. Başlıktaki t (zaman damgası) ve v1 (imza) değerlerini ayırın.
2. İmzalanan metni kurun: t değeri, bir nokta ve gövdenin ham hâli. JSON'u ayrıştırıp yeniden yazmayın; gövde bayt bayt aynı kalmalıdır.
3. Bu metnin HMAC-SHA256 özetini, imza sırrınızı anahtar olarak kullanarak hesaplayın ve küçük harfli onaltılık yazıya çevirin.
4. Sonucu v1 ile karşılaştırın (mümkünse sabit zamanlı karşılaştırmayla).
5. Zaman damgası 5 dakikadan eskiyse isteği reddedin.

import hmac, hashlib, time

def dogrula(sir, imza_basligi, ham_govde):   # ham_govde: bayt
    p = dict(x.split("=", 1) for x in imza_basligi.split(","))
    metin = (p["t"] + ".").encode() + ham_govde
    beklenen = hmac.new(sir.encode(), metin, hashlib.sha256).hexdigest()
    return hmac.compare_digest(beklenen, p["v1"]) and abs(time.time() - int(p["t"])) <= 300

Karşı adresiniz 10 saniye içinde 2xx yanıt vermelidir; ağır işleri yanıttan sonra yapın. Yönlendirme (3xx) izlenmez. Aynı bildirim iki kez ulaşabilir: id ve X-QRS-Delivery yeniden denemede değişmez, bu değeri kaydedip tekrarı yok sayın. Yeniden deneme kuralları SSS'te anlatılmıştır. İmza sırrını kaybettiyseniz Sırrı yenile düğmesiyle yenisini üretin ve hemen dış sisteme girin; eski sır geçersiz olur.

6. Yazarkasa firmasına ne söyleyeceksiniz

• API salt okunurdur; sipariş ve ciro verisini okuyabilir.
• Kimlik doğrulama başlığı ve dakikada 120 istek sınırı.
• İsterlerse bildirim adresi ve imza doğrulama; yoksa belirli aralıklarla /api/v1/orders sorgulayabilirler.
• Anahtarı iş bittiğinde silmeniz ya da durdurmanız gerekir.

QRSystema mali yazarkasa değildir ve mali belge üretmez. Bu işi yazarkasa yazılımı yapar; API yalnız ona siparişleri verir.

Sık yapılan hatalar

Hata	Çözüm
401 “anahtar_gecersiz”	Anahtar yanlış kopyalanmış, durdurulmuş ya da silinmiş. Yeni anahtar oluşturun.
429 “cok_fazla_istek”	Dakikada 120 isteği aştınız; sorgu sıklığını azaltın ya da bildirim kullanın.
Anahtarı kaybettim	Tekrar gösterilemez. Yeni anahtar oluşturup eskisini silin.
Bildirim imzası tutmuyor	Gövdeyi ayrıştırıp yeniden yazmayın; ham gövdeyi ve yeni sırrı kullanın.
Bildirim hiç gelmiyor	Adres https olmalı ve 10 saniyede 2xx dönmeli. Satırdaki “Deneme bildirimi gönder” düğmesiyle deneyin.
Anahtarı herkese verdim	Anahtar sipariş ve ciro verinizi okur. Yalnız güvendiğiniz firmaya verin, işi bitince silin.

Daha fazlası için sık yapılan hatalar ve çözümleri sayfasına bakın.

Kontrol listesi

• Anahtar yalnız bir kez gösterildi, kopyalanıp güvenli iletildi.
• İsteğe bağlı bildirim adresi https ve 10 saniyede 2xx dönüyor.
• /api/v1/me ile bağlantı denendi.
• İmza doğrulaması ham gövde ve zaman damgası kontrolüyle yapılıyor.
• Tekrar eden bildirimler id ile ayıklanıyor.
• Kullanılmayan anahtarlar silindi.

Özelliğin genel anlatımı için API ve yazarkasa bağlantısı sayfasına bakabilirsiniz.

Sık sorulanlar