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

ملخص

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

مقدمة

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

توفر المنصة ثلاثة أنواع من واجهات برمجة التطبيقات: Storefront API (للتجارة بدون واجهة أمامية)، و Management API (لعمليات الواجهة الخلفية)، و Payments API (للمعاملات). يعمل معظم المطورين مع Management API. وهي تتعامل مع المنتجات والطلبات والعملاء وكل ما يحدث خلف الكواليس.

منحنى التعلم ليس صعبًا، ولكن قد تبدو الوثائق مربكة. ستجد نفسك تتنقل بين وثائق المصادقة، ومراجع API، وأدلة Webhooks لإنجاز مهمة بسيطة.

يركز هذا الدليل على ما ستستخدمه بالفعل: المنتجات والطلبات والعملاء وWebhooks. ستتعلم المصادقة والأنماط الشائعة وكيفية اختبار عمليات التكامل الخاصة بك قبل أن تصل إلى متجر مباشر.

💡

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

button

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

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

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

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

تقدم BigCommerce طريقتين للمصادقة حسب ما تقوم ببنائه.

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

إذا كنت تبني نصًا برمجيًا أو خدمة تعمل مع متجر واحد، فاستخدم رموز API.

إنشاء حساب API:

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

ستحصل على:

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

قم بإجراء مكالمتك الأولى:

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"

الـ store-hash هو الجزء الذي يأتي بعد /stores/ في مسار API الخاص بك. وهو مرئي أيضًا في عنوان URL لإدارة متجرك.

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

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

تدفق OAuth:

ينقر المستخدم على "تثبيت" لتطبيقك في المتجر
BigCommerce يعيد التوجيه إلى عنوان URL لمعاودة الاتصال الخاص بك مع رمز المصادقة
يقوم الخادم الخاص بك بتبادل الرمز برمز وصول
قم بتخزين الرمز لاستدعاءات 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

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

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

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

المنتجات هي قلب أي متجر BigCommerce. يتعامل V3 Catalog API مع المنتجات والمتغيرات والفئات والعلامات التجارية.

سرد المنتجات

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

الاستجابة:

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

إنشاء منتج

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]
}

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

المنتجات ذات الخيارات (الحجم، اللون) لها متغيرات. كل متغير يمكن أن يكون له SKU وسعر ومخزون خاص به.

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"
    }
  ]
}

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

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

{
  "inventory_level": 75
}

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

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

{
  "inventory_level": 25
}

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

الطلبات هي حيث تتم الأعمال. يتعامل Orders V2 API مع إنشاء الطلبات وتحديثاتها وتسليمها.

سرد الطلبات

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

الاستجابة:

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

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

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

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

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

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

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

{
  "status_id": 12
}

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

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
    }
  ]
}

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

يتعامل Customers V3 API مع بيانات العملاء وعناوينهم ومجموعات العملاء.

سرد العملاء

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

الاستجابة:

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

إنشاء عميل

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
}

تحديث العميل

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
}

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

تقوم Webhooks بإخطار تطبيقك عند حدوث أحداث في المتجر. بدلاً من الاستعلام الدوري، تدفع BigCommerce البيانات إلى نقاط النهاية الخاصة بك.

إنشاء 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
}

النطاقات المتاحة:

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

تقوم BigCommerce بتوقيع Webhooks حتى تتمكن من التحقق من شرعيتها:

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')
})

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

تتطلب واجهات برمجة تطبيقات BigCommerce رؤوسًا متسقة ومصادقة صحيحة. يصبح الاختبار اليدوي باستخدام curl مملًا. يعمل Apidog على تبسيط هذه العملية.

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

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

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

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

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)
})

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

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

401 غير مصرح به

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

الإصلاح:

تحقق من تعيين رأس X-Auth-Token الخاص بك
تحقق من أن الرمز لم يتم إبطاله
تأكد من أن حساب API لديه النطاقات الصحيحة

403 ممنوع

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

الإصلاح:

تحقق من أذونات حساب API الخاص بك
أضف النطاق المفقود (المنتجات، الطلبات، إلخ.)
قم بإنشاء رمز جديد بأذونات موسعة

404 غير موجود

السبب: نقطة نهاية خاطئة أو المورد غير موجود.

الإصلاح:

تحقق من صحة تجزئة المتجر (store hash)
تحقق من إصدار API في عنوان URL (V2 مقابل V3)
تأكد من وجود معرف المورد

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

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

الإصلاح: تسمح BigCommerce بحدود مختلفة لكل نقطة نهاية. المنتجات: 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
    }
  }
}

422 كيان غير قابل للمعالجة

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

الإصلاح: تحقق من الاستجابة للحصول على التفاصيل. تُرجع BigCommerce أخطاء تحقق محددة:

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

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

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

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

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

مزامنة المخزون متعددة القنوات. تبيع علامة تجارية على BigCommerce و Amazon والمتاجر الفعلية. يستخدمون Products API لمزامنة مستويات المخزون عبر القنوات، مما يمنع البيع الزائد. يقوم Apidog باختبار نقاط نهاية المزامنة قبل كل نشر.

أتمتة الطلبات. تستخدم شركة صناديق الاشتراك Webhooks لتشغيل التسليم عند إنشاء الطلبات. تقوم Orders API بتحديث أرقام التتبع. يستقبل مستودعهم قوائم الانتقاء تلقائيًا عبر معالجات Webhook.

تجزئة العملاء. يستخدم موقع تجارة إلكترونية Customers API لتجزئة المشترين بناءً على سجل الشراء. يتم إضافة عملاء VIP إلى مجموعة خاصة بأسعار حصرية. يعمل التكامل أسبوعيًا عبر مهمة مجدولة.

الخاتمة

إليك ما تعلمته:

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

خطواتك التالية:

أنشئ حساب API في متجر BigCommerce الخاص بك
قم بإجراء أول استدعاء API لسرد المنتجات
قم بإعداد Webhook لإنشاء الطلبات
احفظ استدعاءات API الخاصة بك في Apidog
ابنِ تكاملك

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

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

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

كيف أحصل على تجزئة متجري (store hash)؟توجد في عنوان URL لإدارة BigCommerce الخاص بك: https://store-abc123.mybigcommerce.com/manage. الجزء abc123 هو تجزئة متجرك (store hash). وهو مرئي أيضًا في إعدادات حساب API.

هل يمكنني استخدام API على متجر تجريبي؟نعم. تتمتع متاجر BigCommerce التجريبية بوصول كامل إلى API. وهذا مثالي للتطوير والاختبار قبل الانطلاق.

ما هو حد المعدل لاستدعاءات API؟يعتمد على نقطة النهاية. المنتجات: 10,000 طلب/ساعة. الطلبات: 30,000 طلب/ساعة. تحقق من X-Rate-Limit-Remaining في رؤوس الاستجابة لمعرفة الحد الحالي الخاص بك.

كيف أتعامل مع الترقيم؟استخدم معلمات الاستعلام page و limit. الحد الافتراضي هو 50. تحقق من 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++
}

هل يمكنني تحميل صور المنتجات عبر API؟نعم. استخدم نقطة نهاية صور المنتجات:

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
}

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

ماذا يحدث إذا تعطلت نقطة نهاية Webhook الخاصة بي؟تعيد BigCommerce محاولة Webhooks الفاشلة باستخدام التراجع الأسي. بعد 5 محاولات فاشلة خلال 24 ساعة، يتم تعطيل Webhook. راقب نقاط النهاية الخاصة بك وتلقى تنبيهات عند الفشل.