WMS / Depo Sistemini Bağlama

WMS akışının hangi parçaları bugün API'de mevcut, hangileri yakında geliyor:

İşletmenizin planı apiAccess içermelidir (aksi halde çağrılar 402 döner). Kokpit → Ayarlar → API & Webhook → Yeni API Key ile anahtar üretin. WMS için yeterli granüler yetkiler: orders:read ve webhooks:manage (gerekirse products:read, shipping:read). En az ayrıcalık ilkesiyle yalnız gerekeni seçin. Ham anahtar (sk_live_…) yalnız bir kez gösterilir; güvenli saklayın.

Her isteği temel URL'e, API anahtarınızı X-API-Key başlığında göndererek yapın. Anahtar gövdede veya sorgu parametresinde gönderilmez.

Base: https://api.stokzone.com/api/v1/web-api/v1
Header: X-API-Key: sk_live_xxxxxxxxxxxx

Siparişleri sayfalı olarak çekin: platform ve status ile filtreleyin; limit (en fazla 200) ve offset ile sayfalayın. Yanıt items, total, page ve page_size alanlarını içerir; siparişler order_date azalan sıralıdır.

curl -H "X-API-Key: $KEY" \
  "https://api.stokzone.com/api/v1/web-api/v1/orders?status=Created&platform=trendyol&limit=200&offset=0"

Not: Sürdürülebilir artımlı çekme için aşağıdaki `since` imlecini kullanın — `limit/offset` sayfalama, araya yeni sipariş girince kayar ve sınırdaki kaydı atlar. Değişiklikleri gerçek zamanlı yakalamak için webhook (aşağıda); toplu mutabakat için offset ile tam tarama yapın.

`limit/offset` ile sayfalama, araya YENİ sipariş girdiğinde kayar ve sayfa sınırındaki kaydı atlar — üstelik atladığını fark etmezsin. Sürdürülebilir çekme için `since` kullan: yanıttaki `next_since` ve `next_since_id` değerlerini sakla, bir sonraki çağrıda aynen geri gönder.

# 1) ilk cagri — imlecsiz
curl -H "X-API-Key: $KEY" ".../orders?limit=200"

# 2) yanittaki next_since + next_since_id ile devam et
curl -H "X-API-Key: $KEY" ".../orders?limit=200&since=2026-08-24T19:02:31%2B00:00&since_id=ord_123"

# yanit:
# { "items": [...], "next_since": "...", "next_since_id": "...", "has_more": true }

`since_id` şart: aynı `updated_at` değerini taşıyan birden çok sipariş olabilir (toplu senkron aynı anda yazar). Yalnız `since` gönderirsen o gruptan sayfa sınırına denk gelenler atlanır.

İmleç "kayıt DEĞİŞTİ" der, "durumu değişti" demez: sipariş herhangi bir nedenle güncellendiğinde tekrar gelir. Bu bilinçli bir tercihtir — fazladan göndermek, sessizce atlamaktan iyidir. İşleyişini idempotent yaz.

Bir siparişin ayrıntısını (kargo ve adres dahil) ve kalemlerini (SKU, barkod, adet, fiyat) çekin. Sipariş ayrıntısı, Stokzone'un bildiği tracking_number ve tracking_url alanlarını okumanızı sağlar.

curl -H "X-API-Key: $KEY" ".../orders/{order_id}"
curl -H "X-API-Key: $KEY" ".../orders/{order_id}/items"

Depo, sipariş kargolandığında Stokzone'a bildirim gönderir. Bu bir TETİKTİR: statüyü yazar, taşıyıcı ve takip numarasını çekme ucundan alır.

POST https://api.stokzone.com/api/v1/webhooks/wms/fulfillment
X-WMS-Signature: t=<unix>,v1=<hex>      # HMAC_SHA256(sir, "<t>.<HAM govde>")

{
  "olay": "order.fulfilled",
  "inbound_order_id": "...",   # varsa BIREBIR eslesme anahtari
  "source": "stokzone",
  "external_ref": "...",       # yoksa ikincil anahtar
  "status": "shipped",
  "shipped_at": "2026-08-25T10:00:00Z"
}

İmza zorunludur: `X-WMS-Signature: t=<unix>,v1=<hex>` ve imzalanan metin `"<t>.<HAM gövde>"`dir. Gövdeyi ayrıştırıp yeniden serileştirmeyin — anahtar sırası değişir ve imza tutmaz. `t` tekrar-oynatma korumasıdır; ±5 dakika dışındaki damgalar reddedilir. İmza sırrı yapılandırılmamışsa uç hiçbir isteği kabul etmez.

Eşleşme SIRALIDIR: `inbound_order_id` varsa o kullanılır; yoksa `source`+`external_ref`. İkisi de yoksa sipariş entegratöre ait değildir ve olay atlanır. `external_ref` yalnız işletme başına tekil olduğu için birden çok kayıtla eşleşirse istek REDDEDİLİR — yanlış siparişe yazmaktansa reddetmek doğrudur.

Takip numarası ve taşıyıcı webhook gövdesinde YOKTUR. Kısmi sevkte bir sipariş birden çok koliyle çıkabilir ve her koli ayrı takip numarası taşır; tek bir alana sıkıştırılsaydı diğerleri kaybolurdu. Bu bilgi sevk çekme ucundaki `shipments[]` listesinden alınır.

order.created ve order.updated olaylarına abone olun; yeni veya değişen siparişte WMS uç noktanız tetiklenir. Bu, sürekli polling ihtiyacını azaltır.

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://wms.example.com/hooks/stokzone","events":["order.created","order.updated"]}' \
  "https://api.stokzone.com/api/v1/web-api/v1/webhooks"

WMS'in "kargolandı + takip numarası" bilgisini Stokzone'a geri yazması (fulfillment push) henüz mevcut değildir. Bu yetenek eklendiğinde bu bölüm gerçek uçla güncellenecektir. Şimdilik durum güncellemesi Stokzone panelinden veya mevcut pazaryeri entegrasyonundan akar.