نظرة عامة على Merchant Products API

توضّح هذه الصفحة كيفية تحميل منتجاتك وإدارتها آليًا. باستخدام Merchant Products API، يمكنك إدراج منتج أو تعديله في مصدر بيانات، واسترداد منتج من حسابك، وحذف منتج من مصدر بيانات.

تحتوي Merchant Products API على موردَين.

• productInputs يمثّل أجزاء الإدخال في منتجاتك.
• يمثّل products المنتجات التي تمّت معالجتها والتي تم إنشاؤها من أجزاء الإدخال.

يمكن أن تكون productInputs أساسية وتكميلية، وذلك حسب ما إذا كانت تم تحميلها إلى مصدر بيانات أساسي أو مصدر بيانات تكميلي. سيتم إنشاء كل product من productInput أساسي واحد وأي عدد من productInputs التكميلية.

يمكنك استخدام Merchant Products API لإنشاء كتالوجات متاجر على الإنترنت أو في المتاجر المحلية، وهي منتجات يمكن أن تظهر في وجهات تسوّق متعددة. يمكنك استخدام مرجع productInputs بعد إنشاء حسابك على Merchant Center وإعداد مصدر البيانات الأول وأصبح حسابك جاهزًا لتحميل مجموعة أولية من المنتجات من خلال واجهة برمجة التطبيقات.

على الرغم من أنّ التجّار يمكنهم تحميل المنتجات باستخدام ملف يُعرف باسم PrimaryProductDataSource، تتوفر عدة مزايا لإنشاء المنتجات وحذفها باستخدام Merchant API. وتشمل هذه المزايا وقت استجابة أسرع والقدرة على تعديل المنتجات في الوقت الفعلي، بدون الحاجة إلى إدارة ملفات كبيرة. قد يستغرق ظهور التغييرات التي تم إجراؤها على المنتجات من خلال طلبات البيانات من واجهة برمجة التطبيقات في قاعدة بيانات Shopping ما يصل إلى عدة ساعات.

المتطلبات الأساسية

إذا لم يكن لديك مصدر بيانات، أنشئ مصدر بيانات باستخدام Merchant DataSources API أو Merchant Center.

إذا كان لديك مصدر بيانات أنشأته باستخدام واجهة مستخدم Merchant Center أو باستخدام واجهة برمجة التطبيقات، يمكنك استخدام Merchant Products API لإضافة منتجاتك. إذا كنت تستخدم Content API for Shopping لإضافة منتجات، يُرجى الرجوع إلى دليل نقل البيانات للتعرّف على كيفية البدء باستخدام Merchant Products API.

أنت المسؤول عن الالتزام بسياسات إعلانات Shopping و البيانات المجانية. تحتفظ "إعلانات Shopping" بالحق في فرض هذه السياسات والردّ عليها بشكل مناسب إذا رصدنا محتوًى أو سلوكًا ينتهكان هذه السياسات.

الموارد

يتيح لك المرجع products استرداد معلومات المنتجات من قاعدة بيانات Shopping.

يمثّل المورد productInput بيانات الإدخال التي ترسلها لمنتج معيّن. وتوفّر هذه الميزة أيضًا methods التي تتيح لك تعديل معلومات المنتجات أو حذفها واحدة تلو الأخرى أو حذف العديد منها في الوقت نفسه في وضع الحِزم. يجب أن يحتوي مرجع productInput على الحقول التالية:

• channel: القناة التي يُعرض فيها المنتج
• ‫offerId: المعرّف الفريد للمنتج
• contentLanguage: رمز اللغة المكوَّن من حرفَين وفق المعيار ISO 639-1 للمنتج
• feedLabel: تصنيف الخلاصة للمنتج.

تحميل إدخال منتج إلى حسابك

لتحميل إدخال منتج إلى حسابك، استخدِم أسلوب accounts.productInputs.insert. يجب إدخال المعرّف الفريد لمصدر البيانات الأساسي أو المصدر الإضافي.

يوضّح نموذج الطلب التالي كيفية استخدام الطريقة accounts.productInputs.insert لتحميل إدخال منتج إلى حسابك على التاجر. يحدِّد الطلب سعر الشحن والمنطقة، ويقوم أيضًا بضبط سمات مخصّصة، مثل تاريخ التصنيع والحجم.

POST https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource={DATASOURCE}

{
  "name": "{PRODUCT_TITLE}",
  "versionNumber": {VERSION_NUMBER},
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "feedLabel": "{FEED_LABEL}",
  "offerId": "{OFFER_ID}",
  "channel": "ONLINE",
  "attributes": {
    "availability": "in stock",
    "imageLink": "{IMAGE_LINK}",
    "link": "{PRODUCT_LINK}",
    "brand": "{BRAND_NAME}",
    "price": {
      "currencyCode": "{CURRENCY_CODE}",
      "amountMicros": {PRICE}
    },
    "color": "red",
    "productWeight": {
      "value": 320,
      "unit": "g"
    },
    "adult": false,
    "shipping": [
      {
        "country": "GB",
        "price": {
          "amountMicros": {SHIPPING_COST},
          "currencyCode": "{CURRENCY_CODE_SHIPPING}"
        },
        "postalCode": "{SHIPPING_POSTALCODE}",
        "service": "",
        "region": "{SHIPPING_REGION}",
        "maxHandlingTime": "{MAX_HANDLING_TIME}",
        "minHandlingTime": "{MIN_HANDLING_TIME}",
        "maxTransitTime": "{MAX_TRANSIT_TIME}",
        "minTransitTime": "{MIN_TRANSIT_TIME}"
      }
    ],
    "gender": "Female"
  },
  "customAttributes": [
    {
      "name": "size",
      "value": "Large"
    },
    {
      "name": "Date of Manufacturing",
      "value": "2024-05-05"
    }
  ]
}

