Ürünler

Bu API ne işe yarar?

Products API, ERP, muhasebe, POS, PIM veya başka bir dış sistem ile BYNovax mağazasındaki ürün kataloğunu senkronize etmek için kullanılır.

Ürünleri listeleyebilir, tek ürün detayını okuyabilir, yeni ürün oluşturabilir veya mevcut bir ürünü güncelleyebilirsiniz.

Gerekli scope'lar

İlk kez ürün okuyorsanız

Önce GET /products çağrısı yapın. Credential hangi mağazaya bağlıysa yalnızca o mağazanın ürünleri listelenir.

Liste endpointi pagination kullanır. İlk çağrıda after_id göndermeyin; sonraki sayfa için response içerisindeki next_after_id değerini kullanın.

Ürün oluştururken gerekli temel alanlar

Opsiyonel ve ek ürün alanları

Ürün contract'ı brand, compare_at_price, currency, status ve active gibi ek alanlar taşıyabilir. Gönderdiğiniz alanların tiplerini API Reference tablosuyla uyumlu tutun.

Kategori kimliğini kendi ERP kategori kimliğinizle karıştırmayın. category_id BYNovax tarafındaki kategori kaydını ifade eder.

Tenant davranışı

Request içerisine store_id koyarak mağaza seçemezsiniz. Mağaza credential tarafından belirlenir.

Başka bir mağazaya ait product ID ile işlem yapılmaya çalışılırsa kaynak credential tenant kapsamında bulunamaz.

Varyantlı ürün oluşturma

POST /products endpointi ürünle birlikte variants dizisi gönderilmesini destekler.

Her varyant kendi SKU, barkod, seçenek, fiyat ve stok bilgisine sahiptir.

Varyant gönderildiğinde ürünün has_variants alanı true olur ve ürün toplam stoğu varyant stoklarının toplamından hesaplanır.

Ürün SKU/barkodu ile varyant SKU/barkodları aynı mağaza içerisinde benzersiz olmalıdır.

curl -X POST \
  https://bynovax.com/api/external/v1/products \
  -H "Authorization: Bearer bnx_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-variant-create-001" \
  -d '{
    "name": "Basic Tişört",
    "sku": "TSHIRT-001",
    "barcode": "TSHIRT-001",
    "category_id": 12,
    "brand": "BYNovax",
    "price": 499.90,
    "compare_at_price": 599.90,
    "stock": 18,
    "currency": "TRY",
    "tax_rate": 20,
    "status": "active",
    "description": "Basic pamuklu tişört",
    "image_urls": [
      "https://cdn.example.com/products/tshirt-001.jpg"
    ],
    "external_id": "ERP-TSHIRT-001",
    "variants": [
      {
        "sku": "TSHIRT-001-S-BEYAZ",
        "barcode": "8690000000011",
        "option1_name": "Beden",
        "option1_value": "S",
        "option2_name": "Renk",
        "option2_value": "Beyaz",
        "price": 499.90,
        "compare_at_price": 599.90,
        "stock": 10,
        "currency": "TRY",
        "status": "active"
      },
      {
        "sku": "TSHIRT-001-M-BEYAZ",
        "barcode": "8690000000012",
        "option1_name": "Beden",
        "option1_value": "M",
        "option2_name": "Renk",
        "option2_value": "Beyaz",
        "price": 499.90,
        "compare_at_price": 599.90,
        "stock": 8,
        "currency": "TRY",
        "status": "active"
      }
    ]
  }'

Varyantlı ürün oluşturma response örneği

Başarılı oluşturma HTTP 201 döner.

Response içindeki product.id ve product.uid değerlerini ERP eşlemenizde saklayın.

Varyantların id değerlerini daha sonraki stok ve fiyat güncellemelerinde kullanabilirsiniz.

