Adım Adım Entegrasyon

BU SAYFAYI NASIL KULLANACAKSIN?

• Aşağıdaki adımları 1'den 10'a kadar sırayla uygula.
• Bir adım çalışmadan sonraki adıma geçme.
• Endpoint adreslerini veya JSON alan isimlerini Türkçeye çevirmeye çalışma.
• API Key ve API Secret değerlerini kimseyle paylaşma.
• Önce test et, sonra gerçek veri gönder.

1. API BAĞLANTISINI HAZIRLA

Sana bir API Key ve bir API Secret verilir. BYNovax hangi mağazaya bağlandığını bu bilgilerden anlar.

Request içine store_id yazma.

• API Secret değerini kod deposuna açık şekilde yazma.
• API Secret değerini loglara yazma.
• Başka mağazanın store_id değerini request içine gönderme.

X-API-Key: bnx_key_<client_uid>
X-API-Secret: <API_SECRET>
Accept: application/json
Content-Type: application/json

2. ÖNCE ÜRÜNÜ KONTROL ET — HENÜZ KAYDETME

Ürün göndermeden önce doğrulama endpointini kullan.

Bu işlem ürün oluşturmaz. Sadece gönderdiğin veride hata var mı gösterir.

POST /products/bulk/validate

{
  "mode": "create",
  "products": [
    {
      "external_id": "NESLICE-1001",
      "name": "Örnek Ürün",
      "sku": "NES-1001",
      "barcode": "8690000001001",
      "category_id": 25,
      "price": 799.90,
      "stock": 10,
      "description": "Ürün açıklaması",
      "image_urls": [
        "https://example.com/product.jpg"
      ]
    }
  ]
}

3. ÜRÜNÜ BYNOVAX'A EKLE

Doğrulama başarılıysa aynı ürünü create endpointine gönder.

Bir istekte en fazla 100 ürün gönder.

• external_id kendi sistemindeki ürün kimliğindir.
• external_id değerini mümkünse daha sonra değiştirme.
• BYNovax'ın döndürdüğü product_id değerini kendi sisteminde sakla.
• Varyant varsa variant_id değerlerini de sakla.

POST /products/bulk/create

Idempotency-Key: neslice-products-0001

4. ÜRÜN BİLGİSİ DEĞİŞECEKSE BURAYI KULLAN

• Ürün adı değişecekse burada güncelle.
• Açıklama değişecekse burada güncelle.
• Kategori veya katalog bilgileri değişecekse burada güncelle.
• FİYATI burada değiştirme.
• STOĞU burada değiştirme.

PATCH /products/bulk/update

4A. ÜRÜNÜ SİLECEKSEN TOPLU SİLME ENDPOINTİNİ KULLAN

Bir veya birden fazla ürünü entegrasyondan kaldırmak istiyorsan bulk delete endpointini kullan.

Bir istekte en fazla 100 ürün gönderebilirsin.

• Her kayıt için product_id, external_id, sku veya barcode alanlarından yalnızca birini kullan.
• summary.deleted başarıyla arşivlenen ürün sayısını gösterir.
• summary.skipped zaten silinmiş veya bulunamayan ürünleri gösterebilir.
• summary.failed işlenemeyen ürün sayısını gösterir.
• Aynı işlemi retry ediyorsan aynı Idempotency-Key değerini kullan.

POST /products/bulk/delete

Idempotency-Key: neslice-products-delete-0001

{
  "products": [
    {
      "product_id": 123
    },
    {
      "sku": "NES-1002"
    }
  ]
}

5. FİYAT DEĞİŞECEKSE SADECE FİYAT ENDPOINTİNİ KULLAN

• Ürün fiyatı değişiyorsa /prices/bulk kullan.
• Varyantın kendi fiyatı varsa varyant fiyat endpointini kullan.
• Fiyat değiştirmek için ürün update endpointini kullanma.

PATCH /prices/bulk

{
  "items": [
    {
      "product_id": 123,
      "price": 899.90,
      "compare_at_price": 999.90,
      "currency": "TRY"
    }
  ]
}

