ملاحظة مهمة: سيتم إيقاف Content API for Shopping نهائيًا في 18 أغسطس 2026.

نقدّم لك Merchant API التي تشكّل البديل الرسمي لـ Content API for Shopping.

الاطّلاع على آخر الأخبار حول الميزات الجديدة وإصلاحات الأخطاء وتحديثات Merchant API

ابدأ استخدام Merchant API واحصل على إمكانية الوصول إلى البيانات والإحصاءات والميزات الفريدة على نطاق واسع.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

يتيح مصدر products قدراً كبيراً من المرونة والتحكّم في أكثر من 60 سمة من سمات المنتجات.هناك عدد من الحقول الإلزامية التي يجب تضمينها من أجل الموافقة على عرضها على Google Shopping. هناك عدد من الحقول الاختيارية التي يمكن أن تصبح إلزامية استنادًا إلى شروط مختلفة، مثل الموقع الجغرافي ونوع المنتج وخيارات المنتج وحِزم المنتجات. لمزيد من التفاصيل حول أكثر من 60 مَعلمة اختيارية يمكن ضبطها للمنتجات، يُرجى الرجوع إلى مواصفات بيانات المنتج.

يتيح لك المرجع products insert وget وupdate وdelete منتجًا واحدًا في كل مرة، كما يتيح لك list جميع المنتجات في قاعدة بيانات Merchant Center.

يمكن استخدام المرجع productstatuses للتحقّق من حالة الموافقة أو الرفض لمنتج معيّن في وجهة معيّنة. راجِع دليل حالة المنتج للحصول على مزيد من التفاصيل حول المنتجات التي قد تواجه مشاكل في جودة البيانات وأنواع هذه المشاكل.

في أمثلة واجهة برمجة التطبيقات، نستخدم ثلاثة منتجات: قميصان من Google وقبعة من Google. ونستخدم مجموعة بسيطة من بيانات المنتجات الموضّحة في الجدول أدناه لإجراء طلبات موارد products لإدراج المنتجات الفردية ومجموعات المنتجات والحصول عليها وتعديلها وإدراجها وحذفها.

ننصحك بضبط معلومات الشحن والضريبة على مستوى الحساب بدلاً من ضبطها على مستوى المنتج.

في الحسابات الفرعية المتعددة البائعين التابعة للأسواق، يجب أن تتضمّن جميع المنتجات الحقل external_seller_id. لمزيد من التفاصيل، يُرجى الاطّلاع على معرّفات المنتجات.


id	online:en:US:1111111111	online:en:US:2222222222	online:en:US:3333333333
offerId	1111111111	2222222222	3333333333
title	تيشيرت Black Google	Google Tee Green	قبّعة من القماش القطني من Google
الوصف	تيشيرت Black Google	قميص Google مصنوع من القطن بنسبة% 100	الحد الأقصى الكلاسيكي لـ Google
معرّف مجموعة السلع	google_tee	google_tee
رابط	http://my.site.com/blacktee	http://my.site.com/greentee	http://my.site.com/blackhat
الشرط	جديد	New	جديد
price	21.99 USD	21.99 USD	‎10.99 SAR
مدى التوفّر	متوفر	متوفر	متوفر
imageLink	https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX1100.jpg	https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX0906.jpg	https://shop.example.com/store/20160512512/assets/items/images/GGOEGHPB071610.jpg
رقم GTIN	9504000059422	9504000059446	9504000059452
رقم القطعة بحسب الشركة المصنّعة	00638NIC	00638ANG	00638ABC
العلامة التجارية	Google	Google	Google
فئة المنتجات من Google	ملابس وإكسسوارات > ملابس	ملابس وإكسسوارات > ملابس	ملابس وإكسسوارات > إكسسوارات الملابس > قبعات
اللون	أسود	أخضر	أسود
الحجم	L	M	M
age_group	adult	adult	adult
الجنس	ذكر	ذكر	unisex
included_destination	‫Shopping Actions و"إعلانات Shopping"	‫Shopping Actions و"إعلانات Shopping"	Shopping Actions

products.insert

لإدراج منتج واحد، استخدِم عنوان URL الخاص بالطلب التالي، مع تحديد معرّف التاجر ونص JSON نموذجي. يؤدي إدراج منتج إلى إنشاء المنتج الجديد. إذا كانت هناك قيم للسمات channel وcontentLanguage وofferId وfeedLabel لمنتج معيّن، تعدّل هذه الطريقة الإدخال وتستبدل جميع البيانات من طلبات البيانات السابقة من واجهة برمجة التطبيقات للمنتج المعيّن.

