نظرة عامة

ملاحظة: هذه تجربة.

تحذير: هذا المستند قيد الإنشاء. قد تتغيّر المعلومات بشكل متكرّر.

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

العروض

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

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

• خصم 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	مصفوفة من قيم التعداد (OfferMode)	مطلوب	طُرق الاستفادة من العرض، مثل الحجز أو الشراء على الإنترنت أو غير ذلك حقل إلزامي
offer_category	enum (OfferCategory)	مطلوب	تمثّل هذه السمة فئة العرض. الحقل مطلوب.
source_assigned_priority	الرقم		عدد صحيح غير سالب ([1-100]، حيث يمثّل الرقم 1 أعلى مستوى من الأولوية) يشير إلى مستوى أولوية العرض الذي حدّده المصدر. عندما تتوفّر عروض متعدّدة للتاجر نفسه، سيشكّل ذلك إشارة لترتيب العروض. تشير القيمة 0 إلى أنّه لم يتم ضبط الأولوية.
offer_details	الكائن (OfferDetails)	مطلوب	تمثّل هذه السمة تفاصيل العرض، مثل الخصم وتكلفة الحجز وما إلى ذلك. مطلوبة.
offer_restrictions	الكائن (OfferRestrictions)	مطلوب	توضّح هذه السمة القيود المفروضة على العرض، أي ما إذا كان الاشتراك أو وسيلة الدفع مطلوبَين، وما إذا كان يمكن الجمع بين هذا العرض وعروض أخرى (وما هي الأنواع)، وما إلى ذلك. هذه السمة مطلوبة.
coupon	الكائن (Coupon)		تفاصيل قسيمة مطلوبة لفئة العرض: OFFER_CATEGORY_ADD_ON_COUPON_OFFER.
payment_instrument	الكائن (PaymentInstrument)		تعرض هذه السمة تفاصيل وسيلة الدفع. مطلوبة لفئة العرض: OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER.
subscription	الكائن (Subscription)		تعرض هذه السمة تفاصيل الاشتراك. مطلوبة لفئة العرض: OFFER_CATEGORY_ADD_ON_SUBSCRIPTION_OFFER.
terms	الكائن (Terms)	مطلوب	أحكام العرض وشروطه الحقل مطلوب.
validity_periods	مصفوفة تتضمّن عناصر (ValidityPeriod)	مطلوب	تمثّل هذه السمة مدة صلاحية العرض. تصف هذه السمة الفترة الزمنية التي يكون العرض ساريًا خلالها، بما في ذلك أوقات البدء والانتهاء وأيام الأسبوع وما إلى ذلك. هذه السمة مطلوبة.
offer_url	سلسلة		تمثّل هذه السمة عنوان URL لصفحة العرض التي يقدّمها التاجر. مطلوبة لفئة العرض: OFFER_CATEGORY_BASE_OFFER.
image_url	سلسلة		تمثّل هذه السمة عنوان URL لصورة العرض الترويجي الخاص بالتاجر.
tags	مصفوفة من التعداد (OfferTag)		علامات خاصة مرتبطة بالعرض يُستخدم هذا الحقل لتحديد العروض الخاصة، مثل "موسم الأعياد" و"الأكثر تقييمًا" و"الأكثر حجزًا" وما إلى ذلك.
brand_id	سلسلة		مطلوبة لعروض بطاقات الهدايا لتحديد العلامة التجارية التي تقدّم العرض.

OfferDetails

اسم الحقل	النوع	المتطلبات	الوصف
offer_display_text	سلسلة	مطلوب	نص العرض الذي يريد مقدّم العرض الترويجي عرضه للعملاء على صفحة نتائج البحث الحقل مطلوب.
	oneOf (offer_specification)	مطلوب	لا يمكن ضبط سوى حقل واحد من الحقول في هذا oneOf.
