DEV Community

Cover image for كيفية استخدام واجهات برمجة تطبيقات BigCommerce: دليل المطور لدمج التجارة الإلكترونية
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام واجهات برمجة تطبيقات BigCommerce: دليل المطور لدمج التجارة الإلكترونية

#api #backend #tutorial #webdev

ملخص

تتيح لك واجهات برمجة تطبيقات BigCommerce إدارة المنتجات، الطلبات، العملاء، وعمليات المتجر بشكل برمجي وفعال. يمكنك المصادقة عبر رموز API أو OAuth، واستدعاء نقاط نهاية REST على api.bigcommerce.com، والتعامل مع Webhooks لتلقّي التحديثات الفورية. لاختبار عمليات التكامل ومشاركتها مع فريقك، استخدم Apidog لحفظ استدعاءات API والتحقق من صحة الاستجابات.

جرّب Apidog اليوم

مقدمة

تدعم BigCommerce أكثر من 60,000 متجر إلكتروني. كل متجر يحتاج إلى تكامل مخصص: مزامنة مخزون، معالجة طلبات، إدارة عملاء، وتنفيذ عمليات دفع. هنا يأتي دور الـ APIs.

توفر المنصة ثلاث واجهات API رئيسية:

  • Storefront API (للتجارة بدون واجهة أمامية)
  • Management API (لإدارة الكواليس)
  • Payments API (للمعاملات)

أغلب المطورين يتعاملون مع Management API لإدارة المنتجات، الطلبات، والعملاء.

غالبًا ما يكون التنقل بين وثائق المصادقة وWebhooks ومراجع API مربكًا. في هذا الدليل ستجد الخطوات العملية لإدارة المنتجات، الطلبات، العملاء، وWebhooks مع كيفية المصادقة واختبار عمليات التكامل قبل الإطلاق.

💡 إذا كنت تبني تكاملات لـ BigCommerce، سيساعدك Apidog على تصميم، اختبار، وتوثيق استدعاءات API بسهولة. احفظ الطلبات كمجموعات، استخدم متغيرات البيئة للمتاجر المختلفة، وتحكم في صحة الاستجابات. اكتشف الأخطاء مبكرًا قبل وصولها للعملاء الحقيقيين.

اختبر واجهات برمجة تطبيقات BigCommerce الخاصة بك باستخدام Apidog - مجانًا.

بنهاية الدليل ستكون قادرًا على:

  • إعداد مصادقة BigCommerce
  • إدارة المنتجات والمتغيرات والمخزون
  • معالجة الطلبات وبيانات العملاء
  • إعداد Webhooks للتحديثات الفورية
  • اختبار وتوثيق عمليات التكامل باستخدام Apidog

المصادقة: الوصول إلى متجرك

الطريقة الأولى: رموز API (للتكاملات المخصصة)

لبناء اسكربت أو خدمة لمتجر واحد، استخدم رموز API.

خطوات إعداد حساب API:

  1. اذهب للوحة تحكم متجرك.
  2. الإعدادات ← حسابات API ← إنشاء حساب API.
  3. اختر "رمز API V3/V2".
  4. حدد النطاقات المطلوبة (منتجات، طلبات، عملاء، إلخ).
  5. احفظ بيانات الاعتماد.

تحصل على:

  • عنوان URL للمتجر: mystore.mybigcommerce.com
  • رمز الوصول: abc123def456...
  • معرف العميل: abc123...
  • سر العميل: xyz789...

مثال استدعاء API:

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 هو الجزء بعد /stores/ في مسار API.

الطريقة الثانية: OAuth (لتطبيقات المتجر)

إذا كنت تطور تطبيقًا لسوق BigCommerce، استخدم OAuth.

تدفق OAuth:

  1. المستخدم يثبت التطبيق.
  2. BigCommerce يعيد التوجيه إلى عنوان callback مع رمز.
  3. خادمك يستبدل الرمز برمز وصول.
  4. خزّن الرمز لاستخدامه في استدعاءات API لاحقًا.

