دمج خلاصة العروض

العروض

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

أمثلة على العروض:

• خصم %50 على المقبّلات أيام الأربعاء والخميس في ديسمبر من الساعة 12 ظهرًا حتى 5 مساءً
• احصل على حلوى مجانية عند شراء حلوى أخرى في عشاء عيد الأم من الساعة 6 مساءً إلى الساعة 10 مساءً
• خصم 5 دولارات أمريكية على وجبة فطور وغداء كل يوم أحد من الساعة 10 صباحًا حتى الساعة 2 ظهرًا
• خصم% 10 عند الحجز بدون موعد، ويمكن دمجه مع خصم% 5 للمشتركين في الخطة المميزة وخصم% 5 إذا دفع المستخدم من خلال تطبيقك

ملاحظة: يجب أن تتم الإشارة إلى كل عرض ترويجي باستخدام معرّف فريد. بعد تعيين معرّف للعرض، لا يمكن تغيير العرض. في حال تغيّر العرض، يجب تعيين معرّف فريد جديد له ويمكن إزالة العرض القديم.

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

تنفيذ العروض

يتكوّن دمج العروض من خلاصتَين سيتم تحميلهما يوميًا أو بمعدّل يضمن دقة عالية (أي يقلّل من عدم دقة البيانات):

• إما:
  • خلاصة التجّار (باستخدام إعدادات Merchant)
  • أو خلاصة الكيانات (باستخدام إعدادات Generic)
• و خلاصة العروض (باستخدام إعدادات Generic)

OfferFeed

اسم الحقل	النوع	المتطلبات	الوصف
data	مصفوفة من العناصر (Offer)

عرض

اسم الحقل	النوع	المتطلبات	الوصف
offer_id	سلسلة	مطلوب	المعرّف الفريد للعرض الحقل مطلوب.
entity_ids	مصفوفة سلاسل		قائمة بالتجّار المشاركين في هذا العرض
add_on_offer_applicable_to_all_entities	قيمة منطقية		إذا كانت القيمة صحيحة، ينطبق هذا العرض على جميع الكيانات التابعة لخدمة التجميع. تنطبق هذه السمة على عروض الإضافات فقط.
offer_source	enum (OfferSource)	مطلوب	يمكن أن يقدّم العرض مجمّع أو تاجر فردي أو حتى طرف ثالث كإضافة. الحقل مطلوب.
action_type	enum (ActionType)	مطلوب	الخدمة التي تقدّم العرض يمكن أن ينتمي offer_id إلى action_type واحد فقط. إذا كان من الممكن مشاركة عرض ترويجي واحد في أنواع خدمات متعددة، من المتوقّع إنشاء عروض ترويجية مكرّرة بمعرّفات فريدة لكل نوع خدمة. الحقل مطلوب.
offer_modes	مصفوفة من enum (OfferMode)	مطلوب	طُرق الاستفادة من العرض، مثل الحضور إلى المكان أو الحجز أو الاستفادة من العرض على الإنترنت وما إلى ذلك. مطلوب.
offer_category	enum (OfferCategory)	مطلوب	فئة العرض الحقل مطلوب.
source_assigned_priority	الرقم		عدد صحيح غير سالب ([1-100]، حيث يمثّل الرقم 1 الأولوية القصوى) يشير إلى مستوى أولوية العرض الذي حدّده المصدر. عندما تتوفّر عروض متعدّدة للتاجر نفسه، ستكون هذه إشارة لترتيب العروض. وتمثّل القيمة 0 عدم ضبط الأولوية.
offer_details	object (OfferDetails)	مطلوب	تفاصيل العرض، مثل الخصم وتكلفة الحجز وما إلى ذلك (مطلوبة)
offer_restrictions	object (OfferRestrictions)	مطلوب	تصف هذه السمة القيود المفروضة على العرض، أي ما إذا كان يتطلب اشتراكًا أو وسيلة دفع، وما إذا كان يمكن الجمع بينه وبين عروض أخرى (وما هي أنواعها)، وما إلى ذلك. هذه السمة مطلوبة.
coupon	الكائن (Coupon)		تعرض هذه السمة تفاصيل قسيمة. مطلوب لفئة العرض: OFFER_CATEGORY_ADD_ON_COUPON_OFFER.
payment_instrument	object (PaymentInstrument)		تفاصيل وسيلة الدفع مطلوب لقيمة offer_category: OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER.
subscription	object (Subscription)		تعرض هذه السمة تفاصيل الاشتراك. مطلوبة لسمة offer_category: OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER.
terms	object (Terms)	مطلوب	تمثّل هذه السمة أحكام العرض وشروطه. الحقل مطلوب.
validity_periods	مصفوفة من العناصر (ValidityPeriod)	مطلوب	تمثّل هذه السمة مدة صلاحية العرض. تصف هذه السمة الفترة الزمنية التي يكون العرض صالحًا خلالها، بما في ذلك أوقات البدء والانتهاء وأيام الأسبوع وما إلى ذلك. وهي مطلوبة.
offer_url	سلسلة		عنوان URL لصفحة العرض الترويجي الخاص بالتاجر مطلوبة لـ offer_category: OFFER_CATEGORY_BASE_OFFER.
tags	مصفوفة من التعداد (OfferTag)		علامات خاصة مرتبطة بالعرض يُستخدم هذا الحقل لتحديد العروض الخاصة، مثل "موسم الأعياد" و"الأكثر تقييمًا" و"الأكثر حجزًا" وما إلى ذلك.
brand_id	سلسلة		تحدّد هذه السمة العلامة التجارية المرتبطة بالعرض. وفي حال ترك هذه السياسة بدون ضبط، يتم استخدام العلامة التجارية التلقائية.
availability_level	enum (AvailabilityLevel)		مستوى توفّر العرض

OfferDetails

