DEV Community

Cover image for BigCommerce API Kullanımı: E-Ticaret Entegrasyonu Geliştirici Rehberi
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

BigCommerce API Kullanımı: E-Ticaret Entegrasyonu Geliştirici Rehberi

#tutorial #api #webdev #programming

Kısaca

BigCommerce API'leri ile ürün, sipariş, müşteri ve mağaza operasyonlarını programatik olarak yönetebilirsiniz. Kimlik doğrulama için API token'ları (sunucu tarafı) veya OAuth (uygulama tarafı) kullanılır. REST uç noktalarına (api.bigcommerce.com) istek atılır ve gerçek zamanlı güncellemeler için webhook'lar kurulur. API çağrılarınızı kayıt altına almak, yanıtları doğrulamak ve ekip içinde koleksiyonlarınızı paylaşmak için test ortamı olarak Apidog'u kullanabilirsiniz.

Apidog'u hemen deneyin

Giriş

BigCommerce, 60.000'den fazla çevrimiçi mağazaya hizmet verir ve çok çeşitli entegrasyonlara ihtiyaç duyan işletmeler için API altyapısı sunar: envanter senkronizasyonu, sipariş işleme, müşteri yönetimi, ödeme yönetimi gibi. Üç ana API tipi mevcut: Storefront API (headless), Management API (arka uç), Payments API (ödeme işlemleri). Geliştiricilerin çoğu Management API üzerinde çalışır ve mağaza arka plan süreçlerini yönetir.

Belgelere göz atmak karmaşık görünebilir, özellikle kimlik doğrulama ve webhook süreçleri arasında dolaşırken. Bu rehber, gerçek projede ihtiyacınız olacak görevleri ve entegrasyonları pratik olarak anlatır: ürün, sipariş, müşteri yönetimi ve webhook entegrasyonu. Kimlik doğrulamasını, temel API desenlerini ve canlı mağazayı etkilemeden entegrasyonlarınızı nasıl test edeceğinizi öğreneceksiniz.

💡 BigCommerce entegrasyonları geliştiriyorsanız, Apidog ile API çağrılarını tasarlayın, test edin ve dökümante edin. İstekleri koleksiyonlara kaydedin, farklı mağazalar için ortam değişkenleri kullanın ve yanıtların doğruluğunu kolayca kontrol edin. Gerçek müşterileri etkilemeden hataları erkenden yakalayın.

BigCommerce API'lerinizi Apidog ile test edin - ücretsiz

Bu Kılavuzda Öğrenecekleriniz

  • BigCommerce kimlik doğrulamasını pratik olarak kurma
  • Ürün, varyant ve envanter yönetimi
  • Sipariş ve müşteri veri yönetimi
  • Webhook ile gerçek zamanlı tetikleme
  • Entegrasyonları Apidog ile test ve dökümante etme

Kimlik Doğrulama: Mağazaya Erişim

BigCommerce üzerinde geliştirmenize göre iki kimlik doğrulama yöntemi bulunur:

Yöntem 1: API Token'ları (Özel Entegrasyonlar İçin)

Tek bir mağaza ile çalışan script veya servisler için API token'ı kullanın.

API hesabı oluşturma adımları:

  1. Mağaza yönetim paneline giriş yapın
  2. Ayarlar → API Hesapları → API Hesabı Oluştur
  3. “V3/V2 API Token” seçin
  4. İhtiyacınız olan izinleri (Ürünler, Siparişler, Müşteriler vs.) tanımlayın
  5. Kimlik bilgilerini not edin

Elde edeceğiniz bilgiler:

  • Mağaza URL'si: mystore.mybigcommerce.com
  • Erişim Token'ı: abc123def456...
  • Müşteri Kimliği ve Sırrı

API çağrısı örneği:

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Enter fullscreen mode Exit fullscreen mode

store-hash, hem API yolunda hem yönetici URL'sinde bulunur.

Yöntem 2: OAuth (Pazar Yeri Uygulamaları İçin)

Marketplace uygulamaları için OAuth kullanılır.

OAuth akışı:

  1. Kullanıcı uygulamanızı yükler
  2. BigCommerce, yetkilendirme kodu ile redirect (callback) adresinize yönlendirir
  3. Sunucunuz kodu, erişim token'ına çevirir
  4. Token'ı saklayıp API çağrılarında kullanırsınız

Token alma örneği:

const response = await fetch('https://login.bigcommerce.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: process.env.BC_CLIENT_ID,
    client_secret: process.env.BC_CLIENT_SECRET,
    redirect_uri: 'https://yourapp.com/auth/callback',
    grant_type: 'authorization_code',
    code: authCode,
    scope: 'store_v2_default store_v3_products'
  })
})

const { access_token, context } = await response.json()
// access_token API çağrılarında kullanılır
// context, store_hash içerir
Enter fullscreen mode Exit fullscreen mode

