Stok

Ürün veya varyant stoğunu tekli ya da bulk olarak senkronize edin.

Endpointler

GET/inventory/{product}Stok oku

PATCH/inventory/{product}Stok güncelle

PATCH/inventory/bulkToplu stok güncelle

Inventory API ne işe yarar?

ERP veya depo sisteminizdeki stok miktarını BYNovax mağazasına senkronize etmek için kullanılır.

Tek ürün stoğunu okuyabilir, tek ürün stoğunu güncelleyebilir veya bulk endpoint ile birçok stok değişikliğini tek request içerisinde gönderebilirsiniz.

Endpointler ve scope'lar

Endpoint	Scope
GET /inventory/{product}	inventory:read
PATCH /inventory/{product}	inventory:write
PATCH /inventory/bulk	inventory:write

Tek ürün stok okuma

GET /inventory/{product} ürünün mevcut stok bilgisini döndürür. Response inventory objesinde product_id, product_uid, sku, has_variants, stock ve updated_at gibi stok authority alanları bulunabilir.

Tek ürün stok güncelleme

PATCH işlemi Idempotency-Key gerektirir.

Alan	Tip	Kural
stock	integer	Zorunlu ve 0 veya daha büyük

Varyantlı ürün davranışı

Ürün varyantlıysa toplam ürün stoğunu doğrudan ürün seviyesinde değiştirmek doğru değildir. Böyle bir durumda API variant-level inventory endpointini kullanmanızı isteyebilir ve 409 döndürebilir.

Bulk stok güncelleme

Çok sayıda stok değişikliğini tek tek HTTP çağrısı yapmak yerine bulk endpoint üzerinden gönderebilirsiniz.

Bulk request en fazla 500 item kabul edecek şekilde tasarlanmıştır. Her item product_id, gerekiyorsa variant_id ve stock değerini taşır.

{
  "items": [
    {
      "product_id": 7314,
      "stock": 20
    },
    {
      "product_id": 7315,
      "variant_id": 3623,
      "stock": 8
    }
  ]
}

ERP senkronizasyon modeli

Depoda stok değişti
        ↓
ERP ilgili product / variant eşlemesini buldu
        ↓
Yeni stok miktarı belirlendi
        ↓
PATCH inventory veya PATCH inventory/bulk
        ↓
Başarılı response alındı
        ↓
ERP son senkronizasyon zamanını kaydetti

Sık karşılaşılan sorunlar

Sorun	Çözüm
403	inventory:write scope kontrol edin
404	Product tenant kapsamına ait mi kontrol edin
409	Ürün varyantlı mı kontrol edin
422	stock integer ve negatif değil mi kontrol edin
Timeout	Aynı request için aynı Idempotency-Key ile retry edin

Çalıştığını nasıl doğrularım?

PATCH sonrası başarılı response alındı.
GET /inventory/{product} yeni stok değerini gösteriyor.
Varyantlı ürünlerde variant endpointi kullanılıyor.
Bulk işleminde başarısız item'lar ayrıca değerlendiriliyor.

Inventory authoritative state modeli

Inventory endpointleri BYNovax stok write authority'sidir. Product lifecycle veya bulk product lifecycle endpointlerine stok değişikliği yüklemeyin.

ERP stok sistemi kaynak sistem ise BYNovax'a yalnız yeni authoritative stok değerini gönderin; response sonrasında başarılı senkronizasyon zamanını kaydedin.

Bulk inventory entegrasyon kuralları

Tek bulk request mevcut contracta göre en fazla 500 item taşımalıdır.
Her item doğru product_id ve gerekiyorsa variant_id eşlemesini kullanmalıdır.
Varyantlı ürünlerde varyant stoğunu ürün seviyesinde zorlamayın.
Bulk write için benzersiz Idempotency-Key kullanın.
Response içinde item bazlı başarısızlık bilgisi varsa yalnız HTTP status koduna bakarak tüm batch'i başarılı kabul etmeyin.
Başarısız item'ları ayrı retry kuyruğuna almak duplicate-safe entegrasyon için daha güvenlidir.

Inventory reconciliation

ERP stok state
        ↓
BYNovax product / variant ID eşlemesi
        ↓
PATCH inventory veya inventory/bulk
        ↓
Response doğrulama
        ↓
Gerekirse GET /inventory/{product}
        ↓
ERP sync checkpoint güncelle