اسم الحقل	النوع	المتطلبات	الوصف
offer_display_text	سلسلة	مطلوب	نص العرض الذي يريد مقدّم العرض الترويجي عرضه للعملاء على صفحة نتائج البحث يُرجى العِلم أنّ هذا قد لا يكون بالضبط ما يظهر للمستخدمين، وقد نستخدم بيانات وصفية أخرى لإعادة كتابته أو إعادة صياغته. الحقل مطلوب.
	oneOf (offer_specification)	مطلوب	يمكن ضبط حقل واحد فقط من الحقول الواردة في oneOf.
max_discount_value	الكائن (Money)		الحدّ الأقصى للخصم الذي يمكن الاستفادة منه على سبيل المثال، خصم% 10 يصل إلى 100 دولار أمريكي.
min_spend_value	object (Money)		تمثّل هذه السمة الحدّ الأدنى للإنفاق للاستفادة من الخصم. على سبيل المثال، خصم% 10 عندما يكون السعر الإجمالي 100 ريال سعودي أو أكثر.
booking_cost	الكائن (Money)		تكلفة حجز هذا العرض على سبيل المثال، خصم 100 دولار أمريكي من الفاتورة النهائية عند حجز طاولة مقابل 15 دولارًا أمريكيًا.
booking_cost_unit	enum (FeeUnit)		تمثّل هذه السمة وحدة تكلفة الحجز. على سبيل المثال، لكل شخص، لكل معاملة.
convenience_fee	object (Fee)
booking_cost_adjustable	قيمة منطقية		تُستخدَم لتحديد ما إذا كانت تكلفة الحجز قابلة للتعديل، أي ما إذا كانت تكلفة الحجز تُطرح من الفاتورة النهائية. على سبيل المثال: خصم% 30 على العشاء عند الحجز تبلغ تكلفة الحجز 15 دولارًا أمريكيًا، وسيتم تطبيقها على الفاتورة النهائية. وبالتالي، تكون الفاتورة النهائية: إجمالي الإنفاق - %30 - ‏15 دولار أمريكي
additional_fees	مصفوفة من العناصر (AdditionalFee)		الرسوم الإضافية التي يتم تحصيلها من المستخدم أمثلة: رسوم الراحة والمناولة والتسليم والتعبئة والخدمة وما إلى ذلك
offer_discount_type	enum (OfferDiscountType)		نوع الخصم
gift_card_info	الكائن (GiftCardInfo)		تفاصيل خاصة بصفقات بطاقات الهدايا

المال

تمثّل هذه السمة مبلغًا من المال مع نوع العملة.

اسم الحقل	النوع	المتطلبات	الوصف
currency_code	سلسلة		رمز العملة المكوّن من ثلاثة أحرف والمحدّد في ISO 4217.
units	الرقم		الوحدات الكاملة للمبلغ على سبيل المثال، إذا كانت قيمة currencyCode هي "USD"، تكون الوحدة الواحدة دولارًا أمريكيًا واحدًا.
nanos	الرقم		عدد وحدات النانو (10^-9) من المبلغ. يجب أن تتراوح القيمة بين ‎-999,999,999 و‎+999,999,999، بما في ذلك طرفي النطاق. إذا كانت قيمة units موجبة، يجب أن تكون قيمة nanos موجبة أو صفرًا. إذا كانت قيمة units صفرًا، يمكن أن تكون قيمة nanos موجبة أو صفرًا أو سالبة. إذا كانت قيمة units سالبة، يجب أن تكون قيمة nanos سالبة أو صفرًا. على سبيل المثال، يتم تمثيل ‎ $-1.75 على النحو التالي: units=-1 وnanos=-750,000,000.

رسوم

اسم الحقل	النوع	المتطلبات	الوصف
unit	enum (FeeUnit)
type	enum (FeeType)
	oneOf (cost)		يمكن ضبط حقل واحد فقط من الحقول في هذا الحقل.

MoneyRange

اسم الحقل	النوع	المتطلبات	الوصف
min_amount	object (Money)
max_amount	الكائن (Money)

AdditionalFee

اسم الحقل	النوع	المتطلبات	الوصف
name	سلسلة	مطلوب	اسم الرسوم الإضافية أمثلة: رسم خدمة إضافي، رسم مناولة، وما إلى ذلك هذا الحقل مطلوب.
fee	object (Fee)

GiftCardInfo

اسم الحقل	النوع	المتطلبات	الوصف
	oneOf (denomination_type)		يمكن ضبط حقل واحد فقط من الحقول في هذا الحقل.

FixedDenominations

اسم الحقل	النوع	المتطلبات	الوصف
amounts	مصفوفة من العناصر (Money)		قائمة بجميع الفئات المنفصلة المتاحة (مثل [100, 500, 1000]).

OfferRestrictions

