Package google.shopping.merchant.promotions.v1beta

الفهرس

PromotionsService

خدمة لإدارة العروض الترويجية للمنتجات

GetPromotion

rpc GetPromotion(GetPromotionRequest) returns (Promotion)

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

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

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/content

لمزيد من المعلومات، يُرجى الاطّلاع على OAuth 2.0 Overview.
InsertPromotion

rpc InsertPromotion(InsertPromotionRequest) returns (Promotion)

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

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/content

لمزيد من المعلومات، يُرجى الاطّلاع على OAuth 2.0 Overview.
ListPromotions

rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse)

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

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

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/content

لمزيد من المعلومات، يُرجى الاطّلاع على OAuth 2.0 Overview.

السمات

السمات

الحقول
product_applicability

ProductApplicability

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

OfferType

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

string

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

string

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

CouponValueType

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

DestinationEnum

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

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

Price

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

int64

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

int64

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

Price

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

int64

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

Price

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

int64

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

Price

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

string

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

string

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

Interval

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

Interval

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

StoreApplicability

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

string

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

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

string

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

string

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

CouponValueType

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

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

GetPromotionRequest

رسالة طلب لطريقة GetPromotion

الحقول
name

string

مطلوب. اسم العرض الترويجي المطلوب استرجاعه التنسيق: accounts/{account}/promotions/{promotions}

InsertPromotionRequest

رسالة طلب لطريقة InsertPromotion

الحقول
parent

string

مطلوب. الحساب الذي سيتم إدراج العرض الترويجي فيه. التنسيق: accounts/{account}
promotion

Promotion

مطلوب. العرض الترويجي المطلوب إدراجه.
data_source

string

مطلوب. مصدر بيانات العرض الترويجي: accounts/{account}/dataSources/{datasource}.

ListPromotionsRequest

رسالة طلب لطريقة ListPromotions

الحقول
parent

string

مطلوب. الحساب الذي سيتم إدراج العروض الترويجية التي تمت معالجتها له. التنسيق: accounts/{account}
page_size

int32

النتائج فقط. الحد الأقصى لعدد العروض الترويجية التي سيتم عرضها قد تعرض الخدمة عددًا أقل من هذه القيمة. الحد الأقصى للقيمة هو 250، وسيتم تحويل القيم التي تزيد عن 250 إلى 250. إذا لم يتم تحديدها، سيتم عرض الحد الأقصى لعدد العروض الترويجية.
page_token

string

النتائج فقط. رمز مميّز للصفحة، تم تلقّيه من مكالمة ListPromotions سابقة قدِّم هذا المرجع لاسترداد الصفحة اللاحقة.

عند تقسيم الصفحات، يجب أن تتطابق جميع المَعلمات الأخرى المقدَّمة إلى ListPromotions مع الطلب الذي قدّم الرمز المميّز للصفحة.

ListPromotionsResponse

رسالة الردّ على طريقة ListPromotions

الحقول
promotions[]

Promotion

العروض الترويجية التي تمت معالجتها من الحساب المحدّد
next_page_token

string

رمز مميّز يمكن إرساله على شكل page_token لاسترداد الصفحة التالية. في حال حذف هذا الحقل، لن تكون هناك صفحات لاحقة.

OfferType

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

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

ProductApplicability

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

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

عرض ترويجي

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

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

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

الحقول
name

string

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

string

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

string

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

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

string

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

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

RedemptionChannel

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

string

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

Attributes

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

CustomAttribute

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

PromotionStatus

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

int64

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

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

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

PromotionStatus

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

الحقول
destination_statuses[]

DestinationStatus

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

ItemLevelIssue

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

Timestamp

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

Timestamp

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

DestinationStatus

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

الحقول
reporting_context

ReportingContextEnum

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

State

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

الحالة

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

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

ItemLevelIssue

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

الحقول
code

string

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

Severity

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

string

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

string

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

ReportingContextEnum

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

string

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

string

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

string

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

string

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

درجة الخطورة

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

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

RedemptionChannel

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

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

StoreApplicability

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

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