API çağrısı:

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json"
Enter fullscreen mode Exit fullscreen mode

Ürünler ve Katalog Yönetimi

Ürünleri Listele 

GET https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Yanıt:

{
  "data": [
    {
      "id": 174,
      "name": "Plain T-Shirt",
      "type": "physical",
      "sku": "PLAIN-T",
      "price": 29.99,
      "sale_price": 24.99,
      "inventory_level": 150,
      "inventory_tracking": "product",
      "is_visible": true,
      "categories": [23, 45],
      "brand_id": 12
    }
  ],
  "meta": {
    "pagination": {
      "total": 500,
      "count": 50,
      "page": 1,
      "per_page": 50
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Yeni Ürün Oluştur 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Content-Type: application/json

{
  "name": "Premium Hoodie",
  "type": "physical",
  "sku": "HOODIE-PREM",
  "price": 79.99,
  "description": "Premium pamuk karışımlı kapüşonlu sweatshirt",
  "weight": 1.5,
  "width": 20,
  "height": 28,
  "depth": 2,
  "inventory_level": 100,
  "inventory_tracking": "product",
  "is_visible": true,
  "categories": [23]
}
Enter fullscreen mode Exit fullscreen mode

Ürün Varyantı Güncelle

Örneğin, bir varyantın SKU, fiyat ve stoğunu güncellemek için:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "sku": "HOODIE-PREM-BLK-M",
  "price": 79.99,
  "inventory_level": 50,
  "option_values": [
    {
      "option_display_name": "Color",
      "label": "Black"
    },
    {
      "option_display_name": "Size",
      "label": "Medium"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Envanteri Yönet

Tüm ürün veya sadece varyant stoku şöyle güncellenir:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "inventory_level": 75
}
Enter fullscreen mode Exit fullscreen mode

Varyant için:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
Content-Type: application/json

{
  "inventory_level": 25
}
Enter fullscreen mode Exit fullscreen mode

Siparişler ve Karşılama

Orders V2 API ile sipariş oluşturma, güncelleme ve karşılamalar yönetilir.

Siparişleri Listele 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Yanıt örneği:

[
  {
    "id": 115,
    "status": "Awaiting Fulfillment",
    "status_id": 11,
    "customer_id": 45,
    "date_created": "2026-03-24T10:30:00+00:00",
    "subtotal_ex_tax": 149.99,
    "total_inc_tax": 162.49,
    "items_total": 2,
    "items_shipped": 0,
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "street_1": "123 Main St",
      "city": "Austin",
      "state": "Texas",
      "zip": "78701",
      "country": "United States"
    }
  }
]
Enter fullscreen mode Exit fullscreen mode

Sipariş Detaylarını Al 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Enter fullscreen mode Exit fullscreen mode

Sipariş Ürünlerini Al 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/products
X-Auth-Token: {token}
Enter fullscreen mode Exit fullscreen mode

Sipariş Durumunu Güncelle 

PUT https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "status_id": 12
}
Enter fullscreen mode Exit fullscreen mode

Yaygın durum kimlikleri:

  • 0: Tamamlanmamış
  • 11: Sipariş Karşılaması Bekleniyor
  • 12: Tamamlandı
  • 5: İptal Edildi
  • 4: İade Edildi

Gönderi (Shipment) Oluştur 

POST https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/shipments
X-Auth-Token: {token}
Content-Type: application/json

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "shipping_method": "UPS Ground",
  "items": [
    {
      "order_product_id": 234,
      "quantity": 1
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Müşteriler ve Segmentasyon

Customers V3 API ile müşteri verileri ve segmentasyonu yönetilebilir.

Müşterileri Listele 

GET https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

Yanıt:

{
  "data": [
    {
      "id": 45,
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "company": "Acme Corp",
      "phone": "512-555-1234",
      "customer_group_id": 1,
      "notes": "VIP customer",
      "tax_exempt_category": "",
      "date_created": "2025-11-15T09:30:00+00:00",
      "date_modified": "2026-03-20T14:22:00+00:00"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Yeni Müşteri Oluştur 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Content-Type: application/json

{
  "email": "jane.smith@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "512-555-5678",
  "customer_group_id": 2
}
Enter fullscreen mode Exit fullscreen mode

Müşteri Güncelle 

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/customers/{customer-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "notes": "Tekrarlayan müşteri - öncelikli destek",
  "customer_group_id": 3
}
Enter fullscreen mode Exit fullscreen mode

Gerçek Zamanlı Güncellemeler: Webhook'lar

Webhook'lar, mağazada bir olay gerçekleştiğinde uygulamanıza POST isteği gönderir. Sorgulama yerine, olayda tetiklenir.

Webhook Oluşturma 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/hooks
X-Auth-Token: {token}
Content-Type: application/json

{
  "scope": "store/order/created",
  "destination": "https://yourapp.com/webhooks/orders",
  "is_active": true
}
Enter fullscreen mode Exit fullscreen mode

Mevcut kapsamlar:

  • store/order/created
  • store/order/updated
  • store/order/archived
  • store/product/created
  • store/product/updated
  • store/product/deleted
  • store/customer/created
  • store/inventory/updated

Webhook İmzalarını Doğrulama

Webhook'un BigCommerce tarafından gönderildiğini doğrulamak için:

import crypto from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

app.post('/webhooks/orders', (req, res) => {
  const signature = req.headers['x-bc-webhook-signature']
  const payload = JSON.stringify(req.body)

  if (!verifyWebhook(payload, signature, process.env.BC_CLIENT_SECRET)) {
    return res.status(401).send('Geçersiz imza')
  }

  // Webhook'u işle
  console.log('Sipariş oluşturuldu:', req.body.data.id)
  res.status(200).send('OK')
})
Enter fullscreen mode Exit fullscreen mode

BigCommerce API'lerini Apidog ile Test Etme

BigCommerce API'leri, doğru başlıklar ve kimlik doğrulama gerektirir. Manuel testler yorucu olur, Apidog bu süreci hızlandırır.

Apidog ile BigCommerce Test

1. Ortam Kurulumu

Her mağaza için ortamlar oluşturun:

# Üretim Mağazası
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123

# Sahneleme Mağazası
STORE_HASH: staging456
ACCESS_TOKEN: staging_token
BASE_URL: https://api.bigcommerce.com/stores/staging456
Enter fullscreen mode Exit fullscreen mode

2. Ön-İstek Komut Dosyaları

Kimlik doğrulama başlıklarını otomatik ekleyin:

pm.request.headers.add({
  key: 'X-Auth-Token',
  value: pm.environment.get('ACCESS_TOKEN')
})
pm.request.headers.add({
  key: 'Accept',
  value: 'application/json'
})
Enter fullscreen mode Exit fullscreen mode

3. Yanıtları Doğrula

Ürünlerin gerekli alanlara sahip olup olmadığını test edin:

pm.test('Ürünlerin gerekli alanları var', () => {
  const response = pm.response.json()
  response.data.forEach(product => {
    pm.expect(product).to.have.property('id')
    pm.expect(product).to.have.property('name')
    pm.expect(product).to.have.property('price')
    pm.expect(product.price).to.be.above(0)
  })
})

pm.test('Sayfalandırma çalışıyor', () => {
  const response = pm.response.json()
  pm.expect(response.meta.pagination).to.have.property('total')
  pm.expect(response.meta.pagination.page).to.eql(1)
})
Enter fullscreen mode Exit fullscreen mode

BigCommerce API'lerini Apidog ile test edin - ücretsiz

Yaygın Hatalar ve Çözümleri

401 Yetkilendirilmemiş

Sebep: Geçersiz ya da eksik erişim token'ı.

Çözüm:

  1. X-Auth-Token başlığınızın ayarlandığını kontrol edin
  2. Token'ın geçerli ve aktif olduğundan emin olun
  3. API hesabınızda gerekli izinlerin tanımlı olduğundan emin olun

403 Yasak

Sebep: Token geçerli ama izin kapsamı yetersiz.

Çözüm:

  1. API hesabınızın izinlerini gözden geçirin
  2. Eksik kapsamı ekleyin
  3. Gerekirse yeni bir token oluşturun

404 Bulunamadı

Sebep: Yanlış uç nokta ya da kaynak yok.

Çözüm:

  1. Mağaza hash'ini doğrulayın
  2. Doğru API versiyonunu (v2/v3) kullandığınızdan emin olun
  3. Kaynak kimliğinin varlığını kontrol edin

429 Çok Fazla İstek

Sebep: Oran limiti aşıldı.

Çözüm:

BigCommerce, farklı uç noktalar için farklı oran limitleri belirler (Ürünler: 10.000/saat, Siparişler: 30.000/saat). Yanıt başlığındaki X-Rate-Limit-Remaining değerini izleyin ve otomatik backoff ekleyin:

async function callWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fn()
    if (response.status === 429) {
      const retryAfter = response.headers.get('X-Rate-Limit-Reset')
      await new Promise(r => setTimeout(r, retryAfter * 1000))
    } else {
      return response
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

422 İşlenemeyen Varlık

Sebep: Gövde doğrulama hatası.

Çözüm:

Yanıttaki hata detayını inceleyin:

{
  "errors": {
    "price": "Fiyat sıfırdan büyük olmalıdır",
    "sku": "SKU zaten mevcut"
  }
}
Enter fullscreen mode Exit fullscreen mode

Alternatifler ve Karşılaştırmalar

Özellik BigCommerce Shopify WooCommerce
API sürümleme V2 ve V3 REST ve GraphQL REST
Oran sınırlamaları 10K-30K/saat 2/dk (sızıntılı kova) Barındırmaya bağlı
Webhook'lar Evet Evet Evet (eklenti)
GraphQL Hayır Evet Hayır
SDK kalitesi İyi Mükemmel Yalnızca PHP
Çoklu mağaza Evet Hayır Hayır

BigCommerce V3 API, Shopify'ın parça parça API yapısına göre daha tutarlıdır; ancak Shopify GraphQL ile karmaşık sorgularda daha esnektir.

Gerçek Dünya Kullanım Senaryoları

  • Çok kanallı envanter senkronizasyonu:

    BigCommerce, Amazon ve fiziksel mağazada satış yapan bir marka, Ürünler API'si ile envanteri kanallar arası eşitler. Apidog ile entegrasyonları yayına almadan önce test eder.

  • Sipariş otomasyonu:

    Abonelik bazlı bir şirket, sipariş oluştuğunda webhook tetikleyip Orders API ile takip numarasını günceller. Depo, webhook handler ile otomatik toplama listesi alır.

  • Müşteri segmentasyonu:

    Bir e-ticaret sitesi, Customers API ile satın alma geçmişine göre müşterileri segmentlere ayırır. VIP müşteriler özel fiyatlandırmaya sahip gruba eklenir ve bu süreç zamanlanmış görevle otomatikleştirilir.

Sonuç

Bu rehber ile:

  • Kimlik doğrulama yöntemlerini (API Token & OAuth) öğrendiniz
  • V3 Katalog API ile ürün ve varyant yönetimini uyguladınız
  • V2 Orders API ile sipariş süreçlerini yönettiniz
  • V3 Customers API ile müşteri veri yönetimini gördünüz
  • Webhook ile gerçek zamanlı entegrasyon kurdunuz
  • Apidog ile entegrasyonlarınızı test edip belgelediniz

Sonraki adımlarınız:

  1. BigCommerce mağazanız için API hesabı oluşturun
  2. Ürünleri listeleyen ilk API çağrınızı yapın
  3. Siparişler için bir webhook tanımlayın
  4. API çağrılarınızı Apidog'a kaydedin
  5. Entegrasyonunuzu geliştirin

BigCommerce API'lerini Apidog ile test edin - ücretsiz

Sıkça Sorulan Sorular

V2 ve V3 API'leri arasındaki fark nedir?

V3 daha yeni ve tutarlı; ürün, kategori, marka ve müşteri için V3 kullanın. Siparişlerde ise henüz hepsi V3'e taşınmadığı için V2 ile çalışılır. Çoğu projede ikisi birlikte kullanılır.

Mağaza hash'imi nasıl bulurum?

Yönetici URL'nizde: https://store-abc123.mybigcommerce.com/manage → abc123 kısmı hash'tir. API hesabı oluştururken de görünür.

API'yi deneme mağazasında kullanabilir miyim?

Evet, deneme mağazaları tam API erişimi sunar. Canlıya geçmeden önce geliştirme ve test için idealdir.

API çağrılarında oran limiti nedir?

Uç noktaya göre değişir: Ürünler için 10.000/saat, siparişler için 30.000/saat. Yanıt başlığındaki X-Rate-Limit-Remaining ile güncel limitinizi takip edin.

Sayfalandırmayı nasıl yönetirim?

page ve limit parametreleri ile. Varsayılan limit 50'dir, meta.pagination ile toplam sayfa sayısını alın ve döngü kurun.

let allProducts = []
let page = 1

while (true) {
  const response = await fetch(
    `${baseUrl}/v3/catalog/products?page=${page}&limit=100`,
    { headers: { 'X-Auth-Token': token } }
  )
  const data = await response.json()
  allProducts.push(...data.data)

  if (page >= data.meta.pagination.total_pages) break
  page++
}
Enter fullscreen mode Exit fullscreen mode

API ile ürün resimleri yükleyebilir miyim?

Evet, ürün görseli yükleme uç noktası:

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/images
Content-Type: application/json

{
  "image_url": "https://example.com/image.jpg",
  "is_thumbnail": true
}
Enter fullscreen mode Exit fullscreen mode

Para birimi ve çoklu mağaza yönetimi nasıl olur?

BigCommerce mağazalarının bir ana para birimi vardır. Çoklu para birimi API ile değil, vitrin üzerinden yönetilir. Birden fazla mağaza için ayrı API hesapları ve Apidog'da farklı ortamlar tanımlayın.

Webhook uç noktam kapalıysa ne olur?

BigCommerce, başarısız webhook'ları üstel geri çekilme ile yeniden dener. 24 saatte 5 kez başarısız olursa webhook devre dışı olur. Uç noktalarınızı izleyin ve hata durumunda uyarı alın.

Top comments (0)