اسم الحقل	النوع	المتطلبات	الوصف
combinable_with_other_offers	قيمة منطقية		تُستخدَم لتحديد ما إذا كان يمكن الجمع بين هذا العرض وعروض أخرى. عند ضبط هذه السمة على "صحيح"، يمكن للشركاء تحديد العروض التي يمكن دمج هذا العرض معها. في حال ضبط كل من combinable_offer_categories وcombinable_offer_ids، سيكون أي عرض يطابق أحد الشروط أعلاه قابلاً للدمج.
combinable_offer_categories	مصفوفة من التعداد (OfferCategory)		قائمة بأنواع العروض التي يمكن الجمع بينها وبين هذا العرض على سبيل المثال، قد يكون هذا العرض قابلاً للجمع مع قسائم أخرى. إذا كانت قيمة combinable_with_other_offers هي "صحيح" ولم يتم ضبط هذا الحقل، ستكون جميع الأنواع قابلة للدمج.
combinable_offer_ids	مصفوفة من السلاسل		قائمة بمعرّفات العروض التي يمكن الجمع بينها وبين هذا العرض قد لا يمكن الجمع بين بعض العروض إلا مع معرّفات عروض ترويجية أخرى معيّنة (يمكن اعتبارها عروضًا رئيسية). إذا كانت قيمة combinable_with_other_offers هي "صحيح" ولم يتم ضبط هذا الحقل، يمكن الجمع بين جميع معرّفات العروض الترويجية.
inclusions	مصفوفة من العناصر (OfferCondition)		قائمة بالشروط التي يجب استيفاؤها ليكون العرض صالحًا (مثل المشروبات غير الكحولية والطعام).
exclusions	مصفوفة من العناصر (OfferCondition)		قائمة بالشروط التي من شأنها إبطال العرض (مثل البوفيه والعروض المجمّعة والكوكتيلات).
min_guest	الرقم		الحدّ الأدنى لعدد الأشخاص المطلوب للاستفادة من العرض ملاحظة: ينطبق هذا الحقل على حجوزات المطاعم فقط، ولا يجب استخدامه في مجالات أخرى.
food_offer_restrictions	object (FoodOfferRestrictions)		القيود الخاصة بعروض الطعام
max_redemption_count	الرقم		القيود المتعلّقة بعدد المرات التي يمكن فيها استخدام هذا العرض وتعني القيمة 0 عدم وجود حدود. على سبيل المثال، إذا كانت القيمة 3، يعني ذلك أنّه يمكن للمستخدم الاستفادة من هذا العرض 3 مرات.
max_total_discount_value	object (Money)		تمثّل هذه السمة الحد الأقصى للخصم الذي يمكن الاستفادة منه في عدّة معاملات ضمن هذا العرض.
special_conditions	مصفوفة من السلاسل		تمثّل هذه السمة الشروط الخاصة لهذا العرض التي يجب عرضها للمستخدم. أمثلة: "صالحة للدفع في [المنطقة] فقط"، "لا تشمل الدفعات على الإنترنت"، "يمكن استخدام قسيمة الهدايا خلال فترة التخفيضات".

OfferCondition

اسم الحقل	النوع	المتطلبات	الوصف
description	سلسلة

FoodOfferRestrictions

اسم الحقل	النوع	المتطلبات	الوصف
meal_types	مصفوفة من التعداد (MealType)		أنواع الوجبات التي يمكن تطبيق العرض عليها، مثل الغداء أو العشاء في حال عدم ضبطها، يمكن تطبيق العرض على جميع أنواع الوجبات.
restricted_to_certain_courses	قيمة منطقية		تُستخدَم لتحديد ما إذا كان يمكن تطبيق العرض على دورات تدريبية معيّنة فقط.

القسيمة

اسم الحقل	النوع	المتطلبات	الوصف
text	سلسلة		نص القسيمة الذي يريد مقدّم العرض عرضه للمستخدمين.
code	سلسلة	مطلوب	رمز القسيمة مطلوب للاستفادة من العرض. الحقل مطلوب.

PaymentInstrument

اسم الحقل	النوع	المتطلبات	الوصف
items	مصفوفة من العناصر (PaymentInstrumentItem)	مطلوب	قائمة بوسائل الدفع التي يمكن استخدامها للاستفادة من العرض الحقل مطلوب.
provider_name	سلسلة		اسم مقدّم وسيلة الدفع يمكن أن يكون شريكًا مصرفيًا أو اسم مصرف أو غير ذلك، مثل American Express أو HDFC أو ICICI.

PaymentInstrumentItem

اسم الحقل	النوع	المتطلبات	الوصف
type	enum (PaymentInstrumentType)	مطلوب	نوع وسيلة الدفع الحقل مطلوب.
name	سلسلة	مطلوب	اسم وسيلة الدفع، مثل اسم بطاقة الائتمان على سبيل المثال: HDFC Infinia وAmerican Express Platinum. الحقل مطلوب.

تاريخ التوفّر للمشتركين

اسم الحقل	النوع	المتطلبات	الوصف
name	سلسلة	مطلوب	اسم الاشتراك الحقل مطلوب.
subscription_auto_added	قيمة منطقية		ما إذا كان الاشتراك يُضاف تلقائيًا عندما يستفيد المستخدم من هذا العرض
cost	الكائن (Money)	مطلوب	تكلفة الاشتراك الحقل مطلوب.
subscription_duration	object (Duration)	مطلوب	مدة صلاحية الاشتراك وفقًا لسمة "تكلفة الاشتراك" (subscription_cost) الحقل مطلوب.
terms_and_conditions_url	سلسلة		عنوان URL المؤدي إلى أحكام وشروط الشريك ذات الصلة بهذا الاشتراك

المدة

اسم الحقل	النوع	المتطلبات	الوصف
seconds	الرقم		الثواني الموقَّعة للفترة الزمنية يجب أن تتراوح القيمة بين -315,576,000,000 و+315,576,000,000، بما في ذلك طرفي النطاق. ملاحظة: يتم احتساب هذه الحدود من خلال: 60 ثانية/دقيقة * 60 دقيقة/ساعة * 24 ساعة/يوم * 365.25 يوم/سنة * 10000 سنة
nanos	الرقم		تشير هذه السمة إلى أجزاء الثانية الموقَّعة بدقة النانو ثانية للفترة الزمنية. يتم تمثيل المدد الزمنية الأقل من ثانية واحدة باستخدام الحقل 0 seconds والحقل nanos الموجب أو السالب. بالنسبة إلى المدد التي تبلغ ثانية واحدة أو أكثر، يجب أن تكون قيمة الحقل nanos غير صفرية وأن تحمل الإشارة نفسها التي يحملها الحقل seconds. يجب أن تتراوح القيمة بين -999,999,999 و+999,999,999، بما في ذلك طرفي النطاق.

البنود

