REST Resource: accounts.promotions

المرجع: العرض الترويجي

يمثّل عرضًا ترويجيًا. يمكنك الاطّلاع على المقالات التالية للحصول على مزيد من التفاصيل.

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

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

تمثيل JSON 
{
  "name": string,
  "promotionId": string,
  "contentLanguage": string,
  "targetCountry": string,
  "redemptionChannel": [
    enum (RedemptionChannel)
  ],
  "dataSource": string,
  "attributes": {
    object (Attributes)
  },
  "customAttributes": [
    {
      object (CustomAttribute)
    }
  ],
  "promotionStatus": {
    object (PromotionStatus)
  },
  "versionNumber": string
}
الحقول
name

string

المعرّف اسم الترويج. التنسيق: accounts/{account}/promotions/{promotion}
promotionId

string

مطلوب. قدّم المستخدِم المعرّف الترويجي لتحديد العرض الترويجي بشكلٍ فريد. اتّبِع الحدّ الأدنى من المتطلبات لتجنّب رفض العروض الترويجية.
contentLanguage

string

مطلوب. الرمز المكوَّن من حرفَين وفق المعيار ISO 639-1 للغة العرض الترويجي

تتوفّر العروض الترويجية بلغات محدّدة فقط.
targetCountry

string

مطلوب. البلد المستهدَف المستخدَم كجزء من المعرّف الفريد يتم تمثيلها على شكل رمز CLDR للمنطقة.

لا تتوفّر العروض الترويجية إلا في بلدان محدّدة، البيانات المجانية وإعلانات Shopping إعلانات للمنتجات داخل المتجر
redemptionChannel[]

enum (RedemptionChannel)

مطلوب. قناة تحصيل القيمة للعرض الترويجي يجب توفّر قناة واحدة على الأقل.
dataSource

string

النتائج فقط. مصدر البيانات الأساسي للعرض الترويجي.
attributes

object (Attributes)

اختيارية: قائمة بسمات العرض الترويجي
customAttributes[]

object (CustomAttribute)

اختيارية: قائمة بالسمات المخصّصة (التي يقدّمها التاجر) ويمكن أيضًا استخدامه لإرسال أيّ سمة من مواصفات البيانات في شكلها العام (على سبيل المثال، { "name": "size type", "value": "regular" }). ويُعدّ ذلك مفيدًا لإرسال السمات التي لا تعرضها واجهة برمجة التطبيقات بشكل صريح.
promotionStatus

object (PromotionStatus)

النتائج فقط. حالة العرض الترويجي، ومشاكل التحقّق من البيانات، أي معلومات عن عرض ترويجي يتم احتسابها بشكل غير متزامن
versionNumber

string (int64 format)

اختيارية: يمثّل الإصدار الحالي (الحداثة) من العرض الترويجي، والذي يمكن استخدامه للحفاظ على الترتيب الصحيح عند إجراء عدّة تعديلات في الوقت نفسه.

في حال ضبطها، يتم منع الإدراج عندما يكون رقم الإصدار أقل من رقم الإصدار الحالي للعرض الترويجي الحالي. يمكن إجراء إعادة الإدراج (على سبيل المثال، إعادة تحميل العرض الترويجي بعد 30 يومًا) باستخدام versionNumber الحالية.

في حال منع العملية، سيتم طرح استثناء تم إلغاؤه.

RedemptionChannel

قناة عرض عرض ترويجي

عمليات التعداد
REDEMPTION_CHANNEL_UNSPECIFIED يشير إلى أنّ القناة غير محدّدة.
IN_STORE يشير إلى أنّ القناة متوفّرة في المتجر. هذا هو نفسه قناة local المستخدَمة في products.
ONLINE يشير إلى أنّ القناة متاحة على الإنترنت.

السمات

السمات

