مهم: API محتوا برای خرید در ۱۸ آگوست ۲۰۲۶ غیرفعال شد.

از ۱ سپتامبر ۲۰۲۶ ، رابط برنامه‌نویسی کاربردی محتوا برای درخواست‌های خرید با خطاهای پیش‌رونده مواجه خواهد شد. راهنمای انقضای رابط برنامه‌نویسی کاربردی محتوا را مرور کنید.

اگر برای مهاجرت به Merchant API به زمان بیشتری نیاز دارید، برای دسترسی بیشتر به Content API for Shopping درخواست دهید .

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

نمای کلی میانای برنامه‌سازی کاربردی فرعی «تبلیغات»

از تبلیغات ویژه برای نمایش پیشنهادهای ویژه محصولاتتان که در Google می‌فروشید استفاده کنید. عرضه‌های ترویجی در دارایی‌های مختلف Google ازجمله «جستجوی Google»، Shopping، و Chrome نمایش داده می‌شود. عرضه‌های ترویجی باید معیارهای خاصی را برآورده کنند تا تأیید شوند. برای اطلاعات بیشتر، معیارهای عرضه ترویجی را ببینید.

وقتی به محصولاتتان تبلیغات اضافه می‌کنید، خریداران پیوند پیشنهاد ویژه را می‌بینند. برای مثال، «‫٪۱۵ تخفیف» یا «ارسال رایگان». پیوندهای پیشنهاد ویژه می‌تواند جذابیت محصولاتتان را افزایش دهد و خریداران را به خرید تشویق کند. همه تبلیغات ویژه در تسویه‌حساب یا پایانه فروش اعمال می‌شوند.

برای اطلاعات بیشتر، به اصول اولیه عرضه ترویجی مراجعه کنید.

پیش‌نیازها

‫Google قبل‌از نمایش تبلیغات ویژه شما، باید اطلاعات خاصی درباره کسب‌وکار و محصولاتتان دریافت کند. باید موارد زیر را داشته باشید:

منبع داده محصول در Google Merchant Center.
یک منبع داده ترویج‌ها در Google Merchant Center.
حساب Google Ads برای پویش‌های Shopping.

علاوه‌براین، باید حساب Merchant Center خود را در برنامه «تبلیغات ویژه» ثبت کنید. اگر مطمئن نیستید که قبلاً ثبت‌نام کرده‌اید یا نه، Merchant Center را بررسی کنید.

اگر ثبت‌نام نکرده‌اید، فرم درخواست را تکمیل کنید. تیم تبلیغات به شما اطلاع خواهد داد که چه زمانی برای شروع پیاده‌سازی آماده هستید.

برای اطلاعات بیشتر، معیارهای مشارکت و خط‌مشی‌ها را ببینید.

ایجاد منبع داده

می‌توانید از روش accounts.dataSources.create برای ایجاد منبع داده تبلیغات استفاده کنید. اگر منبع داده تبلیغات ویژه موجودی دردسترس است، از روش accounts.dataSources.list برای بازیابی همه منابع داده استفاده کنید. سپس می‌توانید از فیلد name منبع داده تبلیغات برای ایجاد تبلیغات استفاده کنید.