اسم الحقل	النوع	المتطلبات	الوصف
url	سلسلة		عنوان URL الخاص بالأحكام والشروط لدى الشريك
restricted_to_certain_users	قيمة منطقية		ما إذا كان العرض مقتصرًا على مستخدمين معيّنين
terms_and_conditions	سلسلة		نص الأحكام والشروط الأساسية الذي يقدّمه الشريك
additional_terms_and_conditions	مصفوفة السلاسل النصية		الأحكام والشروط بالإضافة إلى الأحكام والشروط الأساسية من الشريك

ValidityPeriod

اسم الحقل	النوع	المتطلبات	الوصف
valid_period	object (ValidityRange)		الطابع الزمني للبدء والانتهاء الذي يكون العرض صالحًا خلاله. يجب أن تمثّل هذه الأوقات أيامًا مختلفة، أي يجب أن يكون وقت البدء 00:00 (بداية اليوم) ووقت الانتهاء 00:00 (غير شامل) في اليوم الذي تنتهي فيه مدة الصلاحية.
time_of_day	مصفوفة من العناصر (TimeOfDayWindow)		تحدّد هذه السمة الفاصل الزمني الصالح في يوم معيّن والأيام التي يتوفّر فيها العرض. بالنسبة إلى الأُطر الزمنية التي تتجاوز منتصف الليل (مثلاً، من 10 مساءً إلى 2 صباحًا)، استخدِم نوافذ منفصلة لكل يوم: واحدة تنتهي في الساعة 11:59:59 مساءً وأخرى تبدأ في الساعة 12:00 صباحًا في اليوم التالي. على سبيل المثال: الاثنين: من الساعة 10 صباحًا إلى الساعة 5 مساءً الثلاثاء: من الساعة 10 صباحًا إلى الساعة 2 ظهرًا الثلاثاء: من الساعة 5 مساءً إلى الساعة 7 مساءً الأربعاء والخميس والجمعة والسبت والأحد: من الساعة 3 مساءً إلى الساعة 7 مساءً إذا لم يتم ضبط أي وقت، يعني ذلك أنّ العرض الترويجي متاح في كل الأوقات ضمن valid_period.
time_exceptions	مصفوفة من العناصر (ValidTimeException)		تحدّد هذه السمة الاستثناءات لسمتَي valid_period وvalid_time_of_week أعلاه
date_exceptions	مصفوفة من العناصر (Date)		يحدّد هذا الإعداد الاستثناءات بالأيام لـ valid_period وtime_of_day المذكورَين أعلاه
validity_scope	enum (ValidityScope)		تحدّد هذه السمة نطاق مدة الصلاحية.
validity_duration_in_days	الرقم		تمثّل هذه السمة المدة (بالأيام) التي يكون فيها القسيمة أو الكوبون صالحًا بعد شرائه.

ValidityRange

نطاق طابع زمني مغلق-مفتوح.

اسم الحقل	النوع	المتطلبات	الوصف
valid_from_time	object (Timestamp)	مطلوب	تمثّل هذه السمة وقت بدء النطاق (شامل). الحقل مطلوب.
valid_through_time	object (Timestamp)		وقت انتهاء النطاق (غير مشمول). في حال عدم ضبطها، يعني ذلك أنّ هذه الفترة لا تنتهي أبدًا. اختيارية:

الطابع الزمني

اسم الحقل	النوع	المتطلبات	الوصف
seconds	الرقم		تشير هذه السمة إلى عدد ثواني التوقيت العالمي المنسق (UTC) المنقضية منذ بداية حقبة يونكس 1970-01-01T00:00:00Z. يجب أن تتراوح القيمة بين -62135596800 و253402300799، بما في ذلك طرفي النطاق (وهو ما يتوافق مع النطاق من 0001-01-01T00:00:00Z إلى 9999-12-31T23:59:59Z).
nanos	الرقم		تشير هذه السمة إلى أجزاء الثانية غير السالبة بدقة النانو ثانية هذا الحقل هو جزء النانو ثانية من المدة، وليس بديلاً للثواني. يجب أن تظل قيم الثواني السالبة التي تحتوي على كسور تحتوي على قيم نانو ثانية غير سالبة يتم احتسابها للأمام في الوقت المناسب. يجب أن تتراوح القيمة بين 0 و999,999,999، بما في ذلك طرفي النطاق.

TimeOfDayWindow

عنصر TimeWindow هو كيان مركّب يصف قائمة بالنوافذ التي يمكن فيها إما تقديم طلب المستخدم أو تنفيذه.

اسم الحقل	النوع	المتطلبات	الوصف
time_windows	object (TimeOfDayRange)	مطلوب	يشير هذا الحقل إلى الفترة الزمنية التي يمكن خلالها تقديم الطلب أو تنفيذه. الحقل مطلوب.
day_of_week	مصفوفة من التعداد (DayOfWeek)		قائمة أيام الأسبوع التي يتم تطبيق الفترات الزمنية فيها وفي حال عدم ضبط أي قيمة، يعني ذلك أنّ السياسة تنطبق على جميع أيام الأسبوع. اختيارية:
day_of_month	مصفوفة من العناصر (DayOfMonthRange)		الأيام في الشهر التي يتم فيها تطبيق النوافذ. وفي حال عدم ضبط أي قيمة، يعني ذلك أنّ السياسة ستسري على جميع أيام الشهر. اختيارية:

TimeOfDayRange

نطاق زمني مغلق ومفتوح

اسم الحقل	النوع	المتطلبات	الوصف
open_time	object (TimeOfDay)		تمثّل هذه السمة وقتًا يشير إلى وقت بدء اليوم في النطاق (شامل). إذا لم يتم ضبطها، يعني ذلك 00:00:00. اختيارية:
close_time	الكائن (TimeOfDay)		تمثّل هذه السمة وقتًا يشير إلى وقت انتهاء اليوم في النطاق (غير شامل). في حال عدم ضبط القيمة، يعني ذلك 23:59:59. اختيارية:

TimeOfDay