6. STOK DEĞİŞECEKSE SADECE STOK ENDPOINTİNİ KULLAN

• Stok değişiyorsa /inventory/bulk kullan.
• Varyant stoğu değişiyorsa doğru variant_id değerini kullan.
• Stok değiştirmek için ürün update endpointini kullanma.

PATCH /inventory/bulk

{
  "items": [
    {
      "product_id": 123,
      "stock": 25
    }
  ]
}

7. SİPARİŞLERİ ÇEK

• customer = müşterinin temel bilgileri.
• shipping_address = ürünün gönderileceği teslimat adresi.
• invoice_address = faturada kullanılacak adres.
• invoice_address.tax_number = vergi numarası; bilgi yoksa null olabilir.
• invoice_address.tax_office = vergi dairesi; bilgi yoksa null olabilir.
• items = siparişte satılan ürünler.
• Aynı siparişi ikinci kez ERP'de oluşturma.
• BYNovax order ID veya order_no değerini kendi sisteminde sakla.

GET /orders?limit=30

8. KARGO TAKİP NUMARASINI YAZ

Önce siparişin kargo bilgisini okuyabilirsin.

Kargo takip numarası oluştuğunda tracking endpointine gönder.

GET /orders/{order}/shipment

PUT /orders/{order}/tracking

{
  "shipping_provider": "manual",
  "tracking_number": "TRK-123456",
  "tracking_url": "https://kargo.example/TRK-123456"
}

9. FATURAYI KONTROL ET

• Fatura oluşmuşsa burada görürsün.
• Fatura listesi boşsa entegrasyon bozuk demek değildir.
• Fatura henüz oluşturulmamış olabilir.
• invoice_address ile invoice endpointini birbirine karıştırma.
• invoice_address = adres, invoice endpointi = fatura kaydı.

GET /orders/{order}/invoice

10. BİLDİRİMLERİ EN SON BAĞLA

Önce ürün, fiyat, stok ve sipariş işlemlerini çalıştır.

Bunlar düzgün çalıştıktan sonra webhook yani bildirim sistemini ekle.

• Webhook aynı olayı birden fazla kez gönderebilir.
• Aynı siparişi veya ürünü ikinci kez oluşturmamak için kontrol yap.
• Webhook geldiğinde gerektiğinde ilgili GET endpointinden güncel veriyi tekrar oku.

POST /webhooks

{
  "url": "https://senin-sistemin.example.com/bynovax",
  "events": [
    "order.created",
    "order.updated",
    "order.shipped",
    "product.created",
    "product.updated",
    "inventory.updated",
    "pricing.updated"
  ]
}

BİR ŞEY ÇALIŞMIYORSA ÖNCE BURAYA BAK

ÇOK KISA ÖZET

ÜRÜNÜ KONTROL ET
POST /products/bulk/validate
        ↓
ÜRÜNÜ EKLE
POST /products/bulk/create
        ↓
ÜRÜN BİLGİSİNİ DEĞİŞTİR
PATCH /products/bulk/update
        ↓
ÜRÜNÜ SİL / ARŞİVLE
POST /products/bulk/delete
        ↓
FİYATI DEĞİŞTİR
PATCH /prices/bulk
        ↓
STOĞU DEĞİŞTİR
PATCH /inventory/bulk
        ↓
SİPARİŞ ÇEK
GET /orders
        ↓
KARGOYU GÜNCELLE
PUT /orders/{order}/tracking
        ↓
FATURAYI KONTROL ET
GET /orders/{order}/invoice
        ↓
EN SON BİLDİRİMLERİ BAĞLA
POST /webhooks

BURADAN SONRASI İLERİ SEVİYE

Yukarıdaki 10 adımı çalıştırdıysan temel entegrasyon hazırdır.

Aşağıdaki bölüm retry, veri eşleme, kuyruk, loglama, izleme ve production güvenliği gibi ileri seviye konuları anlatır.

Önerilen mimari

ERP / PIM / WMS / Muhasebe
          │
          ▼