سيتم تلقائيًا حذف المنتجات التي تم استبعادها من كل الوجهات لأكثر من 7 أيام.

يُدرج المثال المعروض منتجًا جديدًا هو "قميص Google أسود" ضمن المنتجات المتاحة.

POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

نموذج نص الطلب الخاص بمكالمة لـ "products.insert":

{
 "kind": "content#product",
 "offerId": "1111111111",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

يمكن أن يتضمّن المنتج أيضًا سمات مخصّصة تم ضبطها ضمن نص JSON. على سبيل المثال، يمكننا ضبط purchase_quantity_limit لمنتج واحد من أجل الحدّ من عدد السلع التي يمكن للعميل طلبها:

"customAttributes": [
 {
   "name": "purchase_quantity_limit",
   "value": "4"
 }
]

يُرجى العِلم أنّ سمة purchase_quantity_limit المخصّصة تضع حدًا أقصى لعمليات الشراء لكل طلب من العميل حسب تعريف المنتج، كما أنّها متوافقة مع الخلاصات. تتوفّر السمة حاليًا في الإصدار التجريبي إلى أن تصبح متوافقة بالكامل مع واجهة برمجة التطبيقات. يمكن للتاجر إضافة أي سمة مخصّصة إضافية، ولكن لن تؤدي إلى أي معالجة معيّنة من خلال واجهات برمجة التطبيقات.

تعرض المكالمة الناجحة الرمز HTTP 200 ونص الرد الذي يتضمّن مورد المنتج الذي تم إدراجه مع ملء الحقول id وofferId وcontentLanguage وfeedLabel وchannel فقط:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online"
}

products.get

للحصول على معلومات عن منتج معيّن في قاعدة بيانات Merchant Center، استخدِم products.get. قد يستغرق توفّر منتج تم إدراجه حديثًا من خلال هذه المكالمة بضع دقائق.

استخدِم عنوان URL لطلب HTTP والمعلَمات التالية، ومعرّف التاجر، ومعرّف المنتج (تنسيق معرّف REST) للمنتج الذي تريد الحصول عليه:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

يعرض الطلب الناجح HTTP 200 و "مورد المنتج" في نص الاستجابة. في ما يلي نموذج لبيانات منتج تم استردادها من منتج يحمل المعرّف online:en:US:1111111111:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "source": "api",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

products.update

لتعديل منتج واحد، استخدِم عنوان URL لطلب التالي مع طريقة PATCH، مع تحديد معرّف التاجر ومعرّف المنتج ونص JSON يتضمّن البيانات التي تريد تعديلها للمنتج. على عكس products.insert، الذي يتطلّب توفير جميع الحقول السارية، لا يتطلّب products.update سوى تحديد الحقول التي تريد تغييرها.

لإضافة سمة أو تعديلها، حدِّد الحقل الذي يتضمّن القيمة الجديدة في نص JSON. سيؤدي المثال المعروض إلى تعديل title وdescription لمنتج حالي باسم "Black Google Tee" باستخدام بيانات المنتج المقدَّمة في نص الطلب، مع ترك جميع الحقول الأخرى بدون تغيير.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

نموذج نص الطلب الخاص بمكالمة لـ "products.update":

{
 "title": "Google Tee Black Limited Edition",
 "description": "The Limited Edition Tee is available in unisex sizing and features a retail fit."
}

يمكن تعديل الحقول ذات المستوى الأعلى فقط من خلال طلب products.update. إذا أردت تعديل الحقول المتداخلة، عليك تقديم العنصر الكامل ذي المستوى الأعلى.

سيعدّل المثال المعروض عنصر salePrice المستوى الأعلى، بما في ذلك الحقول المتداخلة الخاصة بمنتج حالي، باستخدام بيانات المنتج المقدَّمة في نص الطلب، مع ترك جميع الحقول الأخرى بدون تعديل.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

{
 "salePrice": {
  "value": "17.99",
  "currency": "USD"
 }
}