اسم الحقل	النوع	المتطلبات	الوصف
hours	الرقم		ساعات اليوم بتنسيق 24 ساعة يجب أن تكون القيمة أكبر من أو تساوي 0 وأقل من أو تساوي 23 عادةً. قد تختار واجهة برمجة التطبيقات السماح بالقيمة "24:00:00" لسيناريوهات مثل وقت إغلاق النشاط التجاري.
minutes	الرقم		الدقائق في الساعة يجب أن تكون القيمة أكبر من أو تساوي 0 وأقل من أو تساوي 59.
seconds	الرقم		ثوانٍ من الدقيقة يجب أن تكون القيمة أكبر من أو تساوي 0، ويجب عادةً أن تكون أقل من أو تساوي 59. قد يسمح أحد واجهات برمجة التطبيقات بالقيمة 60 إذا كان يسمح بالثواني الكبيسة.
nanos	الرقم		أجزاء من الثانية، بالنانو ثانية يجب أن تكون القيمة أكبر من أو تساوي 0 وأقل من أو تساوي 999,999,999.

DayOfMonthRange

نطاق من أيام الشهر ينطبق على جميع أشهر السنة

اسم الحقل	النوع	المتطلبات	الوصف
valid_from_day	الرقم	مطلوب	تمثّل هذه السمة يوم بداية النطاق (شامل). الحقل مطلوب.
valid_through_day	الرقم		يوم انتهاء النطاق (شامل). في حال عدم ضبط هذه السمة، يعني ذلك أنّ هذا النطاق يمثّل يومًا واحدًا (valid_from_day). اختيارية:

ValidTimeException

اسم الحقل	النوع	المتطلبات	الوصف
exceptional_period	object (ValidityRange)		الطابع الزمني للبدء والانتهاء الذي لا يكون العرض صالحًا خلاله. يجب أن تمثّل هذه الأوقات أيامًا مختلفة، أي يجب أن يكون وقت البدء هو 00:00 (بداية اليوم) ووقت الانتهاء هو 00:00 (باستثناء) في اليوم الذي تنتهي فيه فترة الاستثناء.

التاريخ

اسم الحقل	النوع	المتطلبات	الوصف
year	الرقم		تمثّل هذه السمة العام الذي يقع فيه التاريخ. يجب أن تتراوح القيمة بين 1 و9999، أو أن تكون 0 لتحديد تاريخ بدون سنة.
month	الرقم		شهر من السنة يجب أن تكون القيمة من 1 إلى 12، أو 0 لتحديد سنة بدون شهر ويوم.
day	الرقم		اليوم من الشهر يجب أن تكون القيمة من 1 إلى 31 وصالحة للسنة والشهر، أو 0 لتحديد سنة بمفردها أو سنة وشهر حيث لا يكون اليوم مهمًا.

OfferSource

الاسم	الوصف
OFFER_SOURCE_UNSPECIFIED
OFFER_SOURCE_AGGREGATOR

ActionType

تمثّل هذه السمة طريقة الاستفادة من العرض. إذا كان من الممكن مشاركة عرض واحد عبر أوضاع تنفيذ متعددة، من المتوقع إنشاء عروض مكررة لكل وضع تنفيذ.

الاسم	الوصف
ACTION_TYPE_UNSPECIFIED
ACTION_TYPE_FOOD_DELIVERY	يسري العرض على خدمات توصيل الطعام.
ACTION_TYPE_FOOD_TAKEOUT	يسري العرض على طلبات استلام الطعام أو أخذه معك.
ACTION_TYPE_DINING	العرض مخصّص لتناول الطعام في المطعم.
ACTION_TYPE_APPOINTMENT	يسري العرض على خدمات حجز المواعيد.
ACTION_TYPE_SHOPPING_IN_STORE	يسري العرض على عمليات الشراء في المتاجر.

OfferMode

تحدّد هذه السمة الطريقة أو القناة التي يمكن للمستخدم الاستفادة من العرض الترويجي من خلالها.

الاسم	الوصف
OFFER_MODE_OTHER	يُستخدَم لطرق التنفيذ التي لا تغطيها الأوضاع المحدّدة الأخرى.
OFFER_MODE_WALK_IN	يتوفّر العرض للزيارات في الموقع بدون حجز مسبق.
OFFER_MODE_FREE_RESERVATION	ينطبق العرض الترويجي عندما يجري المستخدم حجزًا لا يتطلّب دفع رسوم مقدّمًا.
OFFER_MODE_PAID_RESERVATION	يسري العرض الترويجي عندما يجري المستخدم حجزًا يتطلّب دفع مبلغ مقدّم.
OFFER_MODE_ONLINE_ORDER	يسري العرض على الطلبات المقدَّمة من خلال موقع إلكتروني أو منصة رقمية.
OFFER_MODE_GIFT_CARD_PURCHASE	يشير إلى أنّ شراء بطاقة هدايا هو الخطوة الأساسية المطلوبة للحصول على الصفقة.

OfferCategory

فئة العرض العرض الأساسي هو عرض عادي متاح لجميع العملاء، مثل خصم% 10 على الإنفاق الذي يزيد عن 100 دولار أمريكي. سيتم ضبط الحقول ذات الصلة للعرض الأساسي المقيّد بقسيمة أو وسيلة دفع. لدينا أيضًا عروض إضافية على x، مثل ADD_ON_PAYMENT_OFFER. ويمكن إضافة هذه العروض إلى عروض أخرى للحصول على خصومات إضافية.

الاسم	الوصف
OFFER_CATEGORY_UNSPECIFIED	يجب عدم استخدام قيمة التعداد التلقائية أو UNSPECIFIED في الخلاصات.
OFFER_CATEGORY_BASE_OFFER
OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER
OFFER_CATEGORY_ADD_ON_COUPON_OFFER
OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER
OFFER_CATEGORY_ADD_ON_FEE_REDUCTION_OFFER

FeeUnit

