نظرة عامة على واجهة برمجة التطبيقات للرسائل الترويجية للتاجر

استخدِم العروض الترويجية لعرض عروض خاصة للمنتجات التي تبيعها على Google. تظهر العروض الترويجية على خدمات Google المختلفة، بما في ذلك "بحث Google" و Shopping وChrome.

عند إضافة عروض ترويجية إلى منتجاتك، سيرى المتسوّقون رابط عرض خاص، مثلاً "خصم% 15" أو "شحن مجاني". يمكن أن تساهم روابط العروض في زيادة جاذبية منتجاتك وتشجيع المتسوّقين على إجراء عملية شراء.

لمزيد من المعلومات، اطّلِع على أساسيات المحتوى الترويجي.

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

يجب أن تقدّم إلى Google معلومات محدّدة عن نشاطك التجاري ومنتجاتك قبل عرض عروضك الترويجية. يجب توفّر ما يلي:

بالإضافة إلى ذلك، يجب تسجيل حساب التاجر في برنامج "العروض الترويجية". إذا لم تكن متأكدًا مما إذا سبق لك الاشتراك، يُرجى التحقّق من Merchant Center.

إذا لم تكن مسجّلاً، يُرجى إكمال نموذج طلب. وسيُعلمك فريق الرسائل الترويجية بالوقت المناسب للبدء بعرضها.

لمزيد من المعلومات، يُرجى الاطّلاع على معايير ومتطلبات المشاركة في البرنامج.

إنشاء مصدر بيانات

استخدِم واجهة برمجة التطبيقات datasource.create لإنشاء خلاصة عرض ترويجي. إذا كانت هناك خلاصة عروض ترويجية حالية متاحة، استخدِم طريقة accounts.dataSources.get للحصول على اسم مصدر البيانات.

في ما يلي شكل الطلب:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{account}/dataSources

مثال

يعرض المثال طلبًا واستجابةً نموذجيَين.

الطلب:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/123/dataSources {"displayName": "test api feed", "promotionDataSource":{"targetCountry":"US", "contentLanguage":"en"}}

الردّ:

{
  "name": "accounts/123/dataSources/1000000573361824",
  "dataSourceId": "1000000573361824",
  "displayName": "test api feed",
  "promotionDataSource": {
    "targetCountry": "US",
    "contentLanguage": "en"
  },
  "input": "API"
}

إنشاء إعلانات ترويجية

يمكنك استخدام الوسيطة accounts.promotions.insert لإنشاء عرض ترويجي أو تعديله. تأخذ طريقة accounts.promotions.insert مورد promotions واسم مصدر بيانات كمدخلات. ويعرض الإجراء الترويجي الجديد أو المعدَّل في حال نجاح العملية.

يتطلّب إنشاء عرض ترويجي إدخال اسم مصدر البيانات.

يراجع فريق Google إعلاناتك الترويجية ويوافق عليها قبل نشرها. لمزيد من المعلومات، اطّلِع على عملية الموافقة على العروض الترويجية.

نموذج الطلب:

POST https://merchantapi.googleapis.com/promotions/v1beta/{parent=accounts/*/}promotions:insert

راجِع نماذج العروض الترويجية التالية للاطّلاع على مزيد من المعلومات.

المثال 1: مروّج محلي سارٍ على كل المنتجات وجميع المتاجر

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/promotions:insert

