كيفية استخدام واجهات برمجة تطبيقات eBay؟

ملخص سريع (TL;DR)

تتيح لك واجهات برمجة تطبيقات eBay (APIs) إدارة المخزون والقوائم والطلبات والمدفوعات في أكبر سوق في العالم. تتم المصادقة باستخدام OAuth 2.0، واستدعاء نقاط النهاية api.ebay.com/sell، والتعامل مع حدود المعدل بعناية. للاختبار، استخدم Apidog للتحقق من صحة حمولات القوائم، واختبار معالجة الطلبات، والتأكد من أن تكاملك يتعامل مع حدود واجهة برمجة التطبيقات برشاقة.

مقدمة

يربط eBay المشترين والبائعين على مستوى العالم. تتيح واجهة برمجة التطبيقات للبائعين أتمتة إدارة المخزون، وإنشاء قوائم بكميات كبيرة، ومعالجة الطلبات، والتعامل مع الشحن، وإدارة المرتجعات. سواء كنت بائعًا صغيرًا أو مؤسسة، فإن واجهة برمجة التطبيقات قابلة للتوسع.

مجالات واجهة برمجة التطبيقات الرئيسية:

واجهة برمجة تطبيقات المخزون (Inventory API) - إدارة مخزون المنتج
واجهة برمجة تطبيقات القوائم (Listing API) - إنشاء وإدارة قوائم العناصر
واجهة برمجة تطبيقات الطلبات (Order API) - معالجة الطلبات والشحنات
واجهة برمجة تطبيقات الإنجاز (Fulfillment API) - التعامل مع الشحن والتتبع
واجهة برمجة تطبيقات التحليلات (Analytics API) - سحب تقارير المبيعات

💡

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

button

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

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

المصادقة باستخدام eBay OAuth 2.0
إنشاء وإدارة المخزون
نشر القوائم
معالجة الطلبات والشحنات
التعامل مع المرتجعات واسترداد الأموال
الاختبار باستخدام Apidog

المصادقة باستخدام OAuth 2.0

يستخدم eBay OAuth 2.0 للمصادقة على واجهة برمجة التطبيقات. ستحتاج إلى إنشاء تطبيق في برنامج مطوري eBay.

إنشاء تطبيق

انتقل إلى developers.ebay.com
سجل للحصول على حساب مطور
أنشئ تطبيقًا في Developer Console (وحدة تحكم المطورين)
احصل على معرّف التطبيق الخاص بك (معرّف العميل) ومعرّف الشهادة (سر العميل)

تدفق OAuth

الخطوة 1: تفويض المستخدم

https://auth.ebay.com/oauth2/authorize?
  client_id=YOUR_APP_ID&
  response_type=code&
  redirect_uri=YOUR_SIGNIN_REDIRECT_URI&
  scope=https://api.ebay.com/oauth/api_scope/sell.inventory

الخطوة 2: الحصول على رمز التفويض

يوافق المستخدم، وستحصل على رمز في عنوان URL لإعادة التوجيه الخاص بك.

الخطوة 3: تبادل الرموز المميزة

const response = await fetch('https://api.ebay.com/identity/v1/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + Buffer.from(APP_ID + ':' + CERT_ID).toString('base64')
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: AUTHORIZATION_CODE,
    redirect_uri: 'YOUR_SIGNIN_REDIRECT_URI'
  })
})

const { access_token, refresh_token, expires_in } = await response.json()

النطاقات المطلوبة

https://api.ebay.com/oauth/api_scope/sell.inventory - إدارة المخزون
https://api.ebay.com/oauth/api_scope/sell.listings - القوائم
https://api.ebay.com/oauth/api_scope/sell.orders - الطلبات
https://api.ebay.com/oauth/api_scope/sell.fulfillment - الإنجاز
https://api.ebay.com/oauth/api_scope/sell.account - إدارة الحساب

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

يمثل المخزون المنتجات التي تبيعها.

إنشاء موقع مخزون

curl -X POST "https://api.ebay.com/sell/inventory/v1/location_inventory_location" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "WAREHOUSE_1",
    "name": "Main Warehouse",
    "address": {
      "addressLine1": "123 Main St",
      "city": "San Jose",
      "stateOrProvince": "CA",
      "postalCode": "95101",
      "countryCode": "US"
    }
  }'

