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

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

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

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

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

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

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

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

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

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

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

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

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

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

POST https://merchantapi.googleapis.com/datasources/v1/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".

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

HTTP

POST https://merchantapi.googleapis.com/promotions/v1/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}"
}

cURL

  curl --request POST \
'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert?key=[YOUR_API_KEY]' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"dataSource":"{DATASOURCE_ID}","promotion":{"name":"accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}y","promotionId":"abc","contentLanguage":"en","targetCountry":"US","redemptionChannel":["ONLINE"]}}' \
--compressed

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

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

إذا لم تقدّم قيمة للحقل attributes.genericRedemptionCode، سيتعذّر تنفيذ الطلب وستتلقّى الاستجابة [genericRedemptionCode] No redemption code provided HTTP 400.

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

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

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

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

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

في ما يلي عيّنة يمكنك استخدامها لإدراج عروض ترويجية متعددة بشكل غير متزامن:

Java

import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.protobuf.Timestamp;
import com.google.shopping.merchant.promotions.v1.Attributes;
import com.google.shopping.merchant.promotions.v1.CouponValueType;
import com.google.shopping.merchant.promotions.v1.InsertPromotionRequest;
import com.google.shopping.merchant.promotions.v1.OfferType;
import com.google.shopping.merchant.promotions.v1.ProductApplicability;
import com.google.shopping.merchant.promotions.v1.Promotion;
import com.google.shopping.merchant.promotions.v1.PromotionsServiceClient;
import com.google.shopping.merchant.promotions.v1.PromotionsServiceSettings;
import com.google.shopping.merchant.promotions.v1.RedemptionChannel;
import com.google.shopping.type.CustomAttribute;
import com.google.shopping.type.Destination.DestinationEnum;
import com.google.type.Interval;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert multiple promotions asynchronously. */
public class InsertPromotionsAsyncSample {

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static Promotion createPromotion(String accountId) {
    String merchantPromotionId = generateRandomString();

    Attributes attributes =
        Attributes.newBuilder()
            .setProductApplicability(ProductApplicability.ALL_PRODUCTS)
            .setOfferType(OfferType.GENERIC_CODE)
            .setGenericRedemptionCode("ABCD1234")
            .setLongTitle("My promotion")
            .setCouponValueType(CouponValueType.PERCENT_OFF)
            .addPromotionDestinations(DestinationEnum.SHOPPING_ADS)
            .setPercentOff(10)
            // Note that promotions have a 6-month limit.
            // For more information, read here: https://support.google.com/merchants/answer/2906014
            // Also note that only promotions valid within the past 365 days are shown in the UI.
            .setPromotionEffectiveTimePeriod(
                Interval.newBuilder()
                    .setStartTime(Timestamp.newBuilder().setSeconds(1726842472))
                    .setEndTime(Timestamp.newBuilder().setSeconds(1726842473))
                    .build())
            .build();

    return Promotion.newBuilder()
        .setName(String.format("accounts/%s/merchantPromotions/%s", accountId, merchantPromotionId))
        .setPromotionId(merchantPromotionId)
        .setContentLanguage("fr")
        .setTargetCountry("CH")
        .addRedemptionChannel(RedemptionChannel.ONLINE)
        .setAttributes(attributes)
        // Custom attributes allow you to add additional information which is not available in
        // Attributes. For example, you might want to pilot experimental functionality.
        .addCustomAttributes(
            CustomAttribute.newBuilder()
                .setName("another example name")
                .setValue("another example value")
                .build())
        .build();
  }

  public static void asyncInsertPromotions(String accountId, String dataSourceId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    PromotionsServiceSettings merchantPromotionsServiceSettings =
        PromotionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    try (PromotionsServiceClient merchantPromotionsServiceClient =
        PromotionsServiceClient.create(merchantPromotionsServiceSettings)) {

      // Arbitrarily creates five merchant promotions with random IDs.
      List<InsertPromotionRequest> requests = new ArrayList<>();
      for (int i = 0; i < 5; i++) {
        InsertPromotionRequest request =
            InsertPromotionRequest.newBuilder()
                .setParent(String.format("accounts/%s", accountId))
                .setPromotion(createPromotion(accountId))
                .setDataSource(String.format("accounts/%s/dataSources/%s", accountId, dataSourceId))
                .build();
        requests.add(request);
      }

      // Inserts the merchant promotions.
      List<ApiFuture<Promotion>> futures =
          requests.stream()
              .map(
                  request ->
                      merchantPromotionsServiceClient.insertPromotionCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<Promotion>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<Promotion>>() {
            @Override
            public void onSuccess(List<Promotion> results) {
              System.out.println("Inserted merchant promotions below:");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());
    } catch (Exception e) {
      System.out.println(e);
    }
  }


  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    asyncInsertPromotions(config.getAccountId().toString(), "<YOUR_DATA_SOURCE_ID>");
  }
}InsertPromotionsAsyncSample.java

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

عرض ترويجي محلي يسري على جميع المنتجات وجميع المتاجر

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

POST https://merchantapi.googleapis.com/promotions/v1/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/v1/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 مورد العروض الترويجية المقابل.

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

HTTP

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

cURL

  curl \
   'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}?key=[YOUR_API_KEY]' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --compressed

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

{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/v1/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/v1/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 للاطّلاع على جميع العروض الترويجية التي تم إنشاؤها.

في ما يلي نموذج للطلب:

HTTP

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

cURL

  curl \
   'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions?key=[YOUR_API_KEY]' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --compressed

يتضمّن الردّ قائمة بجميع العروض الترويجية في حسابك. يمكنك الاطّلاع على تفاصيل كل عرض ترويجي، مثل 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": []
  }

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

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

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

لإنهاء عرض ترويجي حالي، يمكنك استخدام طريقة accounts.promotions.insert لتعديل الحقل attributes.promotionEffectiveTimePeriod.endTime إلى وقت سابق.

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

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

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

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

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

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

HTTP

cURL

Java

عرض ترويجي محلي يسري على جميع المنتجات وجميع المتاجر

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

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

HTTP

cURL

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

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

عرض قائمة العروض الترويجية

HTTP

cURL

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

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

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

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

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