Siparişler

BYNovax mağazasında oluşan satışları ERP sistemine aktarın.

Endpointler

GET/ordersSiparişleri listele

GET/orders/{order}Sipariş detayını oku

Alan	Örnek
order_no	BNX-20260830-GQAFVE
payment_status	paid / pending_payment / cancelled
order_status	new / processing / shipped / cancelled
fulfillment_status	unfulfilled / shipped / cancelled
currency	TRY
grand_total	1559.88
customer	Ad, e-posta, telefon
shipping_address	Teslimat adresi: ad, e-posta, telefon, ülke, şehir, ilçe, mahalle, posta kodu ve açık adres
invoice_address	Fatura adresi: kişi / unvan, iletişim, vergi numarası, vergi dairesi ve adres bilgileri
items	SKU, product_id, variant_id, qty, fiyat

Orders API ne işe yarar?

BYNovax mağazasına gelen siparişleri ERP, muhasebe, depo veya fulfillment sisteminize aktarmak için kullanılır.

External Commerce API V1 sipariş tarafında read ağırlıklıdır. Siparişleri listeleyebilir ve detaylarını okuyabilirsiniz.

Gerekli scope

GET /orders ve GET /orders/{order} için orders:read scope gerekir.

External Commerce API V1 contract'ında orders:write isimli bir scope bulunmaz.

Sipariş liste filtreleri

Query	Amaç
limit	Sayfa büyüklüğü; varsayılan 30, maksimum 100
after_id	Pagination cursor
payment_status	Ödeme durumu filtresi
order_status	Sipariş durumu filtresi
fulfillment_status	Fulfillment durumu filtresi
created_after	Belirli zamandan sonra oluşturulan siparişler
updated_after	Belirli zamandan sonra güncellenen siparişler

Sipariş listesinde teslimat adresi

GET /orders response içindeki her sipariş shipping_address alanı taşır. Teslimat adresi kaydı mevcut değilse değer null olur.

Adres mevcutsa name, email, phone, country, city, district, neighborhood, postal_code ve address_line alanları döner.

Bu nedenle ERP veya entegratör, teslimat adresini almak için her sipariş adına ayrıca GET /orders/{order} çağrısı yapmak zorunda değildir.

{
  "id": 116,
  "order_no": "BNX-20260916-RKD3OI",
  "customer": {
    "name": "Ad Soyad",
    "email": "mail@example.com",
    "phone": "05xxxxxxxxx"
  },
  "shipping_address": {
    "name": "Ad Soyad",
    "email": "mail@example.com",
    "phone": "05xxxxxxxxx",
    "country": "Türkiye",
    "city": "Antalya",
    "district": "Muratpaşa",
    "neighborhood": "Mahalle",
    "postal_code": "07000",
    "address_line": "Açık adres"
  }
}

Orders pagination yönü

Orders endpointi yeni siparişleri önce okuyabilmek için azalan ID cursor davranışı kullanır.

Kendi after_id hesabınızı üretmeyin; response içerisindeki next_after_id değerini takip edin.

Liste response'unda önemli alanlar

Alan	Açıklama
id / uid / order_no	Sipariş kimlik bilgileri
payment_status	Ödeme durumu
order_status	Sipariş durumu
fulfillment_status	Fulfillment durumu
currency	Sipariş para birimi
subtotal	Ara toplam
discount_total	İndirim toplamı
shipping_total	Kargo toplamı
tax_total	Vergi toplamı
grand_total	Genel toplam
shipping_provider	Kargo sağlayıcı bilgisi
customer	Müşteri özet bilgisi
shipment	Varsa shipment özeti

Sipariş detayında ek bilgiler

GET /orders/{order} liste özetine ek olarak customer_note, shipping_address, items ve daha ayrıntılı shipment bilgisi sağlayabilir.

ERP'ye sipariş aktarırken yalnız liste response'una güvenmek yerine gerekiyorsa detay endpointini kullanın.

ERP senkronizasyon modeli

1. GET /orders?limit=30
2. Daha önce aktarılmamış order ID'leri belirle.
3. Gerekirse GET /orders/{order} ile detayı al.
4. ERP satış siparişini oluştur.
5. BYNovax order ID/UID/order_no eşlemesini sakla.
6. next_after_id ile sonraki sayfaya geç.
7. Webhook ile yeni değişiklikleri gerçek zamanlı takip et.

Polling + webhook birlikte kullanım

Webhooks gerçek zamanlı değişiklikleri almak için kullanılabilir; periyodik Orders API taraması ise kaçırılmış eventlere karşı reconciliation mekanizması olarak çalışabilir.

Aynı order_no veya order ID için ERP tarafında duplicate oluşturmayacak idempotent import mantığı kurun.

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

orders:read credential üzerinde var.
GET /orders 200 dönüyor.
Order ID/UID ERP'de kalıcı eşleniyor.
Aynı sipariş ikinci kez ERP'de oluşturulmuyor.
Pagination cursor doğru şekilde devam ediyor.

Sipariş liste contractı — adresler

shipping_address ile invoice_address aynı değerleri taşıyabilir ancak entegrasyon contractında iki ayrı alan olarak işlenmelidir.

Alan	Açıklama
shipping_address	Teslimat adresi; kayıt yoksa null
invoice_address	billing_address_id authority üzerinden gelen fatura adresi; kayıt yoksa null
customer	Sipariş müşteri özeti

invoice_address alanları

Alan	Açıklama
name	Fatura adresindeki kişi / unvan
email	Fatura adresi e-posta bilgisi
phone	Telefon
tax_number	Vergi numarası; geçmiş siparişlerde veya bilgi girilmemişse null olabilir
tax_office	Vergi dairesi; geçmiş siparişlerde veya bilgi girilmemişse null olabilir
country	Ülke
city	Şehir
district	İlçe
neighborhood	Mahalle
postal_code	Posta kodu
address_line	Açık adres

Sipariş liste contractı — items

Alan	Açıklama
id	Order item kimliği
product_id	BYNovax ürün kimliği; nullable olabilir
variant_id	BYNovax varyant kimliği; varyantsız üründe null olabilir
sku	Sipariş satırı SKU değeri
name	Sipariş satırı ürün adı
image_url	Satır görsel URL bilgisi
currency	Para birimi
unit_price	Birim fiyat
quantity	Adet
line_subtotal	Satır ara toplamı
tax_rate	Vergi oranı
tax_total	Satır vergi toplamı
line_total	Satır genel toplamı
options	Sipariş satırı seçenekleri

Sipariş import güvenliği

ERP duplicate kontrolünü order ID, UID veya order_no eşlemesiyle yapmalıdır.
Liste response içindeki items doğrudan order ile birlikte işlenebilir; yalnız ürün kataloğundaki güncel state'e bakarak geçmiş sipariş satırını yeniden üretmeyin.
Contractta tarihsel barcode snapshot alanı bulunmadığı için barcode'u order item için zorunlu kabul etmeyin.
shipping_address ve invoice_address alanlarını ayrı saklayın.
Webhook + polling birlikte kullanılıyorsa aynı order için duplicate ERP kaydı oluşturmayın.

Satış senkronizasyonu

BYNovax mağazasında sipariş oluşur.
Harici sistem order.created webhook olayını alır.
Webhook'taki order ID ile GET /orders/{order} çağrılır.
Sipariş harici ERP veya entegrasyon sistemine işlenir.
inventory.updated eventleri stok state değişikliklerini bildirir.