إنشاء عنصر مخزون

curl -X POST "https://api.ebay.com/sell/inventory/v1/inventory_item" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "title": "Vintage Leather Messenger Bag",
      "description": "Genuine leather messenger bag, perfect for work or school.",
      "aspects": {
        "Brand": ["Vintage"],
        "Material": ["Leather"],
        "Color": ["Brown"]
      },
      "imageUrls": [
        "https://example.com/images/bag1.jpg",
        "https://example.com/images/bag2.jpg"
      ]
    },
    "condition": "USED_GOOD",
    "conditionNotes": "Minor wear on corners",
    "availability": {
      "shipToLocationAvailability": {
        "quantity": 25
      }
    }
  }'

تحديث المخزون

curl -X PUT "https://api.ebay.com/sell/inventory/v1/inventory_item/SKU123" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "shipToLocationAvailability": {
        "quantity": 30
      }
    }
  }'

الحصول على عنصر مخزون

curl -X GET "https://api.ebay.com/sell/inventory/v1/inventory_item/SKU123" \
  -H "Authorization: Bearer ACCESS_TOKEN"

قوائم العناصر

إنشاء عرض

curl -X POST "https://api.ebay.com/sell/inventory/v1/offer" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SKU123",
    "marketplaceId": "EBAY_US",
    "format": "FIXED_PRICE",
    "product": {
      "title": "Vintage Leather Messenger Bag"
    },
    "pricingSummary": {
      "price": {
        "currency": "USD",
        "value": "89.99"
      }
    },
    "listing": {
      "listingDuration": "GTC",
      "listingType": "CLASSIC"
    },
    " fulfillment": {
      "shippingProfileId": "SHIPPING_PROFILE_ID",
      " fulfillmentPolicyId": "FULFILLMENT_POLICY_ID",
      "paymentPolicyId": "PAYMENT_POLICY_ID"
    }
  }'

الحقول الرئيسية:

sku - رقم المخزون الخاص بك (SKU)
marketplaceId - EBAY_US, EBAY_UK, EBAY_DE, إلخ.
format - FIXED_PRICE (سعر ثابت) أو AUCTION (مزاد)
listingDuration - المدة (GTC = جيد حتى الإلغاء)
price - السعر المطلوب

نشر العرض

curl -X POST "https://api.ebay.com/sell/inventory/v1/offer/OFFER_ID/publish" \
  -H "Authorization: Bearer ACCESS_TOKEN"

سحب قائمة

curl -X POST "https://api.ebay.com/sell/inventory/v1/offer/OFFER_ID/withdraw" \
  -H "Authorization: Bearer ACCESS_TOKEN"

إدارة الطلبات

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

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/order?orderIds=ORDER_ID_1,ORDER_ID_2" \
  -H "Authorization: Bearer ACCESS_TOKEN"

تصفية حسب التاريخ:

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/order?filter=creation_date_range:from:2026-01-01T00:00:00Z,to:2026-03-24T00:00:00Z" \
  -H "Authorization: Bearer ACCESS_TOKEN"

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

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/order/ORDER_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN"

استجابة الطلب:

{
  "orderId": "12-34567-89012",
  "orderPaymentStatus": "PAID",
  "pricingSummary": {
    "total": {
      "currency": "USD",
      "value": "94.99"
    }
  },
  "fulfillmentStartInstructions": [
    {
      "shippingStep": {
        "shipTo": {
          "fullName": "John Doe",
          "contactAddress": {
            "addressLine1": "123 Main St",
            "city": "Anytown",
            "stateOrProvince": "CA",
            "postalCode": "12345",
            "countryCode": "US"
          }
        }
      }
    }
  ],
  "lineItems": [
    {
      "lineItemId": "LINE_ITEM_ID",
      "sku": "SKU123",
      "quantity": 1,
      "title": "Vintage Leather Messenger Bag",
      "lineItemCost": {
        "currency": "USD",
        "value": "89.99"
      }
    }
  ]
}

الشحن والتسليم