تمثيل JSON 
{
  "productApplicability": enum (ProductApplicability),
  "offerType": enum (OfferType),
  "genericRedemptionCode": string,
  "longTitle": string,
  "couponValueType": enum (CouponValueType),
  "promotionDestinations": [
    enum (DestinationEnum)
  ],
  "itemIdInclusion": [
    string
  ],
  "brandInclusion": [
    string
  ],
  "itemGroupIdInclusion": [
    string
  ],
  "productTypeInclusion": [
    string
  ],
  "itemIdExclusion": [
    string
  ],
  "brandExclusion": [
    string
  ],
  "itemGroupIdExclusion": [
    string
  ],
  "productTypeExclusion": [
    string
  ],
  "minimumPurchaseAmount": {
    object (Price)
  },
  "minimumPurchaseQuantity": string,
  "limitQuantity": string,
  "limitValue": {
    object (Price)
  },
  "percentOff": string,
  "moneyOffAmount": {
    object (Price)
  },
  "getThisQuantityDiscounted": string,
  "freeGiftValue": {
    object (Price)
  },
  "freeGiftDescription": string,
  "freeGiftItemId": string,
  "promotionEffectiveTimePeriod": {
    object (Interval)
  },
  "promotionDisplayTimePeriod": {
    object (Interval)
  },
  "storeApplicability": enum (StoreApplicability),
  "storeCodesInclusion": [
    string
  ],
  "storeCodesExclusion": [
    string
  ],
  "promotionUrl": string
}
الحقول
productApplicability

enum (ProductApplicability)

مطلوب. يشير ذلك إلى ما إذا كان العرض الترويجي ينطبق على جميع المنتجات أو على منتجات معيّنة فقط.
offerType

enum (OfferType)

مطلوب. نوع العرض الترويجي استخدِم هذه السمة لإبلاغ العملاء بما إذا كانوا بحاجة إلى رمز قسيمة للاستفادة من العرض الترويجي.
genericRedemptionCode

string

اختيارية: رمز عام لتحصيل قيمة العرض الترويجي أن تكون قابلة للاستخدام مع حقل offerType وأن تستوفي الحد الأدنى من المتطلبات
longTitle

string

مطلوب. العنوان الكامل للعرض الترويجي
couponValueType

enum (CouponValueType)

مطلوب. سمة نوع قيمة القسيمة للإشارة إلى نوع العرض الترويجي الذي تقدّمه استنادًا إلى نوع قيمة القسيمة المحدّدة، تكون بعض السمات مطلوبة.
promotionDestinations[]

enum (DestinationEnum)

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

من المحتمل أنّك أرسلت في السابق القيم التالية كوجهات لمنتجاتك: Shopping Actions وSurfaces across Google وLocal surfaces across Google. لتمثيل هذه القيم، استخدِم FREE_LISTINGS وFREE_LOCAL_LISTINGS وLOCAL_INVENTORY_ADS. لمزيد من التفاصيل، يُرجى الاطّلاع على وجهة العرض الترويجي.
itemIdInclusion[]

string

اختيارية: فلتر المنتجات حسب معرّف السلعة للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products.
brandInclusion[]

string

اختيارية: فلترة المنتجات حسب العلامة التجارية للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products.
itemGroupIdInclusion[]

string

اختيارية: فلترة المنتجات حسب معرّف مجموعة السلع للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي [productApplicability] على القيمة specific_products.
productTypeInclusion[]

string

اختيارية: فلتر المنتجات حسب نوع المنتج للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products.
itemIdExclusion[]

string

اختيارية: فلتر المنتجات حسب استبعاد معرّف السلعة للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products.
brandExclusion[]

string

اختيارية: فلترة المنتجات حسب استبعاد العلامة التجارية للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products.
itemGroupIdExclusion[]

string

اختيارية: فلترة المنتجات حسب معرّف مجموعة السلع لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products. استبعاد للعرض الترويجي.
productTypeExclusion[]

string

اختيارية: فلترة المنتجات حسب استبعاد نوع المنتج للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products.
minimumPurchaseAmount

object (Price)

اختيارية: الحدّ الأدنى لمبلغ الشراء للاستفادة من العرض الترويجي
minimumPurchaseQuantity

