Forem

Cover image for كيفية استخدام واجهات برمجة تطبيقات eBay؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

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

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

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

جرّب Apidog اليوم

مقدمة

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

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

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

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

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

مع نهاية الدليل ستتمكن من:

  • تنفيذ المصادقة باستخدام OAuth 2.0 مع eBay.
  • إنشاء وإدارة عناصر المخزون.
  • نشر القوائم بشكل تلقائي.
  • معالجة الطلبات والشحنات.
  • إدارة المرتجعات والمبالغ المستردة.
  • اختبار التكاملات عبر Apidog.

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

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

ebay oauth

خطوات إنشاء تطبيق:

  1. انتقل إلى developers.ebay.com
  2. سجل كـ"مطور".
  3. أنشئ تطبيق جديد من خلال Developer Console.
  4. احتفظ بـ App ID (client_id) وCert ID (client_secret).

تدفق 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
Enter fullscreen mode Exit fullscreen mode

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()
Enter fullscreen mode Exit fullscreen mode

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

  • 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 لإدارة الحساب

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

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

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

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

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

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
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

تحديث كمية عنصر 

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
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

جلب عنصر مخزون 

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

إدارة القوائم (Listing)

إنشاء عرض/قائمة 

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

أهم الحقول:

  • sku: رقم تعريف المخزون
  • marketplaceId: رمز السوق (مثلاً EBAY_US)
  • 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"
Enter fullscreen mode Exit fullscreen mode

سحب/إزالة قائمة 

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

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

جلب الطلبات 

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

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

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"
Enter fullscreen mode Exit fullscreen mode

تفاصيل الطلب 

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

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

{
  "orderId": "12-34567-89012",
  "orderPaymentStatus": "PAID",
  "pricingSummary": {
    "total": {
      "currency": "USD",
      "value": "94.99"
    }
  },
  ...
}
Enter fullscreen mode Exit fullscreen mode

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

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

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"
  }'
Enter fullscreen mode Exit fullscreen mode

أشهر شركات الشحن المدعومة: USPS, UPS, FedEx, DHL

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

جلب تفاصيل المرتجع 

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

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

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

حدود المعدل (Rate Limiting) والتعامل معها

تفرض eBay حدودًا على عدد الاستدعاءات. يجب مراقبة رؤوس الاستجابة التالية:

  • X-RateLimit-Limit: الحد الأقصى
  • X-RateLimit-Remaining: المتبقي
  • X-RateLimit-Reset: وقت إعادة التعيين (Unix timestamp)

مثال على التعامل البرمجي مع حدود المعدل:

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')
}
Enter fullscreen mode Exit fullscreen mode

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

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

apidog test

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
Enter fullscreen mode Exit fullscreen mode

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)
})
Enter fullscreen mode Exit fullscreen mode

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')
})
Enter fullscreen mode Exit fullscreen mode

اختبر واجهات برمجة تطبيقات 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
  })
})
Enter fullscreen mode Exit fullscreen mode

10002: رمز الوصول غير صالح

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

الحل: حدّث الرمز المميز فورًا.

21916684: العنصر غير موجود

السبب: محاولة تحديث SKU غير موجود.

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

10003: SKU غير صالح

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

الحل: استخدم رموز SKU أبجدية رقمية فقط مع شرطات وشرطات سفلية.

حد المعدل (429)

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

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

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

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

واجهة برمجة تطبيقات eBay متوسطة التعقيد وأسهل من Amazon SP-API، بينما Etsy أبسط لكنها محدودة للبائعين الكبار.

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

  • البيع عبر قنوات متعددة: مزامنة المخزون تلقائيًا بين eBay، Amazon، والموقع الخاص بك.
  • إعادة التسعير التلقائي: مراقبة المنافسين وتعديل الأسعار تلقائيًا للبقاء تنافسيًا.
  • إنشاء قوائم بالجملة: تحميل ملفات CSV لإنشاء آلاف القوائم دفعة واحدة عبر API.

الخلاصة

ما تعلمته:

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

خطواتك العملية القادمة:

  1. قدم لبرنامج مطوري eBay.
  2. أنشئ تطبيقك واحصل على بيانات الاعتماد.
  3. نفذ تدفق OAuth.
  4. أنشئ أول عنصر مخزون لك.
  5. اختبر ونشر قائمة تجريبية.

اختبر جميع عملياتك عبر Apidog مجانًا قبل الإطلاق المباشر.

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

هل أحتاج إلى حساب تجاري لاستخدام واجهات برمجة التطبيقات؟

نعم، يجب أن تكون بائعًا معتمدًا على eBay. سجل حساب بائع وأكمل التحقق.

ما الفرق بين المخزون والعروض؟

المخزون يخزن بيانات المنتج (العنوان، الوصف، الصور)، بينما العرض يربط المخزون بالسوق مع معلومات التسعير والتسليم.

كم من الوقت تبقى القوائم نشطة؟

قوائم GTC (Good Till Cancelled) تبقى نشطة حتى تقوم بسحبها أو ينفد العنصر.

هل يمكنني البيع دوليًا عبر API؟

نعم. استخدم قيم مختلفة لـmarketplaceId (مثل EBAY_US، EBAY_UK، EBAY_DE) وامتثل لمتطلبات كل سوق.

ما هو حد معدل واجهة برمجة التطبيقات؟

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

كيف أحصل على ملصقات الشحن؟

يوفر eBay ملصقات شحن مخفضة عبر Fulfillment API. أنشئ الشحنة لتحصل على الملصق تلقائيًا.

Top comments (0)