{
  "promotion": {
    "promotionId": "buy_2_get_10_off",
    "contentLanguage": "en",
    "targetCountry": "US",
    "redemptionChannel": [
      "IN_STORE"
    ],
    "attributes": {
      "longTitle": "Buy 2 and get 10$ OFF purchase",
      "productApplicability": "ALL_PRODUCTS",
      "offerType": "NO_CODE",
      "couponValueType": "BUY_M_GET_MONEY_OFF",
      "promotionDisplayTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "promotionEffectiveTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "moneyOffAmount": {
        "amountMicros": "1000000",
        "currencyCode": "USD"
      },
      "minimumPurchaseQuantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/123/dataSources/1000000573361824"
}

المثال 2: عرض ترويجي على الإنترنت ينطبق على منتجات محدّدة باستخدام رمز تحصيل قيمة 

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/promotions:insert

{
 "promotion": {
   "promotionId": "25_pct_off",
   "contentLanguage": "en",
   "targetCountry": "US",
   "redemptionChannel": [
     "ONLINE"
   ],
   "attributes": {
     "longTitle": "10% off on selected items",
     "productApplicability": "SPECIFIC_PRODUCTS",
     "offerType": "GENERIC_CODE",
     "genericRedemptionCode": "SPRINGSALE",
     "couponValueType": "PERCENT_OFF",
     "promotionDisplayTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "promotionEffectiveTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "percentOff": 25,
     "promotionDestinations": [
       "FREE_LISTINGS"
     ],
     "itemIdInclusion": [
       "1499860100",
       "1499860101",
       "1499860102",
       "1499860103",
       "1499860104"
     ],
   }
 },
 "dataSource": "accounts/123/dataSources/1000000573361824"
}

ملاحظات خاصة

بعد إنشاء العرض الترويجي، قد يستغرق ظهوره في قاعدة بيانات Shopping بضع دقائق.

للحصول على قائمة بالسمات المتعلّقة بالعروض الترويجية، اطّلِع على إضافة سمات البيانات المنظَّمة.

قبل إنشاء العروض الترويجية وإدارتها، اطّلِع على أفضل الممارسات المتعلّقة بالعروض الترويجية.

الاطّلاع على العروض الترويجية

لعرض عرض ترويجي، استخدِم accounts.promotions.get. هذه العملية للقراءة فقط. يتطلّب ذلك إدخال merchantId ورقم تعريف الخطوة الترويجية. تُرجع الطريقة get مورد العروض الترويجية المقابل.

على سبيل المثال:

GET https://merchantapi.googleapis.com/promotions/v1beta/{name=accounts/*/promotions/*}

راجِع هذه العيّنات.

المثال 1: عرض ترويجي محلي

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/promotions/in_store~en~US~buy_2_get_10_off

{
 "name": "accounts/123/promotions/in_store~en~US~buy_2_get_10_off",
 "promotionId": "buy_2_get_10_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "IN_STORE"
 ],
 "attributes": {
   "longTitle": "Buy 2 and get 10$ OFF purchase",
   "productApplicability": "ALL_PRODUCTS",
   "offerType": "NO_CODE",
   "couponValueType": "BUY_M_GET_MONEY_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "moneyOffAmount": {
     "amountMicros": "1000000",
     "currencyCode": "USD"
   },
   "minimumPurchaseQuantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/123/dataSources/1000000573361824"
}

العيّنة 2 عرض ترويجي على الإنترنت

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/promotions/online~en~US~25_pct_off
{
 "name": "accounts/123/promotions/online~en~US~25_pct_off",
 "promotionId": "25_pct_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "ONLINE"
 ],
 "attributes": {
   "longTitle": "10% off on selected items",
   "productApplicability": "SPECIFIC_PRODUCTS",
   "offerType": "GENERIC_CODE",
   "genericRedemptionCode": "WINTERGIFT",
   "couponValueType": "PERCENT_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "percentOff": 25,
   "promotionDestinations": [
     "FREE_LISTINGS"
   ],
   "itemIdInclusion": [
     "1499860100",
     "1499860101",
     "1499860102",
     "1499860103",
     "1499860104"
   ],
 }
 "dataSource": "accounts/{account}/dataSources/{dataSource}"
}

عرض العروض الترويجية

يمكنك استخدام الرمز promotions.list لعرض جميع العروض الترويجية التي تم إنشاؤها.

GET https://merchantapi.googleapis.com/promotions/v1beta/{parent=accounts/*}/promotions

حالة العرض الترويجي

للاطّلاع على حالة عرض ترويجي، يمكنك عرض السمة promotionStatus التي يعرضها العنصران promotions.get وpromotions.list.

للتعرّف على عملية الموافقة، اطّلِع على عملية الموافقة على العروض الترويجية.

أمثلة على حالة العرض الترويجي

توضّح العيّنات التالية الفرق بين الطلبات التي تمّ إجراؤها بنجاح والطلبات التي تعذّر إجراؤها.

العيّنة 1 يعرض نص الردّ التالي عرضًا ترويجيًا على الإنترنت سيتم رفضه بسبب عدم توفّر تعيين المنتجات.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "REJECTED"
      }
    ],
    "itemLevelIssues": [
      {
        "code": "promotion_sku_unmapped",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Unmapped",
        "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      },
      {
        "code": "promotion_sku_additional_requirements",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Promotion conditions not allowed",
        "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      }
    ]
  }

العيّنة 2 يعرض نص الردّ التالي عرضًا ترويجيًا لا يزال قيد التقييم.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "PENDING"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "PENDING"
      }
    ],
    "itemLevelIssues": []
  }

العيّنة 3 عرض ترويجي منشور وتمت الموافقة عليه

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "LIVE"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "LIVE"
 }  ],
    "itemLevelIssues": []
  }

مزيد من المعلومات

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

للتعرّف على كيفية نقل البيانات من Content API for Shopping، يُرجى الاطّلاع على مقالة نقل إدارة العروض الترويجية.