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

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

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

لمزيد من المعلومات، راجِع أساسيات العروض الترويجية.

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

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

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

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

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

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

استخدِم واجهة برمجة التطبيقات datasource.create لإنشاء خلاصة عروض ترويجية. في حال توفّر خلاصة عروض ترويجية حالية، استخدِم datasource.get لجلب datasource.name

يكون شكل الطلب على النحو التالي:

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

مثال

يعرض المثال طلبًا وردًّا نموذجيين.

الطلب:

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 واسم مصدر بيانات كإدخال. يعرض الإعلان الترويجي الجديد أو المحدّث في حال نجاحه.

لإنشاء عرض ترويجي، يجب إدخال datasource.name.

تُراجع 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"
      },
      "minimum_purchase_quantity": 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"
}

ملاحظات خاصة

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

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

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

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

للاطّلاع على عرض ترويجي، استخدِم 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"
   },
   "minimum_purchase_quantity": 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. عرض ترويجي موافَق عليه ونشره على YouTube

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

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

لمزيد من التفاصيل، راجع مركز مساعدة العروض الترويجية.

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