تبادل الرمز بالوصول:

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
// context يحتوي على store_hash
Enter fullscreen mode Exit fullscreen mode

استخدام الرمز:

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

إدارة المنتجات والكتالوج

سرد المنتجات 

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

استجابة نموذجية:

{
  "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

إنشاء منتج 

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 cotton blend hoodie",
  "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

تحديث متغيرات المنتج 

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

إدارة المخزون

تحديث مستوى المنتج:

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

تحديث مخزون متغير:

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

الطلبات والتسليم

سرد الطلبات 

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

استجابة نموذجية:

[
  {
    "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

الحصول على تفاصيل الطلب 

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

الحصول على منتجات الطلب 

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

تحديث حالة الطلب 

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

معرفات شائعة:

  • 0: غير مكتمل
  • 11: بانتظار التسليم
  • 12: مكتمل
  • 5: ملغي
  • 4: مسترد

إنشاء شحنة (تسليم) 

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

العملاء والتجزئة

سرد العملاء 

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

استجابة نموذجية:

{
  "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

إنشاء عميل 

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

تحديث العميل 

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

{
  "notes": "Repeat customer - priority support",
  "customer_group_id": 3
}
Enter fullscreen mode Exit fullscreen mode

Webhooks للتحديثات الفورية

Webhooks ترسل إشعارات لتطبيقك عند حدوث أحداث بالمتجر، ما يلغي الحاجة للاستعلام الدوري.

إنشاء Webhook 

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

أمثلة النطاقات:

  • 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

تحقق من التوقيع لضمان أصالة Webhook:

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('Invalid signature')
  }

  // معالجة الـ webhook
  console.log('تم إنشاء الطلب:', req.body.data.id)
  res.status(200).send('OK')
})
Enter fullscreen mode Exit fullscreen mode

اختبار واجهات برمجة تطبيقات BigCommerce باستخدام Apidog

تتطلب APIs من BigCommerce رؤوسًا موحدة ومصادقة دقيقة. يوفر Apidog بيئة متقدمة لاختبار وتوثيق هذه العمليات.

Image 236

1. إعداد البيئة

أنشئ بيئات منفصلة لكل متجر:

# متجر الإنتاج
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123

# متجر التجربة
STORE_HASH: staging456
ACCESS_TOKEN: staging_token
BASE_URL: https://api.bigcommerce.com/stores/staging456
Enter fullscreen mode Exit fullscreen mode

2. سكربتات ما قبل الطلب

لإضافة رؤوس المصادقة تلقائيًا:

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. التحقق من صحة الاستجابات

تأكد أن المنتجات تحتوي الحقول المطلوبة:

pm.test('يجب أن تحتوي المنتجات على الحقول المطلوبة', () => {
  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('الترقيم يعمل', () => {
  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 باستخدام Apidog - مجانًا

الأخطاء الشائعة والإصلاحات

401 غير مصرح به

السبب: رمز وصول غير صالح أو مفقود.

الإصلاح:

  1. تحقق من وجود رأس X-Auth-Token.
  2. تأكد أن الرمز لم يُلغى.
  3. تحقق من صلاحيات حساب API.

403 ممنوع

السبب: الرمز صالح لكن يفتقر للنطاق المطلوب.

الإصلاح:

  1. تحقق من أذونات API.
  2. أضف النطاق اللازم.
  3. أنشئ رمز جديد بأذونات موسعة.

404 غير موجود

السبب: نقطة نهاية أو معرف مورد غير صحيح.

الإصلاح:

  1. تأكد من صحة store hash.
  2. تحقق من إصدار API في العنوان (V2 أو V3).
  3. تأكد من وجود معرف المورد.

429 عدد كبير من الطلبات

السبب: تجاوز حد المعدل.

الإصلاح: المنتجات: 10,000/ساعة. الطلبات: 30,000/ساعة. راقب رأس X-Rate-Limit-Remaining وطبّق backoff.

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 كيان غير قابل للمعالجة

السبب: خطأ في صحة البيانات.

الإصلاح: تحقق من الاستجابة:

{
  "errors": {
    "price": "Price must be greater than zero",
    "sku": "SKU already exists"
  }
}
Enter fullscreen mode Exit fullscreen mode

البدائل والمقارنات

الميزة BigCommerce Shopify WooCommerce
إصدار API V2 و V3 REST و GraphQL REST
حدود المعدل 10-30 ألف/ساعة 2/دقيقة يعتمد على الاستضافة
Webhooks نعم نعم نعم (إضافة)
GraphQL لا نعم لا
جودة SDK جيد ممتاز PHP فقط
متعدد المتاجر نعم لا لا

V3 API من BigCommerce أكثر اتساقًا من Shopify، بينما يوفر Shopify مرونة استعلام أكبر عبر GraphQL.

حالات الاستخدام الواقعية

  • مزامنة المخزون متعددة القنوات: استخدم Products API لمزامنة المخزون بين BigCommerce، Amazon، والمتاجر الفعلية، وجرّب نقاط النهاية باستخدام Apidog قبل كل نشر.
  • أتمتة الطلبات: استخدم Webhooks لتفعيل التسليم عند إنشاء طلب. حدّث أرقام التتبع عبر Orders API. قوائم الانتقاء تصل للمستودع تلقائيًا عبر Webhook.
  • تجزئة العملاء: استخدم Customers API لتقسيم العملاء اعتمادًا على سجل الشراء. أضف عملاء VIP إلى مجموعة أسعار خاصة. نفّذ التكامل أسبوعيًا عبر مهمة مجدولة.

الخاتمة

ملخص ما تعلمته:

  • المصادقة تتم عبر رموز API أو OAuth.
  • V3 Catalog API لإدارة المنتجات والمتغيرات.
  • V2 Orders API لمعالجة الطلبات والتسليم.
  • V3 Customers API لإدارة بيانات العملاء.
  • Webhooks تدفع التحديثات الفورية.
  • استخدم Apidog لاختبار وتوثيق التكاملات بموثوقية.

خطوات عملية:

  1. أنشئ حساب API في BigCommerce.
  2. نفّذ أول استدعاء API لسرد المنتجات.
  3. أضف Webhook لإنشاء الطلبات.
  4. احفظ استدعاءاتك في Apidog.
  5. ابنِ تكاملاتك.

اختبر واجهات برمجة تطبيقات BigCommerce باستخدام Apidog - مجانًا

الأسئلة الشائعة

ما الفرق بين V2 و V3؟

V3 أحدث وأكثر اتساقًا (منتجات، فئات، عملاء)، بينما V2 للطلبات فقط. ستحتاج غالبًا لكليهما.

كيف أجد store hash؟

من عنوان URL لإدارة متجرك:

https://store-abc123.mybigcommerce.com/manage

الجزء abc123 هو store hash.

هل يمكنني استخدام API على متجر تجريبي؟

نعم، بميزات كاملة، مثالي للتطوير.

ما حد المعدل؟

منتجات: 10,000/ساعة.

طلبات: 30,000/ساعة.

تحقق من X-Rate-Limit-Remaining في كل استجابة.

كيف أتعامل مع الترقيم؟

استخدم معلمات page وlimit. تحقق من meta.pagination:

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

هل يمكنني تحميل صور المنتجات؟

نعم:

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

كيف أتعامل مع العملات والمتاجر المتعددة؟

كل متجر له عملة أساسية. العملات المتعددة تدار عبر واجهة المتجر فقط. لإدارة متاجر متعددة، أنشئ حسابات API منفصلة واستخدم بيئات مختلفة في Apidog.

ماذا لو فشل Webhook؟

BigCommerce تعيد المحاولة بتراجع أسي. بعد 5 محاولات فاشلة خلال 24 ساعة، يتم تعطيل Webhook. راقب نقاط النهاية وتلقّى تنبيهات عند الفشل.

Top comments (0)