string (int64 format)

اختيارية: الحدّ الأدنى لكمية السلع المطلوب شراؤها للاستفادة من العرض الترويجي
limitQuantity

string (int64 format)

اختيارية: الحدّ الأقصى المسموح به لكمية السلع الممكن شراؤها باستخدام العرض الترويجي
limitValue

object (Price)

اختيارية: الحدّ الأقصى لسعر المنتج في العرض الترويجي
percentOff

string (int64 format)

اختيارية: النسبة المئوية للخصم المقدَّمة في العرض الترويجي
moneyOffAmount

object (Price)

اختيارية: المبلغ المخفَّض المقدَّم في العرض الترويجي
getThisQuantityDiscounted

string (int64 format)

اختيارية: عدد السلع التي تم تطبيق خصم عليها في العرض الترويجي. يتمّ ضبط السمة عندما تكون couponValueType مساوية لـ buy_m_get_n_money_off أو buy_m_get_n_percent_off.
freeGiftValue

object (Price)

اختيارية: قيمة الهدية المجانية للعرض الترويجي
freeGiftDescription

string

اختيارية: وصف الهدية المجانية للعرض الترويجي
freeGiftItemId

string

اختيارية: معرّف السلعة الخاصة بالهدية المجانية للعرض الترويجي
promotionEffectiveTimePeriod

object (Interval)

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

object (Interval)

اختيارية: TimePeriod تمثيل تواريخ عرض العرض الترويجي تحدّد هذه السمة التاريخ والإطار الزمني لنشر العرض الترويجي على Google.com وإعلانات Shopping. إذا لم يتم تحديد سمة "فترة عرض العرض الترويجي" promotionDisplayTimePeriod، ستحدّد سمة "فترة سريان العرض الترويجي" promotionEffectiveTimePeriod التاريخ والإطار الزمني لعرض الإعلان الترويجي على Google.com وإعلانات Shopping.
storeApplicability

enum (StoreApplicability)

اختيارية: ما إذا كان العرض الترويجي ينطبق على جميع المتاجر أو على متاجر محدّدة فقط تؤدي العروض الترويجية لإعلانات المنتجات داخل المتجر إلى ظهور خطأ في حال عدم تضمين مدى توفّر المنتج في المتجر. يتم طرح خطأ INVALID_ARGUMENT إذا تم ضبط storeApplicability على ALL_STORES وتم ضبط storeCodesInclusion أو score_code_exclusion على قيمة.
storeCodesInclusion[]

string

اختيارية: رموز المتاجر المطلوب تضمينها في العرض الترويجي لا تنطبق سمات فلاتر المتاجر إلا عند ضبط سمة storeApplicability على specific_stores.

رمز المتجر (معرّف المتجر من ملفك التجاري) للمتجر المادي الذي يُباع فيه المنتج اطّلِع على مواصفات بيانات المنتجات المتوفّرة داخل المتجر للحصول على مزيد من المعلومات.
storeCodesExclusion[]

string

اختيارية: رموز المتاجر المطلوب استبعادها للعرض الترويجي لا تنطبق سمات فلاتر المتاجر إلا عند ضبط سمة storeApplicability على specific_stores.
promotionUrl

string

اختيارية: عنوان URL للصفحة على موقع التاجر الإلكتروني التي يظهر عليها العرض الترويجي تؤدي العروض الترويجية لإعلانات المنتجات داخل المتجر إلى ظهور خطأ في حال عدم تضمين promotionUrl. يُستخدَم عنوان URL للتأكّد من أنّ العرض الترويجي صالح ويمكن الاستفادة منه.

ProductApplicability

المنتج أو قائمة المنتجات التي ينطبق عليها العرض الترويجي

عمليات التعداد
PRODUCT_APPLICABILITY_UNSPECIFIED لا نعرف المنتجات التي ينطبق عليها العرض الترويجي.
ALL_PRODUCTS تنطبق على جميع المنتجات.
SPECIFIC_PRODUCTS ينطبق على منتج واحد أو قائمة منتجات فقط.

