Changelog
BYNovax External Commerce API V1 ve developer dokümantasyonundaki önemli contract, davranış ve geliştirici deneyimi değişikliklerini buradan takip edin.
External Commerce API V1 — Production
External Commerce API V1 production contract aktif durumdadır. API ürün, varyant, stok, fiyat, kategori, marka, sipariş, kargo, fatura ve webhook entegrasyonlarını kapsar.
Tenant authority API credential üzerinden belirlenir ve istemci tarafından gönderilen store_id yetki kaynağı olarak kullanılmaz.
V1 production kapsamı
| Alan | Durum |
|---|---|
| Products | Read + Write |
| Variants | Inventory + Pricing Write |
| Inventory | Read + Write + Bulk |
| Pricing | Read + Write + Bulk |
| Categories | Read |
| Brands | Read |
| Orders | Read |
| Shipping | Read + Tracking Write |
| Invoices | Read-only |
| Webhooks | Read + Create + Disable |
Authentication ve tenant modeli
- Bearer API credential kullanılır.
- Credential belirli bir BYNovax mağazasına bağlıdır.
- Tenant request body veya query parametresinden seçilemez.
- Endpoint erişimleri scope tabanlıdır.
Write güvenliği
Write endpointlerinde gerekli olduğu yerde Idempotency-Key kullanılır. Network timeout sonrası aynı mantıksal işlem retry ediliyorsa aynı key korunmalıdır.
Aynı key'in farklı payload veya farklı business işleminde kullanılması conflict oluşturabilir.
Webhook contract
- Canonical event listesi tanımlıdır.
- Webhook create başarılı olduğunda HTTP 201 Created döner.
- Signing secret yalnızca oluşturma response'unda plaintext olarak verilir.
- Receiver duplicate-safe ve idempotent tasarlanmalıdır.
Dokümantasyon geliştirmeleri
Core guide sayfaları sıfır varsayımla entegrasyon yapılabilecek şekilde genişletildi.
API Reference sayfalarına scope, parametre, request/response davranışı, tenant kuralları, hata senaryoları ve entegrasyon örnekleri eklendi.
Uzun kod örnekleri için kontrollü scroll davranışı ve mobil dokümantasyon navigasyonu eklendi.
Değişiklik politikası
v1 içerisinde geriye uyumlu ek response alanları veya dokümantasyon iyileştirmeleri yapılabilir. Entegrasyonların bilinmeyen JSON alanlarını tolere etmesi önerilir.
Endpoint path, HTTP method veya temel business contract gibi geriye uyumsuz major değişiklikler gerektiğinde yeni major sürüm yolu kullanılacaktır.
Entegratör ne yapmalı?
- Production Base URL'yi configuration içerisinde tutun.
- Credential'ı güvenli secret storage içerisinde saklayın.
- Response parser'ı bilinmeyen alanlara toleranslı yazın.
- request_id değerini operasyonel loglara kaydedin.
- Retry ve idempotency kurallarına uyun.
- Webhook yanında periyodik reconciliation mekanizması kullanmayı değerlendirin.