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.
InsertPromotion

rpc InsertPromotion(InsertPromotionRequest) returns (Promotion)

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

نطاقات الأذونات

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

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

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

rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse)

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

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

نطاقات الأذونات

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

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

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

السمات

السمات.

الحقول
product_applicability

ProductApplicability

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

OfferType

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

string

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

string

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

CouponValueType

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

DestinationEnum

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

من المحتمل أنّه سبق أن أرسلت القيم التالية كوجهات لمنتجاتك: Shopping Actions و"منصات Google" و"منصات 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

النتائج فقط. الحدّ الأقصى لعدد العروض الترويجية المطلوب عرضها قد تعرض الخدمة عددًا أقل من هذه القيمة. الحد الأقصى للقيمة هي 1000، وسيتم فرض القيم الأعلى من 1000 على 1000. وفي حال عدم تحديد قيمة هذه السمة، سيتم عرض الحدّ الأقصى لعدد العروض الترويجية.
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 ينطبق العرض الترويجي على المتاجر المحدّدة فقط.