max_discount_value	الكائن (Money)		الحد الأقصى للخصم الذي يمكن الاستفادة منه على سبيل المثال، خصم بنسبة% 10 يصل إلى 100 ريال سعودي.
min_spend_value	الكائن (Money)		تمثّل هذه السمة الحدّ الأدنى لقيمة الإنفاق للاستفادة من الخصم. على سبيل المثال، خصم ‎10% عندما يكون السعر الإجمالي 100 دولار أمريكي أو أكثر.
booking_cost	الكائن (Money)		تمثّل هذه السمة تكلفة حجز هذا العرض. على سبيل المثال، خصم 100 دولار أمريكي من الفاتورة النهائية عند حجز طاولة مقابل 15 دولارًا أمريكيًا.
booking_cost_unit	enum (FeeUnit)		تمثّل هذه السمة وحدة تكلفة الحجز. على سبيل المثال، لكل شخص ولكل معاملة.
convenience_fee	الكائن (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)		لا يمكن ضبط سوى حقل واحد من الحقول في هذا oneOf.

MoneyRange

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

AdditionalFee

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

GiftCardInfo

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

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	الكائن (FoodOfferRestrictions)		قيود خاصة بعروض الطعام
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	الكائن (Duration)	مطلوب	تحدّد هذه السمة مدة صلاحية الاشتراك مقابل تكلفة الاشتراك. الحقل مطلوب.
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	الكائن (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	الكائن (Timestamp)	مطلوب	تمثّل هذه السمة وقت بدء النطاق (شامل). الحقل مطلوب.
valid_through_time	الكائن (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	الكائن (TimeOfDayRange)	مطلوب	الفترة الزمنية التي يمكن فيها تقديم الطلب أو تنفيذه الحقل مطلوب.
day_of_week	مصفوفة من قيم التعداد (DayOfWeek)		قائمة بأيام الأسبوع التي يتم تطبيق النوافذ عليها في حال عدم ضبط أي أيام، يعني ذلك أنّ السياسة تنطبق على جميع أيام الأسبوع. اختياريّ.

TimeOfDayRange

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

اسم الحقل	النوع	المتطلبات	الوصف
open_time	الكائن (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.

ValidTimeException

اسم الحقل	النوع	المتطلبات	الوصف
exceptional_period	الكائن (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_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 دولار أمريكي. سيتم ضبط الحقول ذات الصلة في العرض الأساسي المحظور بقسيمة أو وسيلة دفع. لدينا أيضًا عروض إضافية، مثل 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

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

offer_specification

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

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

التكلفة

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

denomination_type

اسم الحقل	النوع	المتطلبات	الوصف
fixed_denominations	الكائن (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_BASE_OFFER.
  • استنادًا إلى النوع، يجب ضبط البيانات ذات الصلة بـ PaymentInstrument أو Subscription أو Coupon.
  • على الشركاء تقديم نسختَين من كل عرض من هذه العروض لتغطية الحالات التي تعمل فيها كعروض أساسية وعروض إضافية. يمكن بعد ذلك ضبط نسخة "عرض الحزمة" لمطاعم متعدّدة باستخدام entity_ids أو add_on_offer_applicable_to_all_entities.
• عندما يقدّم المطعم عروضًا أساسية متعددة يمكن دمجها، يجب تصنيف جميع العروض الأساسية على أنّها OFFER_CATEGORY_BASE_OFFER، كما يجب إرسال العروض الأساسية التي تتضمّن عروضًا للدفع أو الاشتراك أو القسائم بشكل إضافي كنوع العرض الإضافي ذي الصلة.
• يجب استخدام ValidityPeriod لتفعيل عروض "الحزمة الإضافية" كعروض "الحزمة الأساسية" فقط عندما لا يتوفّر عرض "الحزمة الأساسية" نشط.

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

• يقدّم مطعم خصمًا بنسبة% 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 في أي وقت عند الدفع باستخدام بطاقة ائتمان معيّنة.

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

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

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

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

التتبّع

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

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

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

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

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

على سبيل المثال، إذا قرّرنا إرسال 5,000 عملية تحقّق في اليوم، يعني ذلك أنّ 5,000 مرة في اليوم (يتم توزيعها بالتساوي على مدار اليوم، أي مرة واحدة كل 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.