إنشاء ملصق شحن

curl -X POST "https://api.ebay.com/sell/fulfillment/v1/order/ORDER_ID/shipping_fulfillment" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [
      {
        "lineItemId": "LINE_ITEM_ID",
        "quantity": 1
      }
    ],
    "shippingStep": {
      "shipFrom": {
        "fullName": "Your Name",
        "companyName": "Your Company",
        "contactAddress": {
          "addressLine1": "456 Warehouse Rd",
          "city": "San Jose",
          "stateOrProvince": "CA",
          "postalCode": "95101",
          "countryCode": "US"
        }
      }
    },
    "shippingCarrierCode": "USPS",
    "shippingMethodCode": "PRIORITY_MAIL",
    "trackingNumber": "9400111899223056789012"
  }'

شركات الشحن:

USPS
UPS
FedEx
DHL

إدارة المرتجعات

الحصول على تفاصيل المرتجع

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/return/RETURN_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN"

معالجة مرتجع

curl -X POST "https://api.ebay.com/sell/fulfillment/v1/return/RETURN_ID/decide" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "ACCEPT",
    "shipment": {
      "carrierId": "CARRIER_ID",
      "trackingNumber": "TRACKING_NUMBER"
    }
  }'

حدود المعدل والتعامل معها

يفرض eBay قيودًا على استدعاءات واجهة برمجة التطبيقات لمنع إساءة الاستخدام. تحقق من الرؤوس (headers):

X-RateLimit-Limit - الحد الأقصى للطلبات المسموح بها
X-RateLimit-Remaining - الطلبات المتبقية في النافذة الزمنية
X-RateLimit-Reset - الطابع الزمني بنظام Unix عند إعادة تعيين الحد

async function makeEbayRequest(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options)
    
    const remaining = response.headers.get('X-RateLimit-Remaining')
    if (remaining && parseInt(remaining) < 10) {
      console.warn('Rate limit low:', remaining)
    }
    
    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset')
      const waitTime = (parseInt(resetTime) - Date.now() / 1000) * 1000
      await sleep(waitTime)
      continue
    }
    
    return response
  }
  throw new Error('Rate limited')
}

الاختبار باستخدام Apidog

تعتبر واجهات برمجة تطبيقات eBay حاسمة للإنتاج. اختبرها بدقة قبل إجراء تغييرات مباشرة.

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

EBAY_APP_ID: your_app_id
EBAY_CERT_ID: your_cert_id
EBAY_ACCESS_TOKEN: stored_token
EBAY_REFRESH_TOKEN: stored_refresh
EBAY_MARKETPLACE_ID: EBAY_US
BASE_URL: https://api.ebay.com

2. التحقق من صحة حمولات القوائم

pm.test('Listing has required fields', () => {
  const requestBody = JSON.parse(pm.request.body.raw)
  pm.expect(requestBody).to.have.property('sku')
  pm.expect(requestBody).to.have.property('marketplaceId')
  pm.expect(requestBody.pricingSummary).to.have.property('price')
})

pm.test('Price is valid', () => {
  const requestBody = JSON.parse(pm.request.body.raw)
  const price = parseFloat(requestBody.pricingSummary.price.value)
  pm.expect(price).to.be.above(0)
})

3. اختبار معالجة الطلبات

pm.test('Order response is valid', () => {
  const response = pm.response.json()
  pm.expect(response).to.have.property('orderId')
  pm.expect(response.orderPaymentStatus).to.eql('PAID')
  pm.expect(response.lineItems).to.be.an('array')
})

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

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

401 غير مصرح به (Unauthorized)

السبب: انتهت صلاحية الرمز المميز أو غير صالح.

الإصلاح: استخدم الرمز المميز للتحديث للحصول على رمز مميز جديد للوصول:

const response = await fetch('https://api.ebay.com/identity/v1/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + Buffer.from(APP_ID + ':' + CERT_ID).toString('base64')
  },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: storedRefreshToken
  })
})

10002: خطأ في API - رمز الوصول غير صالح (Invalid access token)

السبب: انتهت صلاحية رمز الوصول.

الإصلاح: قم بتحديث الرمز المميز على الفور.