{
  "success": true,
  "data": {
    "product": {
      "id": 12345,
      "uid": "ext-14-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "category_id": 12,
      "name": "Basic Tişört",
      "slug": "basic-tisort",
      "sku": "TSHIRT-001",
      "barcode": "TSHIRT-001",
      "price": 499.90,
      "compare_at_price": 599.90,
      "stock": 18,
      "currency": "TRY",
      "has_variants": true,
      "variants": [
        {
          "id": 501,
          "uid": "extv-14-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "sku": "TSHIRT-001-S-BEYAZ",
          "barcode": "8690000000011",
          "options": [
            {
              "name": "Beden",
              "value": "S"
            },
            {
              "name": "Renk",
              "value": "Beyaz"
            }
          ],
          "price": 499.90,
          "compare_at_price": 599.90,
          "stock": 10,
          "currency": "TRY",
          "status": "active"
        }
      ]
    }
  },
  "request_id": "req_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Varyant stok ve fiyat güncelleme

Varyantlı ürünlerde stok ve fiyat değişiklikleri ürün seviyesinde değil varyant seviyesinde yapılmalıdır.

Ürün detayındaki variants[].id değerini variant parametresi olarak kullanın.

Ürün oluşturma senaryosu

1. GET /categories ile uygun BYNovax category_id bulun.
2. ERP ürününüzün name, sku, barcode, price, stock,
   description ve image_urls alanlarını hazırlayın.
3. Benzersiz Idempotency-Key üretin.
4. POST /products gönderin.
5. Dönen product ID/UID bilgisini ERP eşlemenizde saklayın.
6. Sonraki fiyat ve stok değişikliklerinde ilgili
   Inventory / Pricing API'lerini kullanın.

Sık karşılaşılan hatalar

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

• GET /products çağrısı 200 dönüyor.
• Yeni oluşturulan ürün listede görünüyor.
• GET /products/{product} ürün detayını döndürüyor.
• ERP tarafında BYNovax product ID eşlemesi saklanıyor.

ERP eşleme önerisi

• Harici sistem kendi product ID değerini saklar.
• BYNovax response içindeki product id / uid eşleme tablosuna yazılır.
• Sonraki PATCH, inventory ve pricing işlemleri bu mapping üzerinden yapılır.
• SKU ve barkod business identifier olarak kullanılabilir fakat canonical BYNovax ID ayrıca saklanmalıdır.

Toplu ürün işlemleri

• BYNovax External Commerce API V1 toplu ürün işlemlerinde en fazla 100 ürün kabul eder.
• POST /products/bulk/validate payload doğrular; ürün, idempotency veya stok/fiyat verisi üzerinde mutation yapmaz.
• POST /products/bulk/create yeni ürünleri toplu oluşturur.
• PATCH /products/bulk/update mevcut ürünlerin lifecycle alanlarını toplu günceller.
• POST /products/bulk/upsert external_id, product_id veya SKU authority üzerinden ürünün oluşturulmasına veya güncellenmesine karar verir.
• POST /products/bulk/delete ürünleri fiziksel olarak silmez; lifecycle durumunu archived yapar ve normal External API ürün liste/detay görünümünden kaldırır.
• bulk/delete için product_id, external_id, SKU veya barkod kullanılabilir. Her products[] kaydı tam olarak bir ürün tanımlayıcı taşımalıdır.
• Tüm bulk write endpointleri products:write scope gerektirir.
• store_id istemci tarafından gönderilemez; mağaza authority API credential üzerinden belirlenir.

Bulk endpoint özeti

• POST /products/bulk/validate — mutation yapmadan create, update veya upsert payload doğrulaması.
• POST /products/bulk/create — 1 ile 100 arasında yeni ürün oluşturma.
• PATCH /products/bulk/update — mevcut ürünlerde lifecycle alanlarını toplu güncelleme.
• POST /products/bulk/upsert — mevcut ürünü bulursa update, bulamazsa create.
• POST /products/bulk/delete — 1 ile 100 ürünü product_id, external_id, SKU veya barkod ile güvenli biçimde arşivler.
• PATCH /inventory/bulk — stok güncellemelerinin authoritative endpointi.
• PATCH /prices/bulk — fiyat güncellemelerinin authoritative endpointi.

Toplu ürün silme / arşivleme

• Her products[] kaydında product_id, external_id, sku veya barcode alanlarından yalnızca biri kullanılmalıdır.
• SKU ve barkod canonical kod normalizasyonuyla çözülür.
• Ürün yalnızca credential'ın bağlı olduğu mağaza kapsamında aranır.
• store_id göndererek başka mağaza seçilemez.
• Zaten arşivlenmiş ürün skipped / already_deleted sonucuyla dönebilir.
• Bulunamayan seçim skipped / product_not_found olarak dönebilir.
• Batch sonucu deleted, skipped ve failed sayaçlarıyla raporlanır.

Idempotency-Key

• bulk/create, bulk/update, bulk/upsert ve bulk/delete write çağrılarında Idempotency-Key zorunludur.
• Aynı Idempotency-Key ve aynı payload tekrar gönderildiğinde önceki tamamlanmış sonuç replay edilir.
• Aynı Idempotency-Key farklı HTTP methodu, farklı path veya farklı payload ile kullanılırsa 409 idempotency_key_conflict döner.
• Önerilen format: erp-bulk-products-20260917-000001 gibi çağrı bazında benzersiz bir anahtar.
• validate endpointi mutation yapmadığı için Idempotency-Key gerektirmez.

Bulk create request örneği

• POST https://bynovax.com/api/external/v1/products/bulk/create Authorization: Bearer <token> Idempotency-Key: erp-bulk-create-20260917-000001 Content-Type: application/json { "products": [ { "external_id": "ERP-10001", "name": "Örnek Ürün", "sku": "ERP-SKU-10001", "barcode": "8690000001001", "category_id": 123, "brand": "Örnek Marka", "price": 799.90, "compare_at_price": 899.90, "stock": 25, "currency": "TRY", "tax_rate": 20, "status": "active", "active": true, "description": "ERP üzerinden oluşturulan ürün.", "image_urls": [ "https://cdn.example.com/product-1.jpg", "https://cdn.example.com/product-2.jpg" ], "variants": [ { "sku": "ERP-SKU-10001-S", "barcode": "8690000001002", "option1_name": "Beden", "option1_value": "S", "price": 799.90, "stock": 10, "currency": "TRY", "status": "active" }, { "sku": "ERP-SKU-10001-M", "barcode": "8690000001003", "option1_name": "Beden", "option1_value": "M", "price": 799.90, "stock": 15, "currency": "TRY", "status": "active" } ] } ] }

Bulk create alanları

• name — zorunlu ürün adı.
• sku — zorunlu ürün SKU değeri; canonical create sırasında büyük harfe normalize edilir.
• barcode — zorunlu barkod; canonical create sırasında normalize edilir.
• category_id — zorunlu ve credential mağazasına ait aktif kategori olmalıdır.
• price — zorunlu başlangıç fiyatı.
• stock — zorunlu başlangıç stok değeri; varyant varsa ürün toplam stoku varyant stoklarının toplamından hesaplanır.
• description — zorunlu ürün açıklaması.
• image_urls — zorunlu, minimum 1 maksimum 12 görsel URL.
• external_id — ERP veya kaynak sisteminizdeki ürün kimliği; upsert/eşleme için kullanılması önerilir.
• variants — opsiyonel, ürün başına maksimum 100 varyant.
• brand, compare_at_price, currency, tax_rate, status, active ve short_description desteklenir.

Bulk validate örneği

• POST https://bynovax.com/api/external/v1/products/bulk/validate Content-Type: application/json { "mode": "create", "products": [ { "external_id": "ERP-10001", "name": "Örnek Ürün", "sku": "ERP-SKU-10001", "barcode": "8690000001001", "category_id": 123, "price": 799.90, "stock": 25, "description": "Doğrulama örneği", "image_urls": [ "https://cdn.example.com/product-1.jpg" ] } ] }
• mode alanı create, update veya upsert olabilir.
• validate yanıtında received, valid ve invalid sayıları ile item bazlı errors listesi döner.
• validate çağrısı ürün veya idempotency kaydı oluşturmaz.

Bulk update ve authority ayrımı

• PATCH https://bynovax.com/api/external/v1/products/bulk/update Idempotency-Key: erp-bulk-update-20260917-000001 Content-Type: application/json { "products": [ { "product_id": 7314, "name": "Yeni ürün adı", "brand": "Yeni marka", "active": true } ] }
• Update locator olarak product_id, external_id veya SKU kullanılabilir.
• Lifecycle bulk update alanları category_id, name, short_description, description, brand, sku, barcode, status ve active alanlarıdır.
• price, compare_at_price, currency ve stock lifecycle bulk update üzerinden değiştirilmez.
• Fiyat için PATCH /prices/bulk kullanın.
• Stok için PATCH /inventory/bulk kullanın.
• Varyant lifecycle değişiklikleri /products/{product}/variants/... endpointleri üzerinden yapılmalıdır.
• Bu authority ayrımı pricing, inventory ve product webhook/event semantiğinin tutarlı kalmasını sağlar.

Bulk upsert örneği

• POST https://bynovax.com/api/external/v1/products/bulk/upsert Idempotency-Key: erp-bulk-upsert-20260917-000001 Content-Type: application/json { "products": [ { "external_id": "ERP-10001", "name": "ERP Ürün 10001 Güncel", "brand": "Örnek Marka" }, { "external_id": "ERP-10002", "name": "ERP Ürün 10002", "sku": "ERP-SKU-10002", "barcode": "8690000002001", "category_id": 123, "price": 499.90, "stock": 8, "description": "Yeni ürün", "image_urls": [ "https://cdn.example.com/product-2.jpg" ] } ] }
• external_id eşleşirse mevcut ürün update edilir.
• external_id eşleşmez ve create zorunlu alanları mevcutsa yeni ürün oluşturulur.
• product_id mevcutsa tenant kapsamı içinde doğrudan ürün authority olarak kullanılabilir.
• SKU fallback locator olarak kullanılabilir.
• Başka mağazaya ait product_id hiçbir zaman cross-tenant update yapamaz.

Partial success response

• { "success": false, "data": { "mode": "create", "summary": { "received": 3, "created": 2, "updated": 0, "failed": 1 }, "results": [ { "index": 0, "status": "created", "action": "create", "external_id": "ERP-10001", "product_id": 7314, "errors": [] }, { "index": 1, "status": "failed", "action": "create", "external_id": "ERP-10002", "errors": [ { "code": "product_create_failed", "message": "Ürün oluşturulamadı." } ] } ] } }
• HTTP transport başarılı olsa bile item bazında failed sonuç bulunabilir.
• Entegrasyon tarafında yalnız HTTP status kontrol etmeyin; data.summary.failed ve data.results[].status alanlarını da kontrol edin.
• Başarılı itemlar geri alınmaz; bulk contract partial success destekler.

Hata kodları ve entegrasyon davranışı

• 401 authentication_context_missing — API credential geçersiz veya eksik.
• 403 — gerekli products:write scope yok.
• 409 idempotency_key_conflict — aynı key farklı istek için kullanıldı.
• 409 idempotency_request_in_progress — aynı key halen işleniyor.
• 422 validation_failed — bulk envelope veya ürün alanları geçersiz.
• 422 store_authority_violation — request içinde store_id gönderilmeye çalışıldı.
• product_not_found — update locator credential mağazasında ürün çözümleyemedi.
• product_code_conflict — SKU veya barkod mağaza namespace'i içinde çakıştı.
• variant_code_conflict — varyant SKU/barkodu ürün veya varyant namespace'i ile çakıştı.
• separate_authority_required — fiyat, stok, görsel veya varyant lifecycle update yanlış endpoint üzerinden gönderildi.

cURL — bulk create

• curl -X POST "https://bynovax.com/api/external/v1/products/bulk/create" \ -H "Authorization: Bearer <token>" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: erp-bulk-create-20260917-000001" \ --data '{ "products": [ { "external_id": "ERP-10001", "name": "Örnek Ürün", "sku": "ERP-SKU-10001", "barcode": "8690000001001", "category_id": 123, "price": 799.90, "stock": 25, "description": "ERP ürünü", "image_urls": [ "https://cdn.example.com/product.jpg" ] } ] }'

ERP entegrasyon kontrol listesi

• Her ürün için mümkünse değişmeyen external_id üretin ve saklayın.
• Her bulk write çağrısında benzersiz Idempotency-Key kullanın.
• Tek istekte maksimum 100 ürün gönderin.
• Gönderim öncesinde /products/bulk/validate kullanabilirsiniz.
• data.results dizisini item bazında işleyin; yalnız success alanına güvenmeyin.
• BYNovax product_id ve product_uid değerlerini ERP eşleme tablonuzda saklayın.
• Fiyat değişikliklerini /prices/bulk ile yönetin.
• Stok değişikliklerini /inventory/bulk ile yönetin.
• Variant değişikliklerinde variant lifecycle endpointlerini kullanın.
• store_id göndermeyin; tenant authority credential üzerinden gelir.
• Retry sırasında aynı logical operation için aynı Idempotency-Key kullanın.