الاسم	الوصف
FEE_UNIT_UNSPECIFIED	يجب عدم استخدام قيمة التعداد UNSPECIFIED أو القيمة التلقائية في الخلاصات.
FEE_UNIT_PER_GUEST
FEE_UNIT_PER_TRANSACTION

FeeType

الاسم	الوصف
FEE_TYPE_UNSPECIFIED	يجب عدم استخدام قيمة التعداد التلقائية أو UNSPECIFIED في الخلاصات.
FEE_TYPE_FIXED
FEE_TYPE_VARIABLE

OfferDiscountType

الاسم	الوصف
OFFER_DISCOUNT_TYPE_UNSPECIFIED
OFFER_DISCOUNT_TYPE_INSTANT_DISCOUNT
OFFER_DISCOUNT_TYPE_CASHBACK
OFFER_DISCOUNT_TYPE_REWARD_POINT

MealType

الاسم	الوصف
MEAL_TYPE_UNSPECIFIED	يجب عدم استخدام القيمة التعدادية UNSPECIFIED أو القيمة التلقائية في الخلاصات.
MEAL_TYPE_BREAKFAST
MEAL_TYPE_LUNCH
MEAL_TYPE_DINNER

PaymentInstrumentType

الاسم	الوصف
PAYMENT_INSTRUMENT_TYPE_UNSPECIFIED	يجب عدم استخدام قيمة التعداد UNSPECIFIED أو القيمة التلقائية في الخلاصات.
PAYMENT_INSTRUMENT_CREDIT_CARD
PAYMENT_INSTRUMENT_DEBIT_CARD
PAYMENT_INSTRUMENT_BANK_ACCOUNT
PAYMENT_INSTRUMENT_UPI
PAYMENT_INSTRUMENT_ONLINE_WALLET
PAYMENT_INSTRUMENT_NETBANKING

DayOfWeek

تمثّل يومًا من أيام الأسبوع.

الاسم	الوصف
DAY_OF_WEEK_UNSPECIFIED	يوم الأسبوع غير محدّد.
MONDAY	الاثنين
TUESDAY	الثلاثاء
WEDNESDAY	الأربعاء
THURSDAY	الخميس
FRIDAY	الجمعة
SATURDAY	السبت
SUNDAY	الأحد

ValidityScope

نطاق مدة الصلاحية، أي الإجراءات التي تنطبق عليها مدة الصلاحية هذه بالضبط

الاسم	الوصف
VALIDITY_SCOPE_UNSPECIFIED
VALIDITY_SCOPE_CLAIM
VALIDITY_SCOPE_REDEEM

OfferTag

الاسم	الوصف
OFFER_TAG_UNSPECIFIED	يجب عدم استخدام قيمة التعداد التلقائية أو UNSPECIFIED في الخلاصات.
OFFER_TAG_NEW_YEAR_SPECIAL
OFFER_TAG_VALENTINES_SPECIAL

AvailabilityLevel

يشير إلى حالة المخزون أو مدى توفّر عرض معيّن.

الاسم	الوصف
AVAILABILITY_LEVEL_UNSPECIFIED
AVAILABILITY_LEVEL_LOW	يشير إلى أنّ العرض الترويجي أوشك على النفاد. ويُنصح المستخدمون بتحصيل قيمتها قبل نفاد المخزون. قد نضيف المستويَين "متوسط" و"مرتفع" لاحقًا.

offer_specification

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

اسم الحقل	النوع	المتطلبات	الوصف
discount_percent	الرقم	لا يمكن استخدامها مع discount_value وother_offer_detail_text	النسبة المئوية للخصم من الفاتورة [0, 100] بالنسبة إلى عروض "اشترِ وجبة واحصل على الثانية مجانًا" أو عروض الخصم بنسبة% 50 التي تنطبق على الوجبة بأكملها (مثل بوفيه "اشترِ وجبة واحصل على الثانية مجانًا"، أو عرض "اشترِ وجبة واحصل على الثانية مجانًا" على الفاتورة بأكملها، أو عرض "اشترِ وجبة واحصل على الثانية مجانًا" على قائمة طعام محدّدة)، يمكن ضبط هذه القيمة على 50.
discount_value	الكائن (Money)	لا يمكن استخدامها مع discount_percent أو other_offer_detail_text	القيمة الثابتة للخصم
other_offer_detail_text	سلسلة	لا يمكن استخدامها مع discount_percent وdiscount_value	نص بأسلوب حر لوصف الخصم بالنسبة إلى عروض "اشترِ قطعة واحصل على قطعة إضافية" المحدّدة (مثل مشروبان بسعر مشروب واحد، أو طبق رئيسي إضافي، أو عناصر محدّدة من القائمة)، يجب توضيح هذه التفاصيل هنا.

التكلفة

اسم الحقل	النوع	المتطلبات	الوصف
amount	object (Money)	لا يمكن استخدامها مع amount_range
amount_range	object (MoneyRange)	لا يمكن استخدامها مع amount

denomination_type

اسم الحقل	النوع	المتطلبات	الوصف
fixed_denominations	object (FixedDenominations)	متنافٍ مع custom_range	يتم استخدامها عندما تكون بطاقة الهدايا متاحة بمبالغ ثابتة ومحدّدة.
custom_range	الكائن (MoneyRange)	لا يمكن استخدامها مع fixed_denominations	يُستخدَم هذا الحقل عندما تسمح العلامة التجارية للمستخدمين باختيار قيمة اسمية مخصّصة (مرنة) ضمن نطاق محدّد.

تحميل الخلاصة

يجب تحميل خلاصة العروض إلى خادم بروتوكول النقل الآمن للملفات (SFTP) الخاص بخلاصة Generic. اتّبِع البرنامج التعليمي حول كيفية استخدام خادم بروتوكول النقل الآمن للملفات (SFTP) الخاص بالخلاصة العامة للحصول على التعليمات واستخدِم السمة name التي تم ضبطها على google.offer في ملف الوصف.