21916684: العنصر غير موجود (Item does not exist)

السبب: محاولة تحديث SKU لم يتم إنشاؤه.

الإصلاح: قم بإنشاء عنصر المخزون أولاً، ثم أنشئ العرض.

10003: SKU غير صالح (Invalid sku)

السبب: تنسيق SKU غير صالح.

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

حد المعدل (429)

السبب: عدد كبير جدًا من الطلبات.

الإصلاح: قم بتطبيق التراجع. تختلف حدود eBay حسب واجهة برمجة التطبيقات ونقطة النهاية.

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

الميزة	eBay	Amazon SP-API	Etsy
واجهة برمجة تطبيقات المخزون (Inventory API)	✓	✓	محدود
واجهة برمجة تطبيقات القوائم (Listing API)	✓	✓	✓
واجهة برمجة تطبيقات الطلبات (Order API)	✓	✓	✓
واجهة برمجة تطبيقات الإنجاز (Fulfillment API)	✓	✓	محدود
الطبقة المجانية (Free tier)	برنامج المطورين	محدود	محدود
تعقيد واجهة برمجة التطبيقات (API complexity)	متوسط	عالي	منخفض

واجهة برمجة تطبيقات eBay أكثر سهولة من واجهة برمجة تطبيقات Amazon ولكنها أقل غنى بالميزات. Etsy هي الأبسط ولكنها محدودة للبائعين الكبار.

حالات الاستخدام في العالم الحقيقي

البيع عبر قنوات متعددة. يعرض البائع منتجاته على eBay و Amazon وموقعه الخاص. تتم مزامنة المخزون عبر جميع المنصات. عند البيع على قناة واحدة، تقل الكمية في كل مكان.

إعادة التسعير التلقائية. يراقب البائع المنافسين ويعدل الأسعار عبر واجهة برمجة التطبيقات. عندما يخفض أحد المنافسين الأسعار، يتم تعديل أسعار البائع تلقائيًا للبقاء تنافسيًا.

إنشاء قوائم بالجملة. يقوم بائع لديه 10,000 عنصر بإنشاء قوائم بكميات كبيرة. تقبل واجهة برمجة التطبيقات تحميل ملفات CSV، مما يؤدي إلى إنشاء آلاف القوائم تلقائيًا.

الخلاصة

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

المصادقة باستخدام OAuth 2.0 باستخدام بيانات اعتماد التطبيق
إدارة المخزون باستخدام SKUs
إنشاء ونشر القوائم
معالجة الطلبات والشحنات
التعامل مع المرتجعات
الاختبار باستخدام Apidog قبل الإطلاق المباشر

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

التقدم بطلب لبرنامج مطوري eBay
إنشاء تطبيق والحصول على بيانات الاعتماد
تنفيذ تدفق OAuth
إنشاء أول عنصر مخزون لك
نشر قائمة اختبار

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

button

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

هل أحتاج إلى حساب تجاري لاستخدام واجهات برمجة التطبيقات؟نعم. واجهات برمجة تطبيقات eBay مخصصة للبائعين المعتمدين. سجل للحصول على حساب بائع وأكمل عملية التحقق.

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

كم من الوقت تبقى القوائم نشطة؟تبقى القوائم التي تحمل علامة GTC (جيد حتى الإلغاء) نشطة حتى تقوم بسحبها أو نفاد العنصر.

هل يمكنني البيع دوليًا عبر واجهة برمجة التطبيقات؟نعم. قم بتعيين marketplaceId إلى قيم مختلفة (EBAY_US، EBAY_UK، EBAY_DE، إلخ). ستحتاج إلى الامتثال لمتطلبات كل سوق.

ما هو حد معدل واجهة برمجة التطبيقات؟تختلف الحدود حسب نقطة النهاية ومستوى حسابك. تحقق من رؤوس الاستجابة لمعرفة حدودك الحالية.

كيف أحصل على ملصقات الشحن؟يوفر eBay ملصقات شحن مخفضة من خلال واجهة برمجة تطبيقات الإنجاز (Fulfillment API). تقوم بإنشاء الشحنة ويقوم eBay بإنشاء ملصق.