Yazarkasa Webhook API entegrasyonu nasıl yapılır?

Kısa Yanıt

Yazarkasa Webhook API entegrasyonu için önce KOBİ GO'da POS cihazınızı ekleyin ve cihaz için oluşturulan API anahtarını alın. Ardından cihazınızı veya entegrasyon yazılımınızı, her fiş kesildiğinde KOBİ GO Webhook URL'sine JSON POST gönderecek şekilde yapılandırın. API anahtarını X-POS-Api-Key başlığıyla isteğe ekleyin.

Yazarkasa Webhook API Nedir?

Webhook API, yazarkasa veya POS sisteminizde oluşan fiş bilgilerinin KOBİ GO'ya aktarılmasını sağlayan entegrasyon yöntemidir. Yazarkasanız doğrudan veya kullandığınız entegrasyon yazılımı aracılığıyla KOBİ GO'nun belirlediği veri yapısında fiş bilgilerini gönderebilir.

Entegrasyon İçin İlk Olarak Ne Yapılmalıdır?

1. 1

   Hızlı Satış Ayarları'nı açın

   KOBİ GO'da Ayarlar → Hızlı Satış Ayarları bölümüne gidin.

2. 2

   POS Cihazları bölümünü açın

   POS Cihazı Entegrasyonu alanına ilerleyin.

3. 3

   Cihazınızı ekleyin

   Yeni cihaz butonunu kullanarak yazarkasa veya POS cihazınızı tanımlayın.

4. 4

   API anahtarını alın

   Eklediğiniz cihaz için oluşturulan API anahtarını entegrasyon yazılımınızda kullanmak üzere alın.

5. 5

   Webhook adresini kullanın

   POS Cihazları bölümünde gösterilen Webhook URL'yi cihaz veya entegrasyon yazılımınıza tanımlayın.

Webhook URL

KOBİ GO Hızlı Satış Ayarları ekranında yazarkasa entegrasyonu için kullanılacak Webhook URL görüntülenir. Bu adresi yanındaki Kopyala butonuyla kopyalayarak entegrasyon yazılımınızda kullanabilirsiniz.

API Anahtarı Nasıl Gönderilir?

Cihaz için KOBİ GO tarafından oluşturulan API anahtarı, Webhook isteğinin X-POS-Api-Key başlığında gönderilir. Böylece istek ilgili cihaz entegrasyonuyla birlikte işlenebilir.

• İstek yöntemi: POST
• Veri formatı: JSON
• Content-Type: application/json
• API anahtarı başlığı: X-POS-Api-Key
• Hedef: KOBİ GO Hızlı Satış Ayarlarında gösterilen Webhook URL

Webhook İsteğinde Hangi Alanlar Gönderilir?

KOBİ GO Entegrasyon Rehberi'nde fiş aktarımı için receipt_no, paid_at, payment_method, subtotal, discount, total ve items alanları gösterilir.

receipt_no

receipt_no, fiş veya Z numarasını taşır ve entegrasyon ekranında zorunlu alan olarak belirtilir.

paid_at

paid_at, işlemin tarih ve zaman bilgisini ISO tarih formatında taşımak için kullanılır. Entegrasyon ekranında bu alan opsiyonel olarak belirtilir; gönderilmezse şu an bilgisi kullanılır.

payment_method

payment_method, satışın ödeme yöntemini belirtir. Entegrasyon Rehberi'nde desteklenen değerler cash, card ve credit olarak gösterilir.

• cash — nakit
• card — kart
• credit — kredili/veresiye ödeme

subtotal, discount ve total

subtotal, discount ve total alanları satışın tutar bilgilerini taşır. Bunlar sırasıyla ara toplam, indirim ve toplam satış tutarının aktarılmasında kullanılır.

items[]

items dizisi fişteki satış kalemlerini taşır. KOBİ GO Entegrasyon Rehberi'nde her satış kalemi için name, qty ve price alanlarının gönderilmesi gerektiği belirtilir.