معدل التحميل

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

سيستغرق ظهور البيانات على Google بضع ساعات.

ملاحظة: إذا حمّلت أكثر من خلاصة واحدة بين عمليتَي تشغيل لمسار التحقّق من الصحة (كل ساعتين تقريبًا)، سيتم التحقّق من صحة الخلاصة الأخيرة فقط وستبقى الخلاصات الأخرى في الحالة Processing.

تصنيف العروض

• ‫OFFER_CATEGORY_BASE_OFFER: عروض يمكن الاستفادة منها بشكل مستقل بدون الجمع بينها وبين أي عرض آخر. يشمل ذلك ما يلي:
  • خصومات ثابتة على الفاتورة بالكامل (مثلاً، خصم% 20)
  • عروض الاشتراك (مثل الحصول على حلوى مجانية عند الاشتراك)
  • عروض الدفع في الحالات التي لا تتوفّر فيها عروض أساسية أخرى للمطعم
  • ملاحظة: يجب عدم ضبط عروض الإعفاء من الرسوم أو تخفيضها على مستوى المنصة كعروض أساسية.
• العروض الإضافية: هي عروض تتطلّب الاستفادة من عرض أساسي. وتشمل هذه السياسات ما يلي:
  • OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER (مثلاً، خصم إضافي بنسبة% 10 عند استخدام بطاقة ائتمان معيّنة)
  • OFFER_CATEGORY_ADD_ON_COUPON_OFFER (مثلاً، مشروب مجاني مع رمز قسيمة محدّد)
  • OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER (مثلاً، خصم إضافي بنسبة% 10 للمشتركين)
  • OFFER_CATEGORY_ADD_ON_FEE_REDUCTION_OFFER (مثلاً، توصيل مجاني أو رسوم مخفَّضة)

اعتبارات أخرى:

• يجب عدم ضبط عروض الإعفاء من الرسوم أو تخفيضها على مستوى المنصة كعروض أساسية (OFFER_CATEGORY_BASE_OFFER)، بل يجب ضبطها فقط كعروض OFFER_CATEGORY_ADD_ON_FEE_REDUCTION_OFFER لتكملة عرض أساسي نشط آخر.
• إذا لم يحدّد المطعم "عرضًا أساسيًا"، لن تظهر "العروض الإضافية". في حال عدم توفّر "العرض الأساسي"، يجب تصنيف أي "عرض دفع" أو "عرض اشتراك" أو "عرض قسيمة" يمكن الاستفادة منه بدون الحاجة إلى إضافته إلى عرض آخر على أنّه OFFER_CATEGORY_BASE_OFFER.
  • استنادًا إلى النوع، يجب ضبط البيانات ذات الصلة لـ PaymentInstrument أو Subscription أو Coupon.
  • يجب أن يقدّم الشركاء نسختَين من كل عرض من هذه العروض لتغطية السيناريوهات التي تعمل فيها كعروض أساسية وعروض إضافية. يمكن بعد ذلك ضبط نسخة "العرض الإضافي" لمطاعم متعدّدة باستخدام entity_ids أو add_on_offer_applicable_to_all_entities.
• عندما يقدّم المطعم عدة عروض أساسية يمكن تجميعها، يجب وضع علامة OFFER_CATEGORY_BASE_OFFER على جميع العروض الأساسية، ويجب إرسال العروض الأساسية التي تتضمّن عروض دفع أو اشتراك أو قسائم بشكل إضافي كنوع عرض إضافي ذي صلة.
• يجب استخدام ValidityPeriod لتفعيل عروض الإضافة كعروض أساسية فقط في حال عدم توفّر عرض أساسي نشط.
• دمج العروض المتطابقة حسب وسيلة الدفع: إذا كانت وسائل دفع متعددة تشترك في قيمة الخصم نفسها (على سبيل المثال، بطاقة الائتمان وبطاقة السحب الآلي وNet Banking تقدّم جميعها خصمًا بنسبة% 5)، يجب تجميعها ضمن عنصر Offer واحد مدمج بدلاً من إرسال عروض مكرّرة منفصلة. لإجراء ذلك، املأ قائمة payment_instrument.items بجميع وسائل الدفع السارية. يؤدي ذلك إلى تقليل الفوضى في تنسيق واجهة Google ويمنع الانخفاض المحتمل في الترتيب بسبب القيود المفرطة على المحتوى المكرّر.

أمثلة على السيناريوهات:

• يقدّم مطعم خصمًا بنسبة% 5 عند الدفع باستخدام بطاقة ائتمان معيّنة ومشروبًا مجانيًا عند استخدام رمز قسيمة معيّن

  • يجب إرسال نسختَين من عرض بطاقة الائتمان الذي يقدّم خصمًا بنسبة% 5، إحداهما تحمل العلامة OFFER_CATEGORY_BASE_OFFER والأخرى تحمل العلامة OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER مع تضمين تفاصيل PaymentInstrument.
  • يجب إرسال عرض المشروب المجاني مع رمز القسيمة على النحو التالي: OFFER_CATEGORY_ADD_ON_COUPON_OFFER مع تضمين تفاصيل Coupon.

• يقدّم مطعم خصمًا بنسبة% 10 للعملاء الذين يزورون المطعم بدون حجز، وخصمًا بنسبة% 5 عند الدفع باستخدام بطاقة ائتمان معيّنة، ويمكن الجمع بين الخصمين.

  • يجب وضع علامة OFFER_CATEGORY_BASE_OFFER على عرض الخصم بنسبة% 10 للعملاء بدون موعد مسبق.
  • يجب أن يتضمّن عرض الخصم بنسبة% 5 على بطاقة الائتمان نسختَين، إحداهما تحمل العلامة OFFER_CATEGORY_BASE_OFFER والأخرى تحمل العلامة OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER.