برای ارجاع مستقیم به آن‌ها در تماس‌های آتی با API، قویاً توصیه می‌کنیم accounts.dataSources.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 {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. اگر یکی از این مقادیر را ارائه نکنید، درخواست API با پاسخ 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 باشد. حتماً مقادیر این فیلدها را با تاریخ‌هایی که در آینده هستند جایگزین کنید.

برای اطلاعات بیشتر، به مشخصات داده‌های تبلیغات مراجعه کنید.

برای روال‌های مطلوب درباره ایجاد ترویج، به روال‌های مطلوب ترویج‌ها مراجعه کنید.

برای فهرست مشخصه‌های مربوط به تبلیغات ویژه، به افزودن مشخصه‌های داده‌های ساختاریافته مراجعه کنید.

پس‌از اینکه درخواست ایجاد عرضه ترویجی با موفقیت اجرا شد، ممکن است چند دقیقه طول بکشد تا عرضه ترویجی بااستفاده از API قابل‌بازیابی شود یا در Merchant Center ظاهر شود.

در اینجا نمونه‌ای آورده شده است که می‌توانید از آن برای درج هم‌زمان چندین تبلیغ ویژه استفاده کنید:

جاوا

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.api.gax.grpc.ChannelPoolSettings;
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
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();

    // Creates a channel provider. This provider manages a pool of gRPC channels
    // to enhance throughput for bulk operations. Each individual channel in the pool
    // can handle up to approximately 100 concurrent requests.
    //
    // Channel: A single connection pathway to the service.
    // Pool: A collection of multiple channels managed by this provider.
    //   Requests are distributed across the channels in the pool.
    //
    // We recommend estimating the number of concurrent requests you'll make, divide by 50 (50%
    // utilization of channel capacity), and set the pool size to that number.
    InstantiatingGrpcChannelProvider channelProvider =
        InstantiatingGrpcChannelProvider.newBuilder()
            .setChannelPoolSettings(ChannelPoolSettings.staticallySized(30))
            .build();

    PromotionsServiceSettings merchantPromotionsServiceSettings =
        PromotionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .setTransportChannelProvider(channelProvider)
            .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 {ACCESS_TOKEN}' \
   --header 'Accept: application/json' \
   --compressed

جایگزین کردن موارد زیر:

‫{ACCOUNT_ID}: شناسه یکتای حساب Merchant Center شما.
{PROMOTION_ID}: شناسه یکتای تبلیغ ویژه‌ای که می‌خواهید بازیابی کنید. قالب {CHANNEL}~{CONTENT_LANGUAGE}~ {TARGET_COUNTRY}~{PROMOTION_ID} است.

توجه داشته باشید که چند دقیقه طول می‌کشد تا ترویج تازه ایجادشده بااستفاده از API قابل‌بازیابی شود.

مشاهده عرضه ترویجی محلی

درخواست نمونه زیر تبلیغات محلی را که شناسه تبلیغات آن 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 {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": []
  }

برای اطلاعات بیشتر، پرسشگان وضعیت عرضه ترویجی را ببینید.

حذف تبلیغات

حذف کردن تبلیغات ویژه بااستفاده از API امکان‌پذیر نیست. برای حذف کردن تبلیغات ویژه، باید به «میانای کاربر Merchant Center» دسترسی داشته باشید. برای اطلاعات بیشتر، ویرایش ترویج یا تغییر وضعیت ترویج را ببینید.

برای پایان دادن به یک تبلیغ ویژه موجود، می‌توانید از روش accounts.promotions.insert برای به‌روزرسانی فیلد attributes.promotionEffectiveTimePeriod.endTime به زمانی در گذشته استفاده کنید.

بیشتر بدانید

برای جزئیات بیشتر، مرکز راهنمایی تبلیغات را ببینید.
برای عیب‌یابی کردن مشکلات رایج، عیب‌یابی کردن مشکلات مربوط به زیر API «تبلیغات ویژه» را ببینید.
برای آشنایی با انتقال از «میانای برنامه‌سازی کاربردی محتوا برای Shopping»، به انتقال مدیریت تبلیغات مراجعه کنید.

بعدی

Troubleshoot issues

نمای کلی میانای برنامه‌سازی کاربردی فرعی «تبلیغات» با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

پیش‌نیازها

ایجاد منبع داده

ایجاد تبلیغات ویژه

HTTP

cURL

جاوا

عرضه ترویجی محلی برای همه محصولات و همه فروشگاه‌ها

تبلیغ آنلاین که برای محصولات منتخب با کد پس‌خرید اعمال می‌شود

مشاهده تبلیغات

HTTP

cURL

مشاهده عرضه ترویجی محلی

مشاهده ترویج آنلاین

فهرست کردن تبلیغات

HTTP

cURL

مشاهده وضعیت تبلیغ ویژه

وضعیت تبلیغ نمونه

حذف تبلیغات

بیشتر بدانید

نمای کلی میانای برنامه‌سازی کاربردی فرعی «تبلیغات»