BYNovax Integration Service
          │
          ├── API Client
          ├── Credential Store
          ├── Idempotency Manager
          ├── Resource Mapping
          ├── Retry Queue
          └── Webhook Receiver
                    │
                    ▼
          BYNovax External API

1. Credential yönetimi

• Credential'ı yalnızca server-side kullanın.
• Secret manager veya encrypted environment variable kullanın.
• Tam credential değerini loglamayın.
• Rotate sonrası eski credential kullanımını durdurun.
• Credential ile mağaza eşlemesini configuration içerisinde açık tutun.

2. Resource mapping

ERP ve BYNovax farklı resource ID'leri kullanır. Bu nedenle kalıcı mapping tablosu oluşturmanız gerekir.

3. İlk katalog senkronizasyonu

GET /categories
      ↓
Kategori eşlemelerini oluştur
      ↓
GET /products pagination
      ↓
Product mapping oluştur
      ↓
Variant mapping oluştur
      ↓
Inventory / Pricing eşlemesini doğrula

4. Incremental senkronizasyon

Her seferinde bütün kataloğu tekrar göndermek yerine yalnızca değişen stok/fiyat kayıtlarını senkronize edin.

Bulk endpointleri yüksek sayıda değişikliği verimli şekilde göndermek için kullanılabilir.

5. Idempotency stratejisi

Business operation:
ERP stock change #98122

Idempotency-Key:
erp-stock-98122

Timeout:
aynı key ile retry

Yeni stok değişikliği #98123:
yeni key üret

6. Sipariş import stratejisi

Orders API'den aldığınız siparişi ERP'ye aktarırken BYNovax order ID/UID/order_no değerini kalıcı olarak saklayın.

Aynı sipariş yeniden geldiğinde duplicate ERP order oluşturmamalısınız.

if bynovax_order_id already imported:
    update/reconcile existing ERP order
else:
    create ERP order
    persist mapping

7. Webhook + polling birlikte kullanın

Webhook gerçek zamanlı event delivery sağlar ancak production entegrasyonunda periyodik reconciliation taraması da önerilir.

Bu yaklaşım geçici network sorunları veya kaçırılmış eventlerin daha sonra düzeltilmesini sağlar.

Realtime:
Webhook → Queue → Worker

Safety net:
Scheduled Orders/API reconciliation

8. Retry politikası

9. Önerilen exponential backoff

Attempt 1 → hemen
Attempt 2 → 2 saniye
Attempt 3 → 5 saniye
Attempt 4 → 15 saniye
Attempt 5 → 30 saniye

Sonrasında:
manual review / dead-letter queue

10. Loglama

• request_id
• endpoint path
• HTTP method
• HTTP status
• error.code
• Idempotency-Key
• resource ID
• tenant/store internal mapping reference
• timestamp
• retry attempt

11. Monitoring

• 5xx oranı
• 401/403 artışı
• Webhook consecutive failures
• Queue backlog
• Sipariş import gecikmesi
• Stok/fiyat sync gecikmesi
• Dead-letter kayıtları

12. Production deployment checklist

13. Minimum production test planı

• Geçerli credential ile /health testi.
• Geçersiz credential ile 401 testi.
• Eksik scope ile 403 testi.
• Yanlış resource ID ile 404 testi.
• Geçersiz payload ile 422 testi.
• Aynı Idempotency-Key retry testi.
• Ürün stok güncelleme + read-back testi.
• Sipariş import duplicate testi.
• Tracking update testi.
• Webhook delivery + duplicate testi.
• Network timeout retry testi.

14. Entegrasyon bitti mi?

Entegrasyon yalnızca API çağrısı 200 döndüğünde bitmiş sayılmaz. Retry, duplicate prevention, resource mapping, logging, webhook recovery ve reconciliation mekanizmaları da production sisteminin parçasıdır.

Production'a geçmeden önce failure senaryolarını bilinçli olarak test edin.

Önerilen okuma sırası

• Hızlı Başlangıç
• Authentication
• Yetkilendirme
• Mağaza / Tenant
• Headers
• Data Format
• Pagination
• Idempotency
• Hatalar
• API Reference
• Webhooks