لاختيار حقول معيّنة لتعديلها بدون إجراء تغييرات على الحقول الأخرى المضمّنة في نص الطلب، يمكنك تحديد updateMask. يجب أن تكون مَعلمة سلسلة طلب البحث هذه قائمة بالحقول التي تريد تعديلها، على أن تكون القيم مفصولة بفواصل. يكون updateMask مفيدًا عندما تريد التأكّد من أنّه سيتم تعديل الحقول المسماة فقط. عدم تحديد updateMask هو بمثابة وضع علامة على جميع الحقول في الطلب المطلوب تعديله، كما هو موضّح في المثال أعلاه.

سيعدّل المثال المعروض فقط الحقلَين description وavailability للمنتج الحالي "Black Google Tee" باستخدام بيانات المنتج المعنيّة المقدَّمة في نص الطلب، مع ترك جميع الحقول الأخرى، بما في ذلك title، بدون تعديل.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=description,availability

نموذج نص الطلب الخاص بمكالمة لـ "products.update":

{
 "title": "Google Tee Black",
 "description": "This Limited Edition is out of print.",
 "availability": "out of stock"
}

إذا تم توفير حقل في قائمة updateMask ولكن ليس في نص الطلب، سيتم حذف هذا الحقل من مرجع Product، إذا كان متوفّرًا.

سيستخدم المثال المعروض updateMask لإزالة قيمة الحقل salePrice.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=salePrice

يجب ألا يتضمّن نموذج نص الطلب الحقل salePrice لحذفه. يمكنك أيضًا عدم تقديم نص أساسي أو تقديم نص أساسي فارغ. ستبقى الحقول الأخرى بدون تغيير ما دامت لا تظهر في updateMask.

لاستخدام updateMask ضمن طلب products.custombatch، يجب تحديد updateMask في نص الطلب.

سيعدّل المثال المعروض price وavailability لمنتج حالي بعنوان "Black Google Tee" باستخدام products.custombatch مع بيانات المنتج المقدَّمة في إدخال الدفعة، مع ترك جميع الحقول الأخرى، بما في ذلك title وdescription، بدون تعديل.

POST https://shoppingcontent.googleapis.com/content/v2.1/products/batch

{
  "entries": [{
    "batchId": 1,
    "merchantId": "MERCHANT_ID",
    "productId": "online:en:US:1111111111",
    "method": "update",
    "product": {
      "title": "Google Tee Black",
      "description": "The Black Google Tee is available in unisex sizing.",
      "availability": "in stock",
      "price": {
        "value": "19.99",
        "currency": "USD"
      }
    },
    "updateMask": "availability,price"
  }]
}

products.delete

لحذف منتج واحد، استخدِم products.delete مع نموذج عنوان URL لطلب HTTP، ومعرّف التاجر، ومعرّف المنتج (بتنسيق معرّف REST، مثل online:en:US:1111111111) للمنتج الذي تريد حذفه:

DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

تعرض الاستجابة الناجحة الرمز HTTP Status 204 بدون نص استجابة.

products.list

تعرض products.list كل المنتجات التي يملكها التاجر في قاعدة بيانات Merchant Center. استخدِم عنوان URL التالي للطلب:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

يؤدي الاتصال الناجح إلى عرض HTTP 200 وبيانات JSON للمنتجات في المفتاح "resources".

يتم عرض المنتجات الثلاثة التالية كمثال:

{
 "kind": "content#productsListResponse",
 "resources": [
  {
   "kind": "content#product",
   "id": "online:en:US:1111111111",
   "offerId": "1111111111",
   "source": "api",
   "title": "Google Tee Black",
   "description": "The Black Google Tee is available in unisex sizing.",
   "link": "http://my.site.com/blacktee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531656",
   "itemGroupId": "google_tee",
   "mpn": "608802531656",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Large"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:2222222222",
   "offerId": "2222222222",
   "source": "api",
   "title": "Google Tee Green",
   "description": "100% cotton jersey fabric sets this Google t-shirt above the crowd.
    Features the google logo across the chest. Unisex sizing.",
   "link": "http://my.site.com/greentee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX0906.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "green",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531649",
   "itemGroupId": "google_tee",
   "mpn": "608802531649",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:3333333333",
   "offerId": "3333333333",
   "source": "api",
   "title": "Google Twill Cap",
   "description": "Classic urban styling distinguishes this Google cap.
    Retains its shape, even when not being worn.",
   "link": "http://my.site.com/blackhat/",
   "imageLink": "https://shop.example.com/.../images/GGOEGHPB071610.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-07T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "173",
   "gtin": "689355417246",
   "mpn": "689355417246",
   "price": {
    "value": "10.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  }
 ]
}

معرّفات المنتجات

وضع الدفعة