• يقدّم أحد المطاعم خصمًا بنسبة% 10 على وجبة الغداء فقط خلال أيام الأسبوع، وخصمًا بنسبة% 5 في أي وقت عند الدفع باستخدام بطاقة ائتمان معيّنة.

  • يجب أن يكون عرض الخصم بنسبة% 10 ValidityPeriod مضبوطًا على الظهور خلال ساعات الغداء في المطعم خلال أيام الأسبوع فقط.
  • يجب إرسال عرض خصم% 5 على بطاقة الائتمان في نسختَين.
    • يجب وضع علامة OFFER_CATEGORY_BASE_OFFER على نسخة واحدة مع تضمين تفاصيل PaymentInstrument. ValidityPeriod يجب ضبطه لاستبعاد ساعات الغداء في أيام الأسبوع عندما يكون عرض خصم% 10 على الغداء نشطًا
    • يجب وضع علامة OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER على نسخة واحدة مع تضمين تفاصيل PaymentInstrument.
  • يجب وضع علامة OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER على جميع عروض الدفع الأخرى لهذا المطعم.

عملية التطوير والإطلاق

خلال عملية الدمج، ستتمكّن من الاستفادة من بوابة الشريك للحصول على المعلومات والملاحظات استنادًا إلى عملية التطوير. ستتّبع عملية التطوير الخطوات التالية:

• سيتم تطوير عملية الدمج أولاً في بيئة وضع الحماية. يجب استخدام نسخة مصدَّرة من بيانات الإنتاج (أو حتى بيانات الإنتاج مباشرةً) في بيئة Google Sandbox. يساعد ذلك في ضمان أن يغطي التطوير جميع الحالات الاستثنائية، ويتيح لـ Google تقييم جودة البيانات ومساعدتك بشكل أفضل استنادًا إلى نموذج البيانات الخاص بك.
• بعد تحميل خلاصات كاملة ويومية للتجّار والخدمات والصفقات بشكل متّسق في بيئة Google Sandbox، سيقيّم فريق Google خلاصاتك. بعد أن يوافق فريق Google، يمكنك نقل الرمز إلى مرحلة الإنتاج وبدء إرسال بيانات الإنتاج إلى بيئة الإنتاج في Google.
• بعد أن تختبر عملية الدمج في بيئة الإنتاج بشكل كامل، سيجري فريق Google اختبارًا أيضًا. بعد اكتمال جميع الاختبارات، سيتم إطلاق عملية الدمج.

المراقبة

لضمان تقديم تجربة جيدة للمستخدمين، ستتحقّق Google من أنّ العروض المقدَّمة صالحة وصحيحة وتستوفي معايير سياستنا قبل الإطلاق وبعده. ولإجراء ذلك، ستستخدم Google مزيجًا من المراجعة اليدوية والمبرمَجة. ستكون نتيجة هذه المراجعات متاحة في لوحة بيانات العروض في "مركز الإجراءات" (الإصدار العلني فقط). وقد يتم استخدام نتيجة هذه المراقبة للتأثير في ترتيب العروض.

تأكَّد من أنّ الصفحة تستغرق أقل من 5 ثوانٍ لتحميل العروض بالكامل، وإلا سيتم اعتبار ذلك فشلاً وسيتم وضع علامة Bad link عليها.

عمليات التحقّق الآلية (برامج الزحف)

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

عدد طلبات البحث

على سبيل المثال، إذا قررنا إرسال 5000 عملية تحقّق في اليوم، يعني ذلك أنّ الزاحف لدينا سينفّذ 5000 مرة في اليوم (موزّعة بالتساوي على مدار اليوم، أي مرة واحدة تقريبًا كل 17 ثانية) جميع الإجراءات التالية التي ينفّذها المستخدم العادي:

• ابدأ من "بحث Google"، وانقر على رابط الشريك.
• ابحث عن معلومات العرض.
• إذا كان العرض الترويجي يتطلّب حجزًا، سيتم الانتقال إلى مسار الحجز للتأكّد من توفّر العرض الترويجي في الوقت المحدّد (لن يتم إجراء أي حجز).

رصد برامج استخراج البيانات من الويب

لضمان عدم حظر برنامج استخراج البيانات من الويب (ما قد يؤدي إلى استنتاج أن العروض غير متوفرة)، تأكَّد من أنّ نظامك يسمح لبرنامج استخراج البيانات من الويب بالبحث في صفحتك في جميع الأوقات. لتحديد برنامج تتبُّع الويب الخاص بنا:

• سيحتوي وكيل المستخدم الخاص ببرنامج استخراج البيانات من الويب على السلسلة "Google-Offers":
  • مثال: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko; Google-Offers) Chrome/104.0.5112.101 Safari/537.36
• يمكنك أيضًا التحقّق مما إذا كانت الطلبات واردة من Google باستخدام نظام أسماء النطاقات العكسي كما هو مقترَح في مقالة "التأكّد من أنّ مصدر طلبات الزحف هو Googlebot وبرامج زحف أخرى من Google". في حالتنا المحدّدة، يتّبع التحويل العكسي باستخدام نظام أسماء النطاقات (DNS) هذا النمط: google-proxy-***-***-***-***.google.com.

السلوك الفني

التخزين المؤقت

لتقليل الحمل على الموقع الإلكتروني الشريك، يتم ضبط برامج الزحف بشكل عام لتراعي جميع عناوين التخزين المؤقت العادية لبروتوكول HTTP الموجودة في الاستجابة. وهذا يعني أنّنا نتجنّب جلب المحتوى الذي يتغيّر نادرًا (مثل مكتبات JavaScript) بشكل متكرّر من المواقع الإلكترونية التي تم إعدادها بشكل صحيح. لمزيد من التفاصيل حول كيفية تنفيذ التخزين المؤقت، يُرجى الاطّلاع على مستندات التخزين المؤقت عبر HTTP.