تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

خلاصة منتجات نشطة في Google Merchant Center
خلاصة عروض ترويجية نشطة في Google Merchant Center
حساب على إعلانات Google لـ حملات Shopping

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

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

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

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

يمكنك استخدام الإجراء accounts.dataSources.create لإنشاء مصدر بيانات عرض ترويجي. إذا كان هناك مصدر بيانات ترويجي حالي متاحًا، استخدِم الأسلوب accounts.dataSources.list لاسترداد جميع مصادر البيانات. يمكنك بعد ذلك استخدام حقل name في مصدر بيانات العرض الترويجي من أجل إنشاء عروض ترويجية.

يوضّح الطلب التالي كيفية إنشاء مصدر بيانات لإضافة عروض ترويجية:

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

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

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

{ACCOUNT_ID}: المعرّف الفريد لحسابك كما يظهر في واجهة مستخدم Merchant Center
{DISPLAY_NAME}: الاسم المعروض لمصدر البيانات
{CONTENT_LANGUAGE}: رمز اللغة المكوّن من حرفَين وفقًا لمعيار ISO 639-1 للمنتجات في مصدر البيانات
{TARGET_COUNTRY}: رمز CLDR للمنطقة البلد المستهدَف الذي تريد أن تظهر فيه العروض الترويجية.

بعد تنفيذ الطلب بنجاح، يظهر لك الردّ التالي الذي يحتوي على تفاصيل عن مصدر بيانات العروض الترويجية الذي تم إنشاؤه حديثًا:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

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

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

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

contentLanguage
redemptionChannel
promotionId
targetCountry
attributes.offerType
attributes.genericRedemptionCode
attributes.couponValueType
attributes.productApplicability
attributes.promotionEffectiveTimePeriod.endTime
attributes.promotionEffectiveTimePeriod.startTime
attributes.longTitle

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

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

يوضّح الطلب التالي كيفية إنشاء عرض ترويجي على الإنترنت:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "name": "{PROMOTION_NAME}",
    "promotionId": "{PROMOTION_ID}",
    "targetCountry": "{TARGET_COUNTRY}",
    "redemptionChannel": [
      "ONLINE"
    ],
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "attributes": {
      "promotionDisplayTimePeriod": {
        "endTime": "{PROMOTION_END_TIME}",
        "startTime": "{PROMOTION_START_TIME}"
      },
      "offerType": "{OFFER_TYPE}",
      "longTitle": "{LONG_TITLE}"
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

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

القيم الصالحة للحقل الإلزامي offerType هي NO_CODE و GENERIC_CODE. في حال عدم تقديم إحدى هاتين القيمتَين، سيتعذّر إرسال طلب واجهة برمجة التطبيقات مع ظهور استجابة HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type. تظهر رسالة خطأ مشابهة إذا لم تقدِّم أيًا من الحقول الإلزامية.

إذا لم تقدِّم قيمة للحقل attributes.genericRedemptionCode، سيتعذّر إكمال الطلب وسيظهر الردّ HTTP 400 [genericRedemptionCode] No redemption code provided.

يجب أن تكون قيم الحقلين promotion.attributes.promotionDisplayTimePeriod.startTime وpromotion.attributes.promotionDisplayTimePeriod.endTime بالتنسيق yyyy-mm-ddThh:mm:ssZ. احرص على استبدال قيم هذين الحدَدين بتواريخ في المستقبل.

لمزيد من المعلومات، اطّلِع على مواصفات بيانات العروض الترويجية.

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

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

بعد تنفيذ طلب إنشاء العرض الترويجي بنجاح، قد يستغرق الأمر بضع دقائق كي يصبح العرض الترويجي قابلاً للاسترجاع باستخدام واجهة برمجة التطبيقات أو كي يظهر في Merchant Center.

في ما يلي بعض نماذج العروض الترويجية التي يمكنك استخدامها للبدء.

عرض ترويجي محلي ينطبق على جميع المنتجات وجميع المتاجر

يوضّح نموذج الطلب التالي كيفية إنشاء عرض ترويجي محلي يسري على جميع المنتجات في حسابك على Merchant Center وجميع المتاجر التي تمت إضافتها في حساب الملف التجاري المرتبط.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/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/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

حقل productApplicability مطلوب. ويشير ذلك إلى إمكانية تطبيق العرض الترويجي على كل المنتجات أو على منتجات معيّنة فقط. القيم المسموح بها هي ALL_PRODUCTS وSPECIFIC_PRODUCTS. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة اختيار المنتجات للعرض الترويجي.

حقل couponValueType مطلوب. ويشير ذلك إلى نوع العرض الترويجي الذي تقدّمه. للحصول على قائمة بالقيم المسموح بها، راجِع نوع قيمة القسيمة. استنادًا إلى نوع قيمة القسيمة التي اخترتها، تكون بعض السمات مطلوبة.

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

وبالمثل، يمكنك استخدام الحقل minimumPurchaseAmount لتحديد الحدّ الأدنى لمبلغ الشراء المطلوب للاستفادة من العرض الترويجي. لمزيد من المعلومات، اطّلِع على الحدّ الأدنى لمبلغ الشراء.

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

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

يوضّح نموذج الطلب التالي كيفية إنشاء عرض ترويجي على الإنترنت ينطبق على منتجات محدّدة باستخدام رمز تحصيل قيمة.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/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/{ACCOUNT_ID}/dataSources/1000000573361824"
}

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

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

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

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

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