OfferType

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

عمليات التعداد
OFFER_TYPE_UNSPECIFIED نوع العرض الترويجي غير معروف.
NO_CODE نوع العرض بدون رمز
GENERIC_CODE نوع العرض الترويجي مع رمز يجب إدخال رمز عام لتحصيل قيمة العرض الترويجي عندما يكون offerType = GENERIC_CODE.

CouponValueType

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

عمليات التعداد
COUPON_VALUE_TYPE_UNSPECIFIED يشير إلى أنّ نوع قيمة القسيمة غير محدّد.
MONEY_OFF نوع قيمة القسيمة التي تقدّم خصمًا نقديًا.
PERCENT_OFF نوع قيمة القسيمة التي تقدّم خصمًا بنسبة مئوية.
BUY_M_GET_N_MONEY_OFF نوع قيمة القسيمة: خصم بمقدار n عند شراء m يجب أن يكون minimumPurchaseQuantity وgetThisQuantityDiscounted متوفّرَين. يجب أيضًا أن يكون moneyOffAmount متوفّرًا.
BUY_M_GET_N_PERCENT_OFF شراء كمية M، والحصول على خصم بنسبة N% من نوع قيمة القسيمة يجب أن يكون minimumPurchaseQuantity وgetThisQuantityDiscounted متوفّرَين. يجب أيضًا أن يكون percent_off_percentage متوفّرًا.
BUY_M_GET_MONEY_OFF خصم على السعر عند شراء كمية M. يجب أن يكون الحقلان minimumPurchaseQuantity وmoneyOffAmount متوفّرَين.
BUY_M_GET_PERCENT_OFF خصم على السعر عند شراء كمية M. يجب أن يكون الحقلان minimumPurchaseQuantity وpercent_off_percentage متوفّرَين.
FREE_GIFT هدية مجانية مع الوصف فقط
FREE_GIFT_WITH_VALUE هدية مجانية ذات قيمة مالية
FREE_GIFT_WITH_ITEM_ID هدية مجانية مع معرّف السلعة
FREE_SHIPPING_STANDARD نوع قيمة قسيمة الشحن العادي المجاني لا تتوفّر إلا للعروض الترويجية على الإنترنت.
FREE_SHIPPING_OVERNIGHT نوع قيمة قسيمة الشحن المجاني في اليوم التالي لا تتوفّر إلا للعروض الترويجية على الإنترنت.
FREE_SHIPPING_TWO_DAY نوع قيمة قسيمة الشحن المجاني في غضون يومَين لا تتوفّر إلا للعروض الترويجية على الإنترنت.

DestinationEnum

قيم الوجهة

عمليات التعداد
DESTINATION_ENUM_UNSPECIFIED غير محدّد
SHOPPING_ADS إعلانات Shopping:
DISPLAY_ADS الإعلانات الصورية:
LOCAL_INVENTORY_ADS إعلانات المستودعات الفعليّة المحليّة.
FREE_LISTINGS البيانات المجانية:
FREE_LOCAL_LISTINGS بيانات المنتج المحلية المجانية:
YOUTUBE_SHOPPING التسوّق على YouTube
YOUTUBE_SHOPPING_CHECKOUT الدفع في "التسوّق على YouTube"
YOUTUBE_AFFILIATE الشريك التابع في YouTube
FREE_VEHICLE_LISTINGS بيانات المركبات المجانية:
VEHICLE_ADS إعلانات المركبات:
CLOUD_RETAIL البيع بالتجزئة على السحابة الإلكترونية:
LOCAL_CLOUD_RETAIL البيع بالتجزئة على السحابة الإلكترونية المحلية:

StoreApplicability

رموز المتاجر أو قائمة برموز المتاجر التي ينطبق عليها العرض الترويجي للعروض الترويجية لإعلانات المنتجات داخل المتجر فقط