• name — ürün veya satış kaleminin adı
• qty — satış miktarı
• price — fiyat

Örnek JSON Yapısı

Bir fiş gönderiminde veri yapısı; fiş numarası, tarih, ödeme yöntemi, tutarlar ve satış kalemlerinden oluşur. Entegrasyon yazılımınız kendi yazarkasanızdan aldığı bilgileri KOBİ GO'nun bu alanlarına dönüştürerek göndermelidir.

Farklı Yazarkasa Markaları Nasıl Entegre Edilir?

Farklı yazarkasa markalarının veri yapıları birbirinden farklı olabilir. KOBİ GO Entegrasyon Rehberi'nde farklı yazarkasa markaları için adapter mimarisinin mevcut olduğu belirtilir. Kendi entegratörünüz cihazdan gelen veriyi KOBİ GO'nun beklediği şemaya normalize ederek Webhook API'ye gönderebilir.

1. 1

   Yazarkasadan veriyi alın

   Entegrasyon yazılımınız satış ve fiş bilgilerini cihazın desteklediği yöntemle alır.

2. 2

   Alanları eşleştirin

   Cihazdaki fiş alanlarını receipt_no, paid_at, payment_method, tutar alanları ve items yapısıyla eşleştirin.

3. 3

   Veriyi normalize edin

   Yazarkasadan gelen yapıyı KOBİ GO'nun beklediği JSON yapısına dönüştürün.

4. 4

   API anahtarını ekleyin

   İlgili cihaz için oluşturulan anahtarı X-POS-Api-Key başlığına ekleyin.

5. 5

   Webhook'a POST gönderin

   Hazırlanan JSON verisini KOBİ GO panelinde gösterilen Webhook URL'ye gönderin.

Webhook'tan Gelen Fişe Ne Olur?

KOBİ GO Entegrasyon Rehberi'ne göre Webhook üzerinden gelen fiş otomatik olarak siparişe dönüşür. Sonraki stok, muhasebe ve rapor işlemleri Hızlı Satış Ayarlarında etkinleştirdiğiniz seçeneklere göre uygulanır.

• Fiş KOBİ GO'ya aktarılır.
• Gelen fiş siparişe dönüşür.
• Otomatik stok düşümü açıksa stok bakiyesi azalır.
• Muhasebeye otomatik kayıt açıksa tamamlanan satış gelir olarak muhasebeye yansır.
• Günlük rapora ekle açıksa satış günlük Z raporuna dahil edilir.

Entegrasyonu Devreye Almadan Önce Kontrol Edin

• POS cihazının KOBİ GO'da tanımlandığını kontrol edin.
• Doğru cihaza ait API anahtarını kullandığınızdan emin olun.
• İsteğin POST yöntemiyle gönderildiğini kontrol edin.
• Content-Type değerinin application/json olduğunu kontrol edin.
• API anahtarının X-POS-Api-Key başlığında gönderildiğini kontrol edin.
• receipt_no alanının gönderildiğini kontrol edin.
• items dizisindeki name, qty ve price alanlarının bulunduğunu kontrol edin.
• payment_method kullanıyorsanız beklenen değerlerden birini gönderdiğinizi kontrol edin.

Fiş KOBİ GO'ya Ulaşmıyorsa

Fiş gönderimi gerçekleşmiyorsa öncelikle Webhook URL'yi, X-POS-Api-Key başlığını, cihaz API anahtarını ve gönderilen JSON yapısını kontrol edin. Zorunlu alanların eksik olmadığından ve isteğin doğru adrese POST olarak gönderildiğinden emin olun.

Entegrasyon Güvenliği

Cihaz API anahtarı entegrasyon için kullanılan özel bir erişim bilgisidir. Anahtarı yalnızca yetkili entegrasyon ortamında saklayın ve istemciye açık alanlarda paylaşmayın.