غيِّر القيم في السلسلة على الشكل التالي:

• {ACCOUNT_ID}: المعرّف الفريد لحسابك على Merchant Center.
• {DATASOURCE}: المعرّف الفريد لمصدر البيانات. يجب أن يكون بالتنسيق accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}.
• {PRODUCT_TITLE}: اسم المنتج
• {VERSION_NUMBER}: رقم إصدار المنتج اختيارية:
• {CONTENT_LANGUAGE}: رمز اللغة المكوَّن من حرفَين وفق المعيار ISO 639-1 للمنتج. مطلوب.
• ‫{FEED_LABEL}: رمز CLDR للأقاليم الخاصة بال المنطقة التي تريد بيع المنتج فيها إذا كانت القيمة المقدَّمة لسمة feedLabel غير صالحة، لن تتم تعبئة حقل targetCountry.
• ‫{OFFER_ID}: المعرّف الفريد للمنتج مطلوب.
• {IMAGE_LINK}: رابط صورة المنتج على موقعك الإلكتروني اختيارية:
• {PRODUCT_LINK}: الرابط المؤدّي إلى المنتج على موقعك الإلكتروني اختيارية:
• ‫{CURRENCY_CODE}: تمثّل هذه السمة العملة المستخدَمة للسعر باستخدام اختصارات مكوّنة من ثلاثة أحرف وفقًا لمعيار ISO 4217. اختيارية:
• {PRICE}: سعر المنتج ممثّلاً كعدد بوحدة micro اختيارية:
• {SHIPPING_COST}: سعر الشحن الثابت ممثّلاً برقم. اختيارية:
• {SHIPPING_POSTALCODE}: نطاق الرمز البريدي الذي ينطبق عليه سعر الشحن. اختيارية:
• {MAX_HANDLING_TIME}: الحد الأقصى لوقت المناولة بال أيام العمل بين وقت استلام الطلب ووقت شحنه. اختيارية:
• {MIN_HANDLING_TIME}: الحد الأدنى لوقت المناولة بال أيام العمل بين وقت استلام الطلب ووقت شحنه. تشير القيمة 0 إلى أنّه يتم تسليم الطلب في اليوم نفسه الذي يتم استلامه فيه. اختيارية:
• {MAX_TRANSIT_TIME}: الحد الأقصى لمدة النقل بال أيام العمل بين وقت شحن الطلب ووقت تسليمه اختيارية:
• {MIN_TRANSIT_TIME}: الحد الأدنى لمدة النقل بالأيام العمل بين وقت شحن الطلب ووقت تسليمه تشير القيمة 0 إلى أنّه تم تسليم الطلب في اليوم نفسه الذي تم فيه شحنه. اختيارية:

عند تنفيذ الطلب بنجاح، يظهر الردّ التالي:

{
  "name": "{PRODUCT_NAME}",
  "product": "{PRODUCT_ID}",
  "channel": "ONLINE",
  "offerId": "{OFFER_ID}",
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "feedLabel": "{FEED_LABEL}",
  "versionNumber": "{VERSION_NUMBER}",
  "attributes": {
    "link": "{PRODUCT_LINK}",
    "imageLink": "{IMAGE_LINK}",
    "adult": false,
    "availability": "in stock",
    "brand": "{BRAND_NAME}",
    "color": "red",
    "gender": "Female",
    "price": {
      "amountMicros": "{PRICE}",
      "currencyCode": "{CURRENCY_CODE}"
    },
    "shipping": [
      {
        "price": {
          "amountMicros": "{SHIPPING_COST}",
          "currencyCode": "{CURRENCY_CODE}"
        },
        "country": "{SHIPPING_COUNTRY}",
        "region": "{SHIPPING_REGION}",
        "postalCode": "{SHIPPING_POSTALCODE}",
        "minHandlingTime": "{MIN_HANDLING_TIME}",
        "maxHandlingTime": "{MAX_HANDLING_TIME}",
        "minTransitTime": "{MIN_TRANSIT_TIME}",
        "maxTransitTime": "{MAX_TRANSIT_TIME}"
      }
    ],
    "productWeight": {
      "value": 320,
      "unit": "g"
    }
  },
  "customAttributes": [
    {
      "name": "Size",
      "value": "Large"
    },
    {
      "name": "Date of Manufacturing",
      "value": "2024-05-05"
    }
  ]
}

استرداد منتج تمت معالجته من حسابك

لاسترداد منتج تمت معالجته من حسابك، استخدِم طريقة accounts.products.get. قد يستغرق ظهور المنتج الذي تمت معالجته بعد إدراجه عدة دقائق.

يمكنك الحصول على اسم المورد للمنتج الذي تمت معالجته من حقل product في استجابة accounts.productInputs.insert.

حذف إدخال منتج من حسابك

لحذف إدخال منتج من حسابك، استخدِم الطريقة accounts.productInputs.delete. يجب إدخال المعرّف الفريد لمصدر البيانات الأساسي أو الإضافي الذي ينتمي إليه المنتج لحذف منتج باستخدام Merchant Products API.

إدراج المنتجات من حسابك

لعرض المنتجات التي تمت معالجتها في حسابك، استخدِم accounts.products.list الطريقة.