Entegrasyon Akışları

Bu sayfada sık kurulan üç entegrasyonun baştan sona akışı anlatılır. Uçların ayrıntıları ilgili sayfalardadır.

1. ERP'den stok ve fiyat gönderme

Amaç: ERP'deki stok ve fiyat değiştikçe mağazaya yansısın.

Anahtar izinleri: products:read, stock:write

1. Ürünleri barkod ya da stok kodu ile eşleştirin. ERP'deki stok kodunun mağazadaki sku ile, ya da barkodun barcode ile aynı olması yeterlidir. Mağazadaki ürünlerin stok kodlarını Ürün Listesi ile çekip kontrol edebilirsiniz.
2. Belirli aralıklarla (örneğin 5 dakikada bir) son turdan beri değişen ürünleri toplayın.
3. Bunları 1.000'lik parçalar halinde Toplu Stok ve Fiyat ucuna gönderin:

{
  "items": [
    { "barcode": "8690000000017", "quantity": 25, "price": 249.90 },
    { "sku": "KUPA-500", "quantity": 0 }
  ]
}

4. Yanıttaki failed kalemleri kaydedin. Bunlar mağazada bulunmayan ya da barkodu birden fazla üründe kayıtlı ürünlerdir. Mağaza yöneticisinin bu ürünleri düzeltmesi gerekir.

Fiyatları KDV dahil gönderin. Yalnız stok gönderen bir tur fiyatı değiştirmez.

2. Siparişleri ERP'ye ya da depo yazılımına alma

Amaç: Ödemesi alınan siparişler sisteminize düşsün. Kargolama ve teslim bilgisi mağazaya geri yazılsın.

Anahtar izinleri: orders:read, orders:write

1. Her 1–5 dakikada bir GET /orders?updatedFrom=... ile yeni ve değişen siparişleri çekin (önerilen döngü).
2. Siparişi id ile eşleştirin. Yeni ise ekleyin, varsa durumunu güncelleyin.
3. Hangi siparişlerin hazırlanacağına status ile karar verin:
   • Processing: ödeme alındı (ya da kapıda ödemeli sipariş onaylandı). Hazırlamaya başlayın.
   • AwaitingPayment: havale bekleniyor. Henüz göndermeyin.
   • Cancelled: iptal edildi. Hazırlamayı durdurun.
4. Hazırlamaya başlayınca preparing, kargoya verince takip numarasıyla shipped gönderin (Sipariş Durumu). Müşteri kargo e-postasını takip numarasıyla alır.
5. Kargo teslim edince delivered gönderin. Kapıda ödemeli siparişlerde tahsilat bu adımda kaydedilir.
6. Fatura keserken discountTotal, installmentFee ve paymentFee tutarlarını hesaba katın. Fatura bilgilerini billingAddressJson alanından alın.

3. Ürün kataloğunu dışarıdan yükleme

Amaç: Tedarikçi ya da ERP kataloğunu mağazada ürün olarak açmak ve güncel tutmak.

Anahtar izinleri: products:read, products:write, categories:read, categories:write

1. Kategorileri açın: kök kategoriler için POST /categories gönderin ve dönen id ile alt kategorileri açın. Aynı ad tekrar gönderildiğinde mevcut kategori döner, bu yüzden her senkronda güvenle çağırabilirsiniz.
2. Markaları POST /brands ile açın.
3. Her ürün için önce GET /products?sku=... ile mağazada olup olmadığına bakın:
   • Yoksa POST /products ile açın (stok kodu, kategori, marka ve görsellerle).
   • Varsa PUT /products/{id} ile yalnızca değişen alanları güncelleyin.
4. Sonraki senkronlarda stok ve fiyat için Toplu Stok ve Fiyat ucunu kullanın. Ürün başına istek göndermeyin.

Genel öneriler

• Her entegrasyona ayrı bir API anahtarı verin ve yalnızca gereken izinleri seçin.
• Bütün tarihleri UTC olarak saklayın ve gönderin.
• 429 ve 5xx yanıtlarında bekleyip tekrar deneyin. 400 yanıtını değiştirmeden tekrar göndermeyin.
• Hata kayıtlarınıza isteğin adresini, zamanını ve yanıttaki code değerini yazın. Destek istediğinizde bu bilgiler sorunu hızla bulmamızı sağlar.