Kargo

Sipariş shipment bilgisini okuyun veya tracking bilgisini BYNovax'a yazın.

Tracking başarıyla işlendiğinde order.shipped webhook olayı üretilebilir.

Endpointler

GET/orders/{order}/shipmentShipment oku

PUT/orders/{order}/trackingTracking güncelle

Shipping API ne işe yarar?

Bir siparişin shipment bilgisini okumak ve dış fulfillment/kargo sisteminde üretilen tracking bilgisini BYNovax'a geri yazmak için kullanılır.

Endpointler ve scope'lar

Endpoint	Scope	Amaç
GET /orders/{order}/shipment	shipping:read	Shipment bilgisini oku
PUT /orders/{order}/tracking	shipping:write	Tracking bilgisini güncelle

Shipment okuma

GET shipment response içerisinde order bilgisi ile shipment objesi döner. Siparişte henüz shipment oluşmamışsa shipment null olabilir.

Tracking request alanları

Request alanı provider değil shipping_provider'dır.

Alan	Durum	Açıklama
tracking_number	Zorunlu	Kargo takip numarası
tracking_url	Opsiyonel/null	Takip sayfası URL'si
shipping_provider	Opsiyonel/null	Kargo sağlayıcı adı/kodu

Idempotency

PUT tracking bir write işlemidir ve Idempotency-Key kullanılmalıdır. Aynı tracking operasyonunu timeout nedeniyle retry ediyorsanız aynı key'i koruyun.

Başarılı tracking update sonrasında

Response shipment objesi shipment_uid, order_id, provider, status, tracking_number, tracking_url, shipping_total, currency, shipped_at ve updated_at gibi alanları taşıyabilir.

İlgili order response'u order_status, fulfillment_status ve shipping_provider gibi güncel operasyon durumlarını da içerebilir.

Webhook ilişkisi

Tracking başarıyla işlendiğinde order.shipped webhook olayı üretilebilir. Entegrasyonunuz aynı business değişikliğini hem API response hem webhook üzerinden görebileceği için duplicate-safe olmalıdır.

Fulfillment senaryosu

BYNovax order ERP'ye alındı
        ↓
Depo siparişi hazırladı
        ↓
Kargo sağlayıcı tracking_number üretti
        ↓
PUT /orders/{order}/tracking
        ↓
BYNovax shipment güncellendi
        ↓
order.shipped webhook oluşabilir

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

shipping:write scope var.
tracking_number gönderiliyor.
Alan adı shipping_provider olarak kullanılıyor.
Idempotency-Key gönderiliyor.
GET shipment yeni tracking bilgisini gösteriyor.

Shipment state contractı

Tracking write request alanı shipping_provider, shipment response alanı provider olarak dönebilir.

Alan	Amaç
shipment_uid	Shipment dış referansı
order_id	Bağlı BYNovax sipariş kimliği
provider	Response içindeki kargo sağlayıcı
status	Shipment durumu
tracking_number	Takip numarası
tracking_url	Takip URL'si
shipping_total	Kargo toplamı
currency	Para birimi
shipped_at	Kargoya verilme zamanı
updated_at	Son güncelleme

Shipping retry / reconciliation

Tracking write işlemi Idempotency-Key ile gönderilmelidir.
Timeout sonrası aynı logical tracking mutation için aynı key korunmalıdır.
Başarılı write sonrasında GET /orders/{order}/shipment ile state tekrar okunabilir.
order.shipped webhook ile API response aynı business değişikliğini bildirebilir; ERP duplicate-safe olmalıdır.
Tracking number'ı siparişin tek global kimliği olarak kullanmayın; BYNovax order ID eşlemesini koruyun.