Hızlı Başlangıç

Başlamadan önce neye ihtiyacınız var?

• Geçerli bir BYNovax API credential.
• Credential'ın bağlı olduğu mağazayı bilmek.
• Kullanacağınız endpointler için gerekli scope'ların credential üzerinde tanımlı olması.
• Server-side çalışan bir entegrasyon uygulaması.
• JSON request/response işleyebilen HTTP client.
• Write işlemleri için Idempotency-Key üretebilen bir yapı.

1. Base URL'yi tanımlayın

Tüm External Commerce API V1 çağrıları production Base URL üzerinden yapılır. Bu değeri kaynak koda sabit yazmak yerine environment variable veya configuration içerisinde saklayın.

https://bynovax.com/api/external/v1

2. Credential'ı güvenli şekilde saklayın

Credential'ı frontend JavaScript, mobil uygulama bundle'ı veya public repository içerisine koymayın.

Server environment variable veya secret manager kullanın.

BYNOVAX_API_TOKEN=bnx_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. İlk bağlantıyı /health ile test edin

İlk isteğiniz mutlaka GET /health olsun. Bu çağrı authentication, tenant ve scope durumunuzu doğrulamanızı sağlar.

curl   https://bynovax.com/api/external/v1/health   -H "Authorization: Bearer bnx_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"   -H "Accept: application/json"

Health response'ta ne kontrol edeceğim?

4. Scope'larınızı doğrulayın

Credential geçerli olsa bile endpoint için gerekli scope yoksa 403 alırsınız. Entegrasyona başlamadan önce health response içerisindeki scope listesini kontrol edin.

5. İlk ürün listesini okuyun

Bağlantınız ve scope'larınız doğruysa GET /products çağrısıyla ürünleri okuyun.

İlk pagination çağrısında after_id göndermeyin.

curl   "https://bynovax.com/api/external/v1/products?limit=10"   -H "Authorization: Bearer bnx_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"   -H "Accept: application/json"

Ürün okuma başarılı mı?

• HTTP 200 alıyorsunuz.
• success=true.
• data.products bir array.
• request_id mevcut.
• Pagination metadata okunabiliyor.

6. Stok güncellemesini test edin

Write testine geçmeden önce test edeceğiniz ürünün doğru mağazaya ait olduğundan emin olun.

PATCH /inventory/{product} için inventory:write scope ve Idempotency-Key gerekir.

curl -X PATCH   https://bynovax.com/api/external/v1/inventory/7314   -H "Authorization: Bearer bnx_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"   -H "Accept: application/json"   -H "Content-Type: application/json"   -H "Idempotency-Key: quickstart-stock-7314-001"   -d '{"stock":20}'

Stok değişti mi nasıl kontrol ederim?

PATCH başarılı olduktan sonra GET /inventory/{product} çağrısıyla değeri tekrar okuyun.

Ürün varyantlıysa ürün seviyesinde stok yazmak yerine variant inventory endpointi kullanmanız gerekebilir.

GET /inventory/7314

7. Siparişleri okuyun

Sipariş entegrasyonunda GET /orders kullanın. Bu endpoint orders:read scope ister.

Orders pagination yeni siparişlerden eski siparişlere doğru ilerleyebilir; her zaman next_after_id kullanın.

curl   "https://bynovax.com/api/external/v1/orders?limit=30"   -H "Authorization: Bearer bnx_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"   -H "Accept: application/json"

ERP'ye sipariş aktarırken

• BYNovax order ID/UID/order_no eşlemesini saklayın.
• Aynı siparişi iki kez ERP'ye oluşturmayın.
• Gerekirse GET /orders/{order} ile detay alın.
• Pagination cursor'u persist edin.
• Webhook olaylarını reconciliation ile destekleyin.

8. Tracking bilgisini BYNovax'a gönderin

Sipariş kargolandığında PUT /orders/{order}/tracking çağrısı kullanılır.

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

curl -X PUT   https://bynovax.com/api/external/v1/orders/95/tracking   -H "Authorization: Bearer bnx_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"   -H "Accept: application/json"   -H "Content-Type: application/json"   -H "Idempotency-Key: tracking-order-95-001"   -d '{
    "shipping_provider": "manual",
    "tracking_number": "TRK-001",
    "tracking_url": "https://carrier.example/track/TRK-001"
  }'

9. Webhook oluşturun

Gerçek zamanlı değişiklikler için webhook endpointinizi oluşturun. URL public HTTPS endpoint olmalı.

Webhook create işlemi HTTP 201 Created döner ve signing_secret yalnızca oluşturma response'unda plaintext olarak verilir.

curl -X POST   https://bynovax.com/api/external/v1/webhooks   -H "Authorization: Bearer bnx_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"   -H "Accept: application/json"   -H "Content-Type: application/json"   -H "Idempotency-Key: webhook-create-001"   -d '{
    "url": "https://erp.example.com/webhooks/bynovax",
    "events": [
      "order.created",
      "order.updated",
      "order.shipped"
    ]
  }'

Webhook receiver kontrol listesi

• Public HTTPS URL erişilebilir.
• Request hızlı şekilde 2xx dönüyor.
• Ağır iş queue/worker katmanına aktarılıyor.
• Duplicate event tekrarları güvenli şekilde işleniyor.
• signing_secret güvenli secret storage içerisinde tutuluyor.

10. Production checklist

Entegrasyonun temel akışı

Credential al
    ↓
GET /health
    ↓
Store + scope kontrolü
    ↓
GET /categories
    ↓
GET /products
    ↓
Inventory / Pricing sync
    ↓
GET /orders
    ↓
ERP sipariş işlemleri
    ↓
PUT tracking
    ↓
Webhooks
    ↓
Reconciliation + monitoring

Bir yerde hata alırsanız

HTTP status, error.code ve request_id değerlerini birlikte kontrol edin.

401/403/404/422 hatalarını kör retry etmeyin. 5xx veya network timeout durumlarında kontrollü retry uygulayın.

Write retry sırasında aynı mantıksal işlem için aynı Idempotency-Key kullanılmalıdır.