عمليات التعداد
STORE_APPLICABILITY_UNSPECIFIED رموز المتاجر التي ينطبق عليها العرض الترويجي غير معروفة.
ALL_STORES يسري العرض الترويجي على جميع المتاجر.
SPECIFIC_STORES ينطبق العرض الترويجي على المتاجر المحدّدة فقط.

PromotionStatus

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

تمثيل JSON 
{
  "destinationStatuses": [
    {
      object (DestinationStatus)
    }
  ],
  "itemLevelIssues": [
    {
      object (ItemLevelIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
الحقول
destinationStatuses[]

object (DestinationStatus)

النتائج فقط. الوجهات المقصودة للعرض الترويجي
itemLevelIssues[]

object (ItemLevelIssue)

النتائج فقط. قائمة بالمشاكل المرتبطة بالعرض الترويجي
creationDate

string (Timestamp format)

النتائج فقط. تاريخ إنشاء العرض الترويجي بتنسيق ISO 8601: التاريخ والوقت والفرق الزمني، على سبيل المثال 2020-01-02T09:00:00+01:00 أو 2020-01-02T09:00:00Z
lastUpdateDate

string (Timestamp format)

النتائج فقط. تاريخ آخر تعديل على حالة العرض الترويجي بتنسيق ISO 8601: التاريخ والوقت والفرق الزمني، على سبيل المثال 2020-01-02T09:00:00+01:00 أو 2020-01-02T09:00:00Z

DestinationStatus

حالة الوجهة المحدّدة.

تمثيل JSON 
{
  "reportingContext": enum (ReportingContextEnum),
  "status": enum (State)
}
الحقول
reportingContext

enum (ReportingContextEnum)

النتائج فقط. اسم وجهة العرض الترويجي.
status

enum (State)

النتائج فقط. حالة الوجهة المحدّدة.

الحالة

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

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

ItemLevelIssue

المشكلة المرتبطة بالعرض الترويجي

تمثيل JSON 
{
  "code": string,
  "severity": enum (Severity),
  "resolution": string,
  "attribute": string,
  "reportingContext": enum (ReportingContextEnum),
  "description": string,
  "detail": string,
  "documentation": string,
  "applicableCountries": [
    string
  ]
}
الحقول
code

string

النتائج فقط. رمز الخطأ للمشكلة.
severity

enum (Severity)

النتائج فقط. كيفية تأثير هذه المشكلة في عرض العرض الترويجي
resolution

string

النتائج فقط. ما إذا كان بإمكان التاجر حلّ المشكلة
attribute

string

النتائج فقط. اسم السمة، إذا كانت المشكلة ناتجة عن سمة واحدة
reportingContext

enum (ReportingContextEnum)

النتائج فقط. الوجهة التي تنطبق عليها المشكلة
description

string

النتائج فقط. وصف موجز للمشكلة باللغة الإنجليزية
detail

string

النتائج فقط. وصف تفصيلي للمشكلة باللغة الإنجليزية
documentation

string

النتائج فقط. عنوان URL لصفحة ويب للمساعدة في حلّ هذه المشكلة
applicableCountries[]

string

النتائج فقط. قائمة برموز البلدان (ISO 3166-1 alpha-2) التي تنطبق فيها المشكلة على العرض

درجة الخطورة

درجة خطورة المشكلة

عمليات التعداد
SEVERITY_UNSPECIFIED غير محدّد
NOT_IMPACTED هذه المشكلة هي تحذير ولا تؤثّر بشكل مباشر في العرض الترويجي.
DEMOTED تمّت ترقية العرض الترويجي ومن المرجّح أنّه يحقّق أداءً محدودًا في نتائج البحث.
DISAPPROVED تؤدي المشكلة إلى رفض العرض الترويجي.

الطُرق

get

 استرداد العرض الترويجي من حسابك على Merchant Center

insert

 تُدرج عرضًا ترويجيًا لحسابك على Merchant Center.

list

 تعرض هذه الصفحة العروض الترويجية في حسابك على Merchant Center.