{ACCOUNT_ID}: المعرّف الفريد لحسابك على Merchant Center.
{PROMOTION_ID}: المعرّف الفريد للعرض الترويجي الذي تريد استرجاعه. التنسيق هو {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.

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

عرض عرض ترويجي محلي

يسترجع نموذج الطلب التالي عرضًا ترويجيًا محليًا بمعرّف العرض الترويجي هو in_store~en~US~buy_2_get_10_off.

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

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

{
 "name": "accounts/{ACCOUNT_ID}/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/{ACCOUNT_ID}/dataSources/1000000573361824"
}

يقدّم الحقل moneyOffAmount في هذا العيّنة الخصم المعروض في العرض الترويجي. لمزيد من المعلومات، يُرجى الاطّلاع على مبلغ الخصم النقدي لأحد العروض الترويجية.

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

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

يسترجع نموذج الطلب التالي عرضًا ترويجيًا على الإنترنت يكون رقم تعريفه هو online~en~US~25_pct_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
{
 "name": "accounts/{ACCOUNT_ID}/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_ID}/dataSources/{dataSource}"
}

يشير حقل itemIdInclusion المستخدَم في هذا العيّنة إلى المنتجات التي تكون مؤهّلة للعرض الترويجي. لمزيد من المعلومات، يُرجى الاطّلاع على معرّف المنتج لمحاولة الترويج.

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

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

GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions

يحتوي الردّ على قائمة بجميع العروض الترويجية في حسابك. لكل رمز إشتراك داعم، يمكنك الاطّلاع على تفاصيل مثل promotionId وredemptionChannel dataSource وpromotionStatus والمزيد.

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

للاطّلاع على حالة عرض ترويجي، اطّلِع على السمة promotionStatus التي تعرضها الطريقة promotions.get أو promotions.list.

يمكن أن يحتوي الحقل promotionStatus على القيم التالية:

IN_REVIEW: لا يزال العرض الترويجي قيد المراجعة.
REJECTED: تم رفض العرض الترويجي.
LIVE: تمّت الموافقة على العرض الترويجي وهو نشط.
‫STOPPED: تم إيقاف العرض الترويجي من خلال الحساب.
EXPIRED: لم يعُد العرض الترويجي نشطًا.
PENDING: لم يتم إيقاف العرض الترويجي، وتمّت الموافقة على جميع المراجعات، ولكن يقع تاريخ التفعيل في المستقبل.
STATE_UNSPECIFIED: حالة العرض الترويجي غير معروفة.

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

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

توضّح العيّنات التالية الفرق بين الطلبات الناجحة والطلبات التي تنتهي بالفشل.

عدم توفّر عملية ربط المنتجات

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

  "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"
        ]
      }
    ]
  }

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

إذا لم تتم الموافقة على العرض الترويجي الذي أنشأته، ستصلك رسالة إلكترونية توضّح سبب الرفض وتتضمن تعليمات لحلّ المشاكل.

العرض الترويجي قيد التقييم

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

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

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

يعرض نص الاستجابة التالي عرضًا ترويجيًا يظهر للمتسوّقين.

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

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

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

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