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

نظرة عامة

تتيح لك واجهة برمجة التطبيقات هذه تحديد الخصومات المحتملة. من بين العروض الترويجية المحدّدة، تطبّق Google العرض الترويجي المؤهَّل أو مجموعة العروض الترويجية التي تؤدي إلى أدنى سعر. إذا كنت تبحث عن واجهة برمجة تطبيقات تتيح التعديلات العشوائية لمعدّل الزحف والتي يمكنها إما زيادة السعر أو خفضه عند استيفاء الشروط، ننصحك بالاطّلاع على واجهة برمجة التطبيقات لمعدِّلات الأسعار. يُرجى العلم أنّه في حال توفّر واجهتَي برمجة التطبيقات، يتم تطبيق تعديلات الأسعار قبل العروض الترويجية.

طلبات

البنية

تستخدم الرسالة Promotions البنية التالية:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner= "partner_key"
            id="message_ID"
            timestamp="timestamp">
  <HotelPromotions hotel_id="HotelID" action="[overlay]">
    <Promotion id="PromotionID" action="[delete]">
      <BookingDates>
        <DateRange start="YYYY-MM-DD[THH:mm:ss]" end="YYYY-MM-DD[THH:mm:ss]"
          days_of_week="MTWHFSU_or_subset"/>
        <DateRange start="YYYY-MM-DD[THH:mm:ss]" end="YYYY-MM-DD[THH:mm:ss]"
          days_of_week="MTWHFSU_or_subset"/>
      </BookingDates>
      <BookingWindow min="integer_or_duration" max="integer_or_duration"/>
      <Ceiling amount_per_night="float"/>
      <Floor amount_per_night="float"/>
      <CheckinDates>
        <DateRange start="[YYYY-]MM-DD" end="[YYYY-]MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </CheckinDates>
      <CheckoutDates>
        <DateRange start="[YYYY-]MM-DD" end="[YYYY-]MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </CheckoutDates>
      <!-- Specify only one of percentage, fixed_amount, fixed_amount_per_night,
           fixed_price, or fixed_price_per_night; applied_nights is only used
           with percentage, fixed_amount_per_night, and fixed_price_per_night. -->
      <Discount percentage="float" fixed_amount="float" fixed_amount_per_night="float"
                fixed_price="float" fixed_price_per_night="float"
                applied_nights="integer_1_to_99" rank="integer_1_to_99">
        <!-- FreeNights may not be used in conjunction with attributes on Discount -->
        <FreeNights stay_nights="integer" discount_nights="integer"
                    discount_percentage="float" night_selection="[cheapest|last]"
                    repeats="boolean"/>
      </Discount>
      <!-- Exactly one of Discount or BestDailyDiscount must be specified.
           Specify only one of percentage, fixed_amount, or fixed_price. -->
      <BestDailyDiscount percentage="float" fixed_amount="float" fixed_price="float"/>
      <Devices>
        <Device type="[desktop|tablet|mobile]"/>
      </Devices>
      <InventoryCount min="integer" max="integer"/>
      <LengthOfStay min="integer" max="integer"/>
      <MembershipRateRule id="RateRuleID"/>
      <MinimumAmount before_discount="integer"/>
      <Occupancy min="integer" max="integer"/>
      <RatePlans>
        <RatePlan id="PackageID_1"/>
        <RatePlan id="PackageID_2"/>
      </RatePlans>
      <RoomTypes>
        <RoomType id="RoomID_1"/>
        <RoomType id="RoomID_2"/>
      </RoomTypes>
      <Stacking type="[any|base|none|second]"/>
      <StayDates application="[all|any|overlap]">
        <DateRange start="[YYYY-]MM-DD" end="[YYYY-]MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </StayDates>
      <UserCountries type="[include|exclude]">
        <Country code="country_code"/>
      </UserCountries>
    </Promotion>
  </HotelPromotions>
</Promotions>

العناصر والسمات

تحتوي رسالة العروض الترويجية على العناصر والسمات التالية:

العنصر / @Attribute	عدد مرات الظهور	النوع	الوصف
Promotions	1	Complex element	تمثّل هذه السمة العنصر الجذر لرسالة ترويجية.
Promotions / @partner	1	string	حساب الشريك لهذه الرسالة تمثّل قيمة السلسلة هذه قيمة "مفتاح الشريك" المدرَجة في صفحة "إعدادات الحساب" ضمن Hotel Center. إذا كانت لديك خلفية توفّر خلاصات لحسابات متعددة، يجب أن تتطابق هذه القيمة مع قيمة السمة ID المحدّدة في العنصر <RequestorID> في رسالتَي <OTA_HotelRateAmountNotifRQ> و<OTA_HotelAvailNotifRQ> للحساب نفسه.
Promotions / @id	1	string	معرّف فريد لرسالة الطلب هذه يتم عرض هذه القيمة في رسالة الرد. الأحرف المسموح بها هي a-z وA-Z و0-9 و_ (شرطة سفلية) و- (شرطة).
Promotions / @timestamp	1	DateTime	تاريخ إنشاء هذه الرسالة ووقتها.
Promotions / HotelPromotions	0..n	HotelPromotions	العروض الترويجية لأحد المواقع. ينطبق كل عرض ترويجي على موقع واحد. ما لم يتم استخدام السمة <Stacking>، يتم تطبيق العرض الترويجي الذي يقدّم أكبر خصم على الحجز عندما تكون عدة عروض ترويجية مؤهّلة.
Promotions / HotelPromotions / @hotel_id	1	string	تشير هذه السمة إلى المعرّف الفريد الخاص بالمكان المخصّص للاستئجار. يجب أن تتطابق هذه القيمة مع معرّف الفندق المحدّد باستخدام <id> في العنصر <listing> في خلاصة بيانات الفنادق. مُدرَج أيضًا رقم تعريف الفندق في مركز إدارة معلومات الفنادق.
Promotions / HotelPromotions / @action	0..1	enum	وفي حال تحديدها، يجب أن تكون القيمة "overlay". عندما تكون القيمة "overlay"، يتم حذف جميع العروض الترويجية المخزَّنة قبل تخزين العروض الترويجية المحدّدة في الرسالة الحالية. إذا لم يتم تحديد أي عرض ترويجي، سيكون كل عرض ترويجي محدّد في الرسالة الحالية إما: Added (إذا لم يكن أي من العروض الترويجية المخزَّنة يحتوي على id نفسه) Updated (إذا كان عرض ترويجي محفوظ يتضمّن id نفسه) Deleted (إذا كان عرض ترويجي مخزّن يتضمّن id نفسه وقيمة السمة action للعرض الترويجي المحدّدة في الرسالة الحالية هي "delete")
Promotions / HotelPromotions / Promotion	0..99	Promotion	عرض ترويجي واحد لفندق. يُرجى العِلم بأنّه في حال عدم تحديد السمة action="overlay" والسمة <Promotion>، سيتم حذف جميع العروض الترويجية الخاصة بالموقع. إذا كنت بحاجة إلى استخدام أكثر من 99 عرضًا ترويجيًا، يُرجى التواصل مع المدير التقني للحسابات (TAM).
Promotions / HotelPromotions / Promotion / @id	1	string	معرّف فريد للعرض الترويجي الحد الأقصى لعدد الأحرف المسموح به هو 40 حرفًا. الأحرف المسموح بها هي a-z وA-Z و0-9 و_ (شرطة سفلية) و- (شرطة) و . (نقطة).
Promotions /HotelPromotions / Promotion / @action	0..1	enum	وفي حال تحديدها، يجب أن تكون القيمة delete. إذا لم يتم تحديد السمة ولم يتم تخزين عرض ترويجي يحمل السمة id نفسها، سيتم حفظ هذا العرض الترويجي. وإذا لم يتم تحديد السمة وتم تخزين عرض ترويجي تحمل السمة id نفسها، سيتم تعديل العرض الترويجي الحالي. في حال تحديد السمة delete، يتم حذف العرض الترويجي المخزن الذي يحمل السمة id نفسها. عند استخدام delete، لا تضمِّن أي عناصر فرعية في <Promotion>. ولا يُسمح أيضًا باستخدام السمة delete مع السمة <HotelPromotions action="overlay"/>.
Promotions / HotelPromotions / Promotion / BookingDates	0..1	BookingDates	تمثّل هذه السمة حاوية لنطاق واحد أو أكثر تحدّد وقت إجراء الحجز ليتم تطبيق العرض الترويجي.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange	1..99	DateRange	تمثّل هذه السمة نطاقًا يحدّد وقت إجراء الحجز ليتم تطبيق العرض الترويجي.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @start	0..1	‫‎Date أو ‎DateTime	تاريخ البدء أو التاريخ (استنادًا إلى المنطقة الزمنية للموقع)، ويشمل ذلك النطاق. يجب أن يكون التاريخ أو التاريخ المحدَّد في start قبل (أو يتطابق مع) التاريخ أو التاريخ المحدَّد في end. إذا لم يتم تحديد السمة start، يصبح النطاق غير محدود فعليًا من حيث وقت البدء. إذا تمت تعبئة start كتاريخ "YYYY-MM-DD"، سيتم تفسيره على أنّه تاريخ ووقت "YYYY-MM-DDT00:00:00".
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end	0..1	‫‎Date أو ‎ DateTime	تاريخ الانتهاء أو التاريخ (استنادًا إلى المنطقة الزمنية للموقع)، بما في ذلك، النطاق. يجب أن يكون التاريخ أو التاريخ المحدَّد في end بعد التاريخ أو الوقت المحدَّد في start بعد (أو يتطابق مع التاريخ). إذا لم يتم تحديد السمة end، يصبح النطاق غير محدود فعليًا من حيث وقت الانتهاء. إذا تم تقديم end كتاريخ "YYYY-MM-DD"، سيتم تفسيره على أنّه تاريخ ووقت "YYYY-MM-DDT23:59:59".
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week	0..1	string	أيام الأسبوع المسموح بها في النطاق الزمني. إذا لم يتم تحديده، سيتم السماح بجميع الأيام في النطاق الزمني. ويحدّد كل حرف في السلسلة يومًا. على سبيل المثال، يحدّد "MTWHF" أنّ أيام الأسبوع مسموح بها في النطاق الزمني. الأحرف الصالحة هي: M ليوم الاثنين T يوم الثلاثاء W يوم الأربعاء H يوم الخميس F يوم الجمعة S ليوم السبت U ليوم الأحد أي تركيبة أحرف صالحة.
Promotions / HotelPromotions / Promotion / BookingWindow	0..1	BookingWindow	تحدّد هذه السمة الفترة الزمنية التي يجب أن يحدث فيها الحجز بالنسبة إلى تاريخ تسجيل الوصول (استنادًا إلى المنطقة الزمنية للموقع). على سبيل المثال، يمكن ضبط فترة الحجز على 7 أيام على الأقل، ولكن ليس أكثر من 180 يومًا، قبل تسجيل الوصول.
Promotions / HotelPromotions / Promotion / BookingWindow / @min	0..1	integer or duration	تمثّل هذه السمة الحدّ الأدنى للمدة المحدّدة قبل تسجيل الوصول، وهي المدة التي يجب خلالها حجز ليتم تطبيق العرض الترويجي. إذا لم يتم تحديد قيمة السمة أو إذا كانت قيمتها 0، ليس هناك حدّ أدنى. أنواع القيم الصالحة هي: عدد صحيح: عدد الأيام التي تسبق تاريخ تسجيل الوصول. على سبيل المثال، تشير القيمة 30 إلى أنّ العرض الترويجي يسري فقط على الحجوزات قبل 30 يومًا على الأقل من تاريخ تسجيل الوصول. المدة وفقًا لمعيار ISO 8601 (الأيام والساعات والدقائق): وهي عدد الأيام التي تسبق تاريخ تسجيل الوصول (ويمكن أن تتضمّن ساعات/دقائق). على سبيل المثال، تشير القيمة P30D إلى أنّ العرض الترويجي يسري فقط على الحجوزات قبل 30 يومًا على الأقل من تاريخ تسجيل الوصول. ويجب الحجز في اليوم الـ 30 قبل الوصول عند الساعة 6:00 مساءً أو قبله بقيمة P30DT6H.
Promotions / HotelPromotions / Promotion / BookingWindow / @max	0..1	integer or duration	تمثّل هذه السمة الحد الأقصى لعدد الأيام قبل تسجيل الوصول عند إجراء الحجز ليتم تطبيق العرض الترويجي. إذا لم يتم تحديد قيمة السمة أو إذا كانت قيمتها هي 0، لن يكون هناك حدّ أقصى. أنواع القيم الصالحة هي: عدد صحيح: عدد الأيام التي تسبق تاريخ تسجيل الوصول. على سبيل المثال، تشير القيمة 30 إلى أنّ العرض الترويجي يسري فقط على الحجوزات قبل 30 يومًا من تاريخ تسجيل الوصول على الأكثر. المدة وفقًا لمعيار ISO 8601 (الأيام والساعات والدقائق): وهي عدد الأيام التي تسبق تاريخ تسجيل الوصول (ويمكن أن تتضمّن ساعات/دقائق). على سبيل المثال، تشير القيمة P30D إلى أنّ العرض الترويجي يسري فقط على الحجوزات قبل 30 يومًا من تاريخ تسجيل الوصول على الأكثر. أما القيمة P30DT6H، فيجب الحجز في الساعة 6:00 مساءً في اليوم الثلاثين قبل للوصول.
Promotions / HotelPromotions / Promotion / Ceiling	0..1	Ceiling	تحدد هذه السمة القيود المفروضة على الحد الأقصى للقيمة التي يمكن ضبط المعدّل عليها بعد تطبيق العروض الترويجية. يجب أن تحدّد العروض الترويجية دائمًا <Discount> أو <BestDailyDiscount>، وبالتالي لإنشاء عرض ترويجي لا ينطبق إلا على <Ceiling>، يمكنك ضبط <Discount> مع percentage بقيمة 0. وفي حال ضبط حزم البيانات، يمكن تطبيق عروض ترويجية متعددة باستخدام <Ceiling> على إقامة واحدة. يتم تطبيق الخصم الخاص بكل عرض ترويجي، يليه مباشرةً الحدّ الأقصى له. ويوضّح المثال التالي كيفية مساهمة كل حد في احتساب العرض الترويجي التالي في الحزمة. مثال: سعر إقامة لمدة ليلة واحدة يبلغ سعر AmountBeforeTax فيها 100 ، وتتوفر حزمة من عرضَين ترويجيَّين: عرض ترويجي بنوع التكديس base، وfixed_amount من 25، وسقف amount_per_night من 60 عرض ترويجي من نوع التكديس second، وfixed_amount من 25، وسقف يبلغ amount_per_night من 90 فيما يلي ترتيب الحساب: يتم تطبيق العرض الترويجي base أولاً ويتم تطبيق الخصم من AmountBeforeTax على 75، ولكن سيتم تخفيضه في الحدّ الأقصى إلى 60. يقدّم العرض الترويجي "second" تخفيضًا على "AmountBeforeTax" من 60 إلى 35. يمثّل هذا الحد قيمة أقل من الحد الأقصى 90، وبالتالي لم يتم تطبيق الحدّ الأقصى الثاني. ويبلغ السعر النهائي 35. ويُرجى العِلم بأنّ القيمة 60 كحدّ أقصى إجمالي أكثر صرامة ليست ذات صلة لأنّها صالحة فقط للترويج الخاص بها، ولا يمكن أن يكون هناك حد أقصى موحّد يغطي حزمة العروض الترويجية بالكامل.
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night	1	float	الحدّ الأقصى للمبلغ الذي يمكن ضبط سعر الإقامة في الليلة عليه بعد تطبيق الخصم. إذا تم تحديد عنصر <Floor> أيضًا، يجب ضبط هذه السمة على قيمة أكبر من أو تساوي السمة amount_per_night في <Floor>. يتم تطبيق amount_per_night على الضرائب والرسوم عند تضمينها في سعر الليلة باستخدام AmountAfterTax، ولكن لا يتم تطبيقها باستخدام معلومات الضرائب.
Promotions / HotelPromotions / Promotion / Floor	0..1	Floor	تحدد هذه السمة القيود على الحدّ الأدنى للقيمة التي يمكن ضبط السعر عليها بعد تطبيق العروض الترويجية. يجب أن تحدّد العروض الترويجية دائمًا <Discount> أو <BestDailyDiscount>، وبالتالي لإنشاء عرض ترويجي لا ينطبق إلا على <Floor>، يمكنك ضبط <Discount> مع percentage بقيمة 0. لا يزال منطق <Floor> ينطبق على خصومات <FreeNights>، حتى إذا كان هناك خصم 100% في الليلة المجانية. وفي حال ضبط حزم البيانات، يمكن تطبيق عروض ترويجية متعددة باستخدام <Floor> على إقامة واحدة. سيطبّق كل عرض ترويجي الخصم الخاص به، ويليه الحدّ الأدنى له مباشرةً. ويوضّح المثال التالي كيفية مساهمة كل طابق في احتساب العرض الترويجي التالي في الحزمة. مثال: سعر إقامة لمدة ليلة واحدة يبلغ سعر AmountBeforeTax فيها 100 ، وتتوفر حزمة من عرضَين ترويجيَّين: عرض ترويجي بنوع التكديس base، fixed_amount من 25، وطابق amount_per_night من 90 عرض ترويجي بنوع التكديس second، fixed_amount من 25، وطابق amount_per_night من 60 فيما يلي ترتيب الحساب: يتم تطبيق العرض الترويجي base أولاً ويتم تطبيق خصم من AmountBeforeTax على 75، ولكن بعد ذلك يرفع الحد الأدنى إلى 90. يقدّم العرض الترويجي "second" تخفيضًا على "AmountBeforeTax" من 90 إلى 65. وهذا الرقم أعلى من الطابق 60، وبالتالي لم يتم تطبيق الطابق الثاني. ويبلغ السعر النهائي 65. وبما أنّ الحد 90 هو حد إجمالي أكثر صرامة، هو صالح فقط للترويج الخاص، ولا يمكن أن يكون هناك حد واحد يمتد لحزمة العروض الترويجية بأكملها.
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night	1	float	تمثّل هذه السمة الحدّ الأدنى للمبلغ الذي يمكن ضبط سعر الإقامة في الليلة عليه بعد تطبيق الخصم. إذا تم تحديد عنصر <Ceiling> أيضًا، يجب ضبط هذه السمة على قيمة أصغر من أو تساوي السمة amount_per_night في <Ceiling>. يتم تطبيق amount_per_night على الضرائب والرسوم عند تضمينها في سعر الليلة باستخدام AmountAfterTax، ولكن لا يتم تطبيقها باستخدام معلومات الضرائب.
Promotions / HotelPromotions / Promotion / CheckinDates	0..1	CheckinDates	تمثّل هذه السمة حاوية لنطاق زمني واحد أو أكثر تحدّد وقت تسجيل الوصول لكي يتم تطبيق العرض الترويجي.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange	1..20	DateRange	تمثّل هذه السمة نطاقًا زمنيًا يحدّد وقت تسجيل الوصول لكي يتم تطبيق العرض الترويجي. هذا العنصر غير مطلوب إذا حذفت عرضًا ترويجيًا واحدًا أو أكثر. يمكنك أيضًا استخدام التنسيق YearlessDate. إذا كان أحد start أو end تاريخًا سنويًا، يجب تعبئة كلاهما كتواريخ غير سنوية. يجب ألا تنتهي النطاقات الزمنية للسنة مع حلول العام الجديد. بدلاً من ذلك، يمكنك تمثيل النطاق كنطاقَين زمنيَين متجاورَين. على سبيل المثال، يمكن تمثيل {"12-29", "01-05"} على النحوين {"12-29", "12-31"} و{"01-01", "01-05"}.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @start	0..1	Date or YearlessDate	تاريخ البدء (استنادًا إلى المنطقة الزمنية للموقع)، ويشمل ذلك النطاق الزمني. ويجب أن يكون هذا التاريخ قبل تاريخ end أو مطابقًا له. إذا لم يتم تحديد السمة start، يصبح النطاق الزمني غير محدود فعليًا من حيث تاريخ البدء.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @end	0..1	Date or YearlessDate	تاريخ الانتهاء (استنادًا إلى المنطقة الزمنية للموقع)، ويشمل ذلك النطاق الزمني. ويجب أن يتطابق هذا التاريخ مع تاريخ start أو بعده. إذا لم يتم تحديد السمة end، يصبح النطاق الزمني غير محدود فعليًا من حيث تاريخ الانتهاء.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @days_of_week	0..1	string	أيام الأسبوع المسموح بها في النطاق الزمني. إذا لم يتم تحديده، سيتم السماح بجميع الأيام في النطاق الزمني. ويحدّد كل حرف في السلسلة يومًا. على سبيل المثال، يحدّد "MTWHF" أنّ أيام الأسبوع مسموح بها في النطاق الزمني. الأحرف الصالحة هي: M ليوم الاثنين T يوم الثلاثاء W يوم الأربعاء H يوم الخميس F يوم الجمعة S ليوم السبت U ليوم الأحد أي تركيبة أحرف صالحة.
Promotions / HotelPromotions / Promotion / CheckoutDates	0..1	CheckoutDates	يجب أن تتضمّن حاوية نطاق زمني واحد أو أكثر تحدِّد وقت إتمام الدفع لتطبيق العرض الترويجي.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange	1..20	DateRange	تمثّل هذه السمة نطاقًا زمنيًا يحدّد وقت إتمام الدفع لكي يتم تطبيق العرض الترويجي. هذا العنصر غير مطلوب إذا كنت تحذف واحدًا أو أكثر من العروض الترويجية. يمكنك أيضًا استخدام التنسيق YearlessDate. إذا كانت إحدى القيمتين start أو end تتضمّن تاريخًا سنويًا، يجب تعبئتهما كتواريخ غير سنوية. يجب ألا تنتهي النطاقات الزمنية للسنة مع حلول العام الجديد. بدلاً من ذلك، يمكنك تمثيل النطاق كنطاقَين زمنيَين متجاورَين. على سبيل المثال، يمكن تمثيل {"12-29", "01-05"} على النحوين {"12-29", "12-31"} و{"01-01", "01-05"}.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @start	0..1	Date or YearlessDate	تاريخ البدء (استنادًا إلى المنطقة الزمنية للموقع)، ويشمل ذلك النطاق الزمني. ويجب أن يكون هذا التاريخ قبل تاريخ end أو مطابقًا له. إذا لم يتم تحديد السمة start، يصبح النطاق الزمني غير محدود فعليًا من حيث تاريخ البدء.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @end	0..1	Date or YearlessDate	تاريخ الانتهاء (استنادًا إلى المنطقة الزمنية للموقع)، ويشمل ذلك النطاق الزمني. ويجب أن يتطابق هذا التاريخ مع تاريخ start أو بعده. إذا لم يتم تحديد السمة end، يصبح النطاق الزمني غير محدود فعليًا من حيث تاريخ الانتهاء.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @days_of_week	0..1	string	أيام الأسبوع المسموح بها في النطاق الزمني. إذا لم يتم تحديده، سيتم السماح بجميع الأيام في النطاق الزمني. ويحدّد كل حرف في السلسلة يومًا. على سبيل المثال، يحدّد "MTWHF" أنّ أيام الأسبوع مسموح بها في النطاق الزمني. الأحرف الصالحة هي: M ليوم الاثنين T يوم الثلاثاء W يوم الأربعاء H يوم الخميس F يوم الجمعة S ليوم السبت U ليوم الأحد أي تركيبة أحرف صالحة.
Promotions / HotelPromotions / Promotion / Devices	0..1	Devices	حاوية تتضمّن أجهزة المستخدمين المؤهّلة للعرض الترويجي. إذا تم تحديد السعر المخفّض، لن يُتاح سوى للمستخدمين المؤهَّلين على الأجهزة المدرَجة السعر المخفّض. في حال عدم تحديد هذه السمة، سنقدّم للمستخدمين المؤهَّلين على أي جهاز السعر المخفَّض.
Promotions / HotelPromotions / Promotion / Devices / Device	1..3	Device	تحدّد هذه السمة نوعًا واحدًا من أجهزة المستخدمين مؤهَّلاً للاستفادة من العرض الترويجي.
Promotions / HotelPromotions / Promotion / Devices / Device / @type	1	enum	نوع الجهاز يجب أن تكون القيمة desktop أو tablet أو mobile.
Promotions / HotelPromotions / Promotion / Discount	1	Discount	يجب تحديد سمة واحدة فقط من Discount أو BestDailyDiscount. تحدّد هذه السمة الخصم الذي سيتم تطبيقه على هذا العرض الترويجي.
Promotions / HotelPromotions / Promotion / Discount / @percentage	0..1	float	ويجب استخدام سمة واحدة فقط من percentage أو fixed_amount أو fixed_amount_per_night أو fixed_price أو fixed_price_per_night. قيمة عشرية من 0 إلى 100 تحدّد النسبة المئوية للخصم ويتم تطبيقها على AmountAfterTax (أو AmountBeforeTax إذا لم يتم تحديد سمة AmountAfterTax). أمثلة: إذا كانت قيمة AmountAfterTax هي 100 وpercentage تساوي 20، حينئذٍ معدّل العرض الترويجي = AmountAfterTax * (1 - النسبة المئوية للخصم) 80.00 = 100 * (1 - 0.2) إذا كانت قيمة AmountBeforeTax هي 100، وقيمة percentage هي 20، وتحدّد TaxFeeInfo ضريبة بقيمة 10، معدّل العرض الترويجي = AmountBeforeTax * (1 - النسبة المئوية للخصم) + الضريبة 90.00 = 100 * (1 - 0.2) + 10
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount	0..1	float	ويجب استخدام سمة واحدة فقط من percentage أو fixed_amount أو fixed_amount_per_night أو fixed_price أو fixed_price_per_night. مبلغ ثابت يتم طرحه من مجموع أسعار الإقامة في الليلة الواحدة (AmountAfterTax) (أو مجموع AmountBeforeTax أسعار في الليلة إذا لم يتم تحديد سمة AmountAfterTax). ومن المفترض أن تكون العملة نفسها المستخدَمة في أسعار الليلة. وإذا كانت هذه القيمة أكبر من مجموع أسعار الليلة، تكون القيمة الناتجة صفرًا. أمثلة: إذا كنا نريد تحديد أسعار إقامة لمدة ليلة واحدة وكان AmountBeforeTax يساوي 90 وAmountAfterTax هو 100 وfixed_amount 20، إذًا معدّل العرض الترويجي = AmountAfterTax - خصم ثابت 80.00 = 100 - 20 إذا كنا نحدّد أسعار إقامة لليلة واحدة تكون فيها قيمة السمة AmountBeforeTax 100 والقيمة fixed_amount هي 20، وتحدّد ضريبة TaxFeeInfo ضريبة نسبتها %8، معدّل العرض الترويجي = (AmountBeforeTax - خصم ثابت) * (1 + النسبة المئوية للضريبة) 86.40 = (100 - 20) * 1.08 إذا كنا نحدّد أسعارًا لإقامة لمدة ليلة واحدة يكون فيها AmountBeforeTax 50 وfixed_amount 60 وTaxFeeInfo لتحديد ضريبة بقيمة 10، معدّل الترويج = (AmountBeforeTax - خصم ثابت) * الضريبة 10.00 = 0 + 10 إذا كنا نحدّد أسعارًا لإقامة لمدة 3 ليالٍ تكون فيها القيم AmountAfterTax هي 100 و110 و120، وقيمة fixed_amount تساوي 150، معدّل العرض الترويجي = sum(AmountAfterTax) - (خصم ثابت) 180.00 = (100 + 110 + 120) - 150
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night	0..1	float	ويجب استخدام سمة واحدة فقط من percentage أو fixed_amount أو fixed_amount_per_night أو fixed_price أو fixed_price_per_night. يمثّل هذا النوع خصمًا ثابتًا يتم تطبيقه على كلّ سعر من أسعار الإقامة في الليلة الواحدة (AmountAfterTax) (أو السعر الأدنى تكلفة في حال تحديد السمة applied_nights). إذا لم يتم تحديد السمة AmountAfterTax، سيتم تطبيقها على السمة AmountBeforeTax. ومن المفترض أن تكون العملة نفسها المستخدَمة في أسعار الليلة. إذا كان fixed_amount_per_night أكبر من سعر الليلة، سيتم خفض سعر الليلة إلى صفر، ولا يمكن أن يتسبّب الخصم في أن يصبح سعر الليلة قيمة سالبة. أمثلة: إذا كنا نحدّد أسعارًا لإقامة لمدة 3 ليالٍ وكانت قيم AmountAfterTax فيها 100 و110 و120، وقيمة fixed_amount_per_night تساوي 10، معدّل العرض الترويجي = المبلغ(AmountBeforeTax - الخصم بمبلغ ثابت) 300.00 = ((100 - 10) + (110 - 10) + (120 - 10)) إذا كنا نحدّد أسعارًا لإقامة لمدة 3 ليالٍ تتراوح فيها القيم AmountAfterTax و10 و50 و100، وقيمة fixed_amount_per_night تساوي 20، معدّل العرض الترويجي = المبلغ(AmountAfterTax - الخصم بمبلغ ثابت) 110.00 = (0 + (50 - 20) + (100 - 20))
Promotions / HotelPromotions / Promotion / Discount / @fixed_price	0..1	float	ويجب استخدام سمة واحدة فقط من percentage أو fixed_amount أو fixed_amount_per_night أو fixed_price أو fixed_price_per_night. إذا تم تحديد أسعار الإقامة في الليلة بـ AmountAfterTax، سيُضبط هذا سعر الإقامة على القيمة المحدّدة، بما في ذلك الضرائب والرسوم. إذا تم تحديد AmountBeforeTax، في حال تحديد AmountAfterTax أو لا، سيتم ضبط السعر قبل احتساب الضريبة للإقامة على القيمة المحدّدة. ومن المفترض أن تكون العملة نفسها المستخدَمة في أسعار الليلة. إذا كان الغرض من السمة AmountAfterTax هو عرض نسبة مئوية من الضريبة، قد يؤدي ضبط سعر ثابت لـ AmountBeforeTax إلى تحصيل ضرائب ورسوم غير دقيقة. وبشكل عام، ننصح بشدة باستخدام السمة TaxFeeInfo لتحديد الضرائب والرسوم في الفندق. أمثلة: إذا كنا نريد تحديد أسعار إقامة لليلة واحدة وكان AmountBeforeTax يبلغ 90 وAmountAfterTax على 100 وfixed_price 80، يكون سعر العرض الترويجي 80. إذا كنا نحدّد أسعار إقامة لليلة واحدة تكون فيها قيمة السمة AmountBeforeTax 100 والقيمة fixed_amount هي 80، وتحدّد ضريبة TaxFeeInfo ضريبة نسبتها %8، معدّل الترويج = سعر ثابت * (1 + نسبة الضريبة) 86.40 = 80 * 1.08 إذا كنا نحدّد أسعار إقامة لمدة 3 ليالٍ وكانت القيم AmountAfterTax فيها 100 و110 و120، وقيمة fixed_amount تساوي 300، معدّل الترويج = 300
Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night	0..1	float	ويجب استخدام سمة واحدة فقط من percentage أو fixed_amount أو fixed_amount_per_night أو fixed_price أو fixed_price_per_night. في حال تحديد أسعار الإقامة في الليلة بـ AmountAfterTax، سيضبط هذا سعر كل ليلة إقامة على القيمة المحدّدة، بما في ذلك الضرائب والرسوم. في حال تحديد AmountBeforeTax، سواء تم تحديد AmountAfterTax أم لا، سيتم ضبط السعر قبل احتساب الضريبة لكل ليلة إقامة على القيمة المحدّدة. ومن المفترض أن تكون العملة نفسها المستخدَمة في أسعار الليلة. إذا كان الغرض من السمة AmountAfterTax هو عرض نسبة مئوية من الضريبة، قد يؤدي ضبط سعر ثابت لـ AmountBeforeTax إلى تحصيل ضرائب ورسوم غير دقيقة. وبشكل عام، ننصح بشدة باستخدام السمة TaxFeeInfo لتحديد الضرائب والرسوم في الفندق. إذا تم تحديد applied_nights، سيتم تطبيق السعر الجديد على أقل سعر لـ N ليلة. أمثلة: إذا كنا نحدّد أسعار إقامة لمدة ليلتين وكانت قيم AmountBeforeTax هي 90 و90، وقيمة AmountAfterTax هي 100 و100، وقيمة fixed_price هي 80، يكون معدّل العرض الترويجي 80 + 80 = 160. إذا كنا نحدّد أسعارًا لإقامة لمدة ليلتين وكانت قيمة السمة AmountBeforeTax هي 100 و100 والقيمة fixed_amount هي 80، وحدّدت ضريبة القيمة المضافة ضريبة بنسبة %8، يكون معدّل العرض الترويجي (80 + 80) * 1.08 = 172.8. إذا كنا نحدّد أسعار إقامة لمدة 3 ليالٍ تكون فيها القيم AmountAfterTax هي 100 و110 و120، وقيمة fixed_amount تساوي 110، يكون معدّل العرض الترويجي 110 × 3 = 330.
Promotions / HotelPromotions / Promotion / Discount / @applied_nights	0..1	integer	ولا يمكن استخدام هذه السمة إلا مع percentage أو fixed_amount_per_night. تمثّل هذه السمة عدد الليالي التي يتم تطبيق الخصم عليها، بدءًا من الأقل تكلفة. يجب أن تكون القيمة عددًا صحيحًا من 1 إلى 99. وفي حال عدم تحديد قيمة، سيتم تطبيق الخصم على جميع الليالي.
Promotions / HotelPromotions / Promotion / Discount / FreeNights	0..1	FreeNights	تحدّد هذه السمة خصمًا على ليالي معيّنة من الإقامة عند استيفاء الحد الأدنى لمدة الإقامة. ولا يُسمح بالسمات في العنصر Discount الرئيسي في حال استخدام هذا العنصر.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights	1	integer	عدد الليالي المطلوبة لكي يتم تطبيق الخصم. ويتم تطبيق كل خصم على قسم منفصل من ليالي الإقامة. على سبيل المثال، بالنسبة إلى الإقامة لمدة 10 ليالٍ يكون فيها stay_nights 4 (وتكون repeats صحيحة)، يتم تحديد جزءَين للإقامة ليلاً: الفترة الأولى إلى الرابعة من الليالي، والليلة الخامسة إلى الثامنة، بينما لا تشكّل الليالي التاسعة والعاشرة جزءًا من فترة الإقامة الليلية.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_nights	1	integer	عدد ليالي الإقامة بسعر مخفَّض ضمن كل قسم من ليالي الإقامة
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage	1	float	الخصم الذي يسري على ليالي الخصم. إذا كانت هذه القيمة هي 50، سيتم خصم% 50 على كل ليلة يتم اختيارها.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection	1	string	يجب أن تكون إما cheapest أو last. في حال last، سيتم خصم قيمة الليالي في نهاية فترة الإقامة مقابل عدد الليالي المحددة. في حال cheapest، سيتم خصم أسعار الليالي الأرخص ضمن نطاق ليالي الإقامة.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats	1	boolean	ما إذا كان يمكن تطبيق الخصم على عدة إقامة ليلية للإقامة. في حال تحديد false، لن يتم الخصم إلا من مدة الإقامة لمدة ليالي الإقامة في بداية برنامج الرحلة. في حال true، سيتم خصم أي جزء من ليالي الإقامة. على سبيل المثال، إذا كانت قيمة السمة stay_nights هي 4 أيام وكان برنامج الرحلة مدته 10 ليالٍ، سيتم خصم جزءَين (من 1 إلى 4 ليلات والليلة من 5 إلى 8 ليالٍ)، أما إذا كانت قيمة سمة repeats هي false، فسيتم خصم جزء واحد فقط (من 1 إلى 4 ليالٍ).repeatstrue
Promotions / HotelPromotions / Promotion / Discount / @rank	0..1	integer	تحدّد هذه السمة ترتيبًا لهذا العرض الترويجي ويفعّله في اختيار الترتيب، حيث يتم فقط تطبيق العرض الترويجي ذي الترتيب الأدنى. ويجب أن تتراوح القيم بين 1 و99 بشكل شامل. في حال مشاركة عروض ترويجية متعددة في الترتيب نفسه، يتم اختيار عرض ترويجي واحد وتطبيقه بشكل عشوائي.
Promotions / HotelPromotions / Promotion / BestDailyDiscount	1	Discount	يجب تحديد سمة واحدة فقط من Discount أو BestDailyDiscount. تحدّد هذه السمة خصمًا يوميًا قد يتم تطبيقه على ليلة الإقامة. ويختلف ذلك عن السمة Discount التي تُطبّق الخصومات على الإقامات الكاملة. يمكن أن يحتوي كل موقع على مجموعة واحدة من العروض الترويجية التي تُعتبر "الأفضل يوميًا". وهذا يعني أنّه لكل ليلة إقامة، يتم اختيار العرض الترويجي "الأفضل يوميًا" المؤهَّل الذي يحقّق أعلى خصم لهذه الليلة وقد يتم تطبيقه. لا يمكن تحديد السمة Stacking في BestDailyDiscount. ويتم الجمع بين خصومات "أفضل الأسعار اليومية" التي تقدّم الخصم الأكثر قيمة لكل ليلة ويتم التعامل معها على أنّها خصومات على الإقامة لمرة واحدة (مثل Discount) مع ضبط نوع التكديس على base. تتم مقارنة هذا الخصم المجمّع بالعروض الترويجية المؤهَّلة الأخرى من نوع <Discount>، ويمكن الجمع بينها للعثور على العرض أو التركيبة التي تقدّم أكبر خصم. ويتم اختيار تركيبة BestDailyDiscount أو Discount واحدة، أيهما يؤدي إلى انخفاض السعر، وتطبيقها على نوع تجميع البيانات base. يمكن تحديد StayDates مع هذا النوع من الخصم، ولكن يجب ضبط application على overlap. .
Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage	0..1	float	ويجب استخدام سمة واحدة فقط من percentage أو fixed_amount أو fixed_price. قيمة عشرية من 0 إلى 100 تحدّد النسبة المئوية للخصم ويتم تطبيقها على AmountAfterTax (أو AmountBeforeTax إذا لم يتم تحديد سمة AmountAfterTax). أمثلة: إذا كانت قيمة AmountAfterTax لليلة الإقامة 100 وقيمة percentage هي 20، يجب عندها معدّل العرض الترويجي = AmountAfterTax * (1 - النسبة المئوية للخصم) 80.00 = 100 * (1 - 0.2) إذا كانت قيمة السمة AmountBeforeTax لإقامة إقامة 100، تكون قيمة percentage هي 20 وتحدّد TaxFeeInfo ضريبة بقيمة 10، معدّل العرض الترويجي = AmountBeforeTax * (1 - النسبة المئوية للخصم) + الضريبة 90.00 = 100 * (1 - 0.2) + 10
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount	0..1	float	ويجب استخدام سمة واحدة فقط من percentage أو fixed_amount أو fixed_price. مبلغ ثابت يتم طرحه من سعر AmountAfterTax واحد في الليلة (أو AmountBeforeTax سعر الليلة في حال عدم تحديد سمة AmountAfterTax). ومن المفترض أن تكون العملة نفسها المستخدَمة في أسعار الليلة. وإذا كانت هذه القيمة أكبر من مجموع أسعار الليلة، تكون القيمة الناتجة صفرًا. أمثلة: إذا كان قيمة AmountBeforeTax لليلة الواحدة 90، وAmountAfterTax كانت 100، وfixed_amount تساوي 20، عندئذ معدّل العرض الترويجي = AmountAfterTax - خصم ثابت 80.00 = 100 - 20 إذا كانت قيمة AmountBeforeTax لليلة الواحدة هي 100، والقيمة fixed_amount هي 20، وحدّدت TaxFeeInfo ضريبة تبلغ %8، عندئذ معدّل العرض الترويجي = (AmountBeforeTax - خصم ثابت) * (1 + النسبة المئوية للضريبة) 86.40 = (100 - 20) * 1.08
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price	0..1	float	ويجب استخدام سمة واحدة فقط من percentage أو fixed_amount أو fixed_price. إذا تم تحديد أسعار الإقامة في الليلة بـ AmountAfterTax، سيتم تحديد سعر ليلة الإقامة، بما في ذلك الضرائب والرسوم، على القيمة المحدّدة. إذا تم تحديد AmountBeforeTax، في حال تحديد AmountAfterTax أو لا، سيتم ضبط السعر قبل احتساب الضريبة للإقامة على القيمة المحدّدة. ومن المفترض أن تكون العملة نفسها المستخدَمة في أسعار الليلة. أمثلة: إذا كان سعر AmountBeforeTax لليلة الواحدة هو 90 والسمة AmountAfterTax 100 والسمة fixed_price 80، يكون سعر العرض الترويجي 80. إذا كانت قيمة السمة AmountBeforeTax لليلة الواحدة هي 100، وقيمة السمة fixed_amount هي 80، وحدَّدت TaxFeeInfo ضريبة تبلغ %8، يتم عندها: معدّل الترويج = سعر ثابت * (1 + نسبة الضريبة) 86.40 = 80 * 1.08
Promotions / HotelPromotions / Promotion / InventoryCount	0..1	InventoryCount	يتم تحديد القيود المفروضة على عدد الغرف التي يجب أن تكون متاحة ليتم تطبيق هذا العرض الترويجي. لا يتم تطبيق الخصم إلا على الليالي التي تستوفي القيود المفروضة. لا يُسمح بها مع خصم fixed_amount. يُرجى العِلم أنّه يتم تحديد عدد الغرف المتاحة من خلال OTA_HotelInvCountNotifRQ (InvCount) أو OTA_HotelAvailNotifRQ (BookingLimit).
Promotions / HotelPromotions / Promotion / InventoryCount / @min	0..1	integer	تمثّل هذه السمة الحد الأدنى لعدد الغرف التي يجب أن تكون متاحة من أجل تطبيق العرض الترويجي على سعر الإقامة في الليلة. وإذا لم يتم تحديد قيمة السمة، ما مِن حد أدنى.
Promotions / HotelPromotions / Promotion / InventoryCount / @max	0..1	integer	تمثّل هذه السمة الحد الأقصى لعدد الغرف التي يجب أن تتوفَّر في العرض الترويجي، وذلك على سعر الإقامة في الليلة. وإذا لم يتم تحديد قيمة السمة، لن يكون هناك حدّ أقصى.
Promotions / HotelPromotions / Promotion / LengthOfStay	0..1	LengthOfStay	تحدّد هذه السمة حدود مدة الإقامة التي يمكن تطبيق هذا العرض الترويجي ضمنها. لا يسري العرض الترويجي عندما تتجاوز مدة الإقامة الحد الأدنى والحد الأقصى.
Promotions / HotelPromotions / Promotion / LengthOfStay / @min	0..1	integer	تمثّل هذه السمة الحدّ الأدنى لعدد الليالي المسموح بها خلال الإقامة ليتم تطبيق العرض الترويجي. وإذا لم يتم تحديد قيمة الحقل، فلا يوجد حد أدنى.
Promotions / HotelPromotions / Promotion / LengthOfStay / @max	0..1	integer	تمثّل هذه السمة الحدّ الأقصى لعدد الليالي المسموح بها في الإقامة خلال مدة الإقامة ليتم تطبيق العرض الترويجي. وإذا لم يتم تحديد قيمة السمة، لن يكون هناك حدّ أقصى.
Promotions / HotelPromotions / Promotion / MembershipRateRule	0..1	MembershipRateRule	حاوية لقاعدة سعر الاشتراك التي تؤدي إلى معالجة الخصم المرتبط على واجهة المستخدم يجب عدم تحديد هذا العنصر ما لم يتم تحديد <Discount> أيضًا.
Promotions / HotelPromotions / Promotion / MembershipRateRule / @id	1	string	رقم تعريف قاعدة الأسعار المرتبطة ببرنامج عضوية.
Promotions / HotelPromotions / Promotion / MinimumAmount	0..1	MinimumAmount	تحدّد هذه السياسة الحد الأدنى لإجمالي أسعار الغرف اليومية (باستخدام القيمة الأكبر من AmountBeforeTax أو AmountAfterTax) التي يجب تجاوزها ليتم تطبيق العرض الترويجي.
Promotions / HotelPromotions / Promotion / MinimumAmount / @before_discount	1	integer	القيمة التي يجب تجاوزها لتطبيق العرض الترويجي
Promotions / HotelPromotions / Promotion / Occupancy	0..1	Occupancy	تحدّد هذه السمة القيود المفروضة على عدد النزلاء الذي ينطبق عليه هذا العرض الترويجي. لا يسري العرض الترويجي عندما يكون عدد النزلاء خارج الحدّ الأدنى والحد الأقصى.
Promotions / HotelPromotions / Promotion / Occupancy / @min	0..1	integer	يجب ألا يقلّ عدد النزلاء الذي حدّده المستخدم عن هذه القيمة حتى يتم تطبيق الخصم.
Promotions / HotelPromotions / Promotion / Occupancy / @max	0..1	integer	يجب ألّا يزيد عدد النزلاء الذي يحدّده المستخدم عن هذه القيمة حتى يتم تطبيق الخصم.
Promotions / HotelPromotions / Promotion / RatePlans	0..1	RatePlans	حاوية لقائمة خطط الأسعار التي ينطبق عليها العرض الترويجي إذا لم يتم تحديد السمة <RatePlans>، يسري العرض الترويجي على جميع خطط الأسعار.
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan	1..n	RatePlan	تحدّد خطة أسعار. يتم تحديد خطة الأسعار من خلال مجموعة تشمل الحزمة والأسعار ومدى التوفّر، على النحو المحدّد في رسائل المعاملات (بيانات الموقع) وOTA_HotelRateAmountNotifRQ وOTA_HotelAvailNotifRQ، وعلى النحو المحدّد في PackageID.
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id	1	string	المعرّف الفريد لخطة الأسعار يتم ربط هذه القيمة بقيمة معرّف الحزمة في <PackageData> في رسالة المعاملة (بيانات الموقع)، وفي السمة RatePlanCode في <StatusApplicationControl> في رسالتَي <OTA_HotelRateAmountNotifRQ> و<OTA_HotelAvailNotifRQ>. الحد الأقصى لعدد الأحرف المسموح به هو 50 حرفًا.
Promotions / HotelPromotions / Promotion / RoomTypes	0..1	RoomTypes	حاوية لقائمة بأنواع الغرف التي ينطبق عليها العرض الترويجي يتم تطبيق العرض الترويجي على كل <RoomType> محدّدة. إذا لم يتم تحديد السمة <RoomTypes>، يسري العرض الترويجي على جميع الغرف.
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType	1..n	RoomType	تحدِّد هذه السياسة نوع الغرفة. يتم تحديد نوع الغرفة في عنصر <RoomData> في رسالة المعاملة (بيانات الموقع)، وتتم الإشارة إليه باستخدام قيمة <RoomID>. (تتم الإشارة إلى قيمة <RoomID> أيضًا من خلال السمة InvTypeCode في رسائل OTA_HotelRateAmountNotifRQ).
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id	1	string	المعرّف الفريد للمستودع (نوع الغرفة) يتم ربط هذه القيمة بـ <RoomID> في رسالة معاملة (بيانات الموقع). الحد الأقصى لعدد الأحرف المسموح به هو 50 حرفًا.
Promotions / HotelPromotions / Promotion / Stacking	0..1	Stacking	تحدّد هذه السمة طريقة دمج العروض الترويجية. إذا لم يتم تحديد قيمة، يتم افتراض أن النوع "النوع" هو base.
Promotions / HotelPromotions / Promotion / Stacking / @type	1	enum	ويمكن تطبيق عروض ترويجية متعددة على سعر واحد استنادًا إلى هذا الإعداد: any: يمكن دمج هذا العرض الترويجي مع أي عرض ترويجي آخر (باستثناء none)، ولكن لا يمكن ضمان الترتيب الذي يجب تطبيق العروض الترويجية به. base: يتم اختيار أفضل عرض ترويجي مؤهَّل من base وتطبيقه أولاً قبل العروض الترويجية الأخرى. وكان يسمّى سابقًا base_only. second: يتم اختيار أفضل عرض ترويجي مؤهَّل من second وتطبيقه بعد عرض ترويجي base (إذا كان ذلك منطبقًا) وقبل any عرض ترويجي. none: لا يمكن الجمع بينه وبين عروض ترويجية أخرى. من بين التركيبات المسموح بها، يتم تطبيق مجموعة العروض الترويجية التي تحقّق أكبر خصم.
Promotions / HotelPromotions / Promotion / StayDates	0..1	StayDates	تمثّل هذه السمة حاوية لنطاق زمني واحد أو أكثر تحدّد كيفية تطبيق العرض الترويجي، مثل تضمين خصومات موسمية.
Promotions / HotelPromotions / Promotion / StayDates / @application	1	enum	تصف هذه السمة طريقة تطبيق العرض الترويجي. القيم الصالحة هي: all: يطبّق العرض الترويجي على كل ليلة في برنامج الرحلة إذا تداخلت جميع التواريخ في برنامج الرحلة مع تواريخ الإقامة. any: يطبّق العرض الترويجي على جميع الليالي في برنامج الرحلة إذا تداخل أي تاريخ في برنامج الرحلة مع تاريخ ضمن النطاق الزمني للإقامة. overlap: لا يسري العرض الترويجي إلا على الليالي في برنامج الرحلة الذي يتداخل مع تاريخ في نطاق تواريخ الإقامة. يجب تحديد هذه السمة دائمًا. إذا كانت السمة <Discount> تحدّد percentage وapplication على all أو any، يتم تطبيق الخصم كنسبة مئوية من الإقامة الكاملة. إذا كانت السمة <Discount> تحدّد السمة percentage وتم ضبط السمة application على overlap، سيتم تطبيق الخصم كنسبة مئوية من أسعار الإقامة في الليلة لليالي المتداخلة. وتُعدّ السمة <Discount> التي تضبط fixed_amount وapplication على overlap تركيبة غير صالحة. وتتيح السمة <FreeNights> استخدام جميع قيم application. يُرجى العِلم أنّه بالنسبة إلى overlap، يتم احتساب ليالٍ إقامة متداخلة فقط ضمن متطلبات الخصم.
Promotions / HotelPromotions / Promotion / StayDates / DateRange	1..99	DateRange	نطاق زمني يحدّد تواريخ تطبيق العرض الترويجي يمكنك أيضًا استخدام التنسيق YearlessDate. إذا كانت إحدى القيمتين start أو end تتضمّن تاريخًا سنويًا، يجب تعبئتهما كتواريخ غير سنوية. يجب ألا تنتهي النطاقات الزمنية للسنة مع حلول العام الجديد. بدلاً من ذلك، يمكنك تمثيل النطاق كنطاقَين زمنيَين متجاورَين. على سبيل المثال، يمكن تمثيل {"12-29", "01-05"} على النحوين {"12-29", "12-31"} و{"01-01", "01-05"}.
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @start	0..1	Date or YearlessDate	تاريخ البدء (استنادًا إلى المنطقة الزمنية للموقع)، ويشمل ذلك النطاق الزمني. ويجب أن يكون هذا التاريخ قبل تاريخ end أو مطابقًا له. إذا لم يتم تحديد السمة start، يصبح النطاق الزمني غير محدود فعليًا من حيث تاريخ البدء.
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end	0..1	Date or YearlessDate	تاريخ الانتهاء (استنادًا إلى المنطقة الزمنية للموقع)، ويشمل ذلك النطاق الزمني. ويجب أن يتطابق هذا التاريخ مع تاريخ start أو بعده. إذا لم يتم تحديد السمة end، يصبح النطاق الزمني غير محدود فعليًا من حيث تاريخ الانتهاء.
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @days_of_week	0..1	string	أيام الأسبوع المسموح بها في النطاق الزمني. إذا لم يتم تحديده، سيتم السماح بجميع الأيام في النطاق الزمني. ويحدّد كل حرف في السلسلة يومًا. على سبيل المثال، يحدّد "MTWHF" أنّ أيام الأسبوع مسموح بها في النطاق الزمني. الأحرف الصالحة هي: M ليوم الاثنين T يوم الثلاثاء W يوم الأربعاء H يوم الخميس F يوم الجمعة S ليوم السبت U ليوم الأحد أي تركيبة أحرف صالحة.
Promotions / HotelPromotions / Promotion / UserCountries	0..1	UserCountries	حاوية لبيانات المواقع الجغرافية للمستخدمين (البلدان) المؤهّلة للعرض الترويجي إذا تم تحديد السعر المخفّض، يُتاح للمستخدمين المؤهَّلين فقط في البُلدان المدرَجة فيه السعر المُخفَّض. في حال عدم تحديد ذلك، سيتم تقديم السعر المخفَّض للمستخدمين المؤهَّلين في أي بلد.
Promotions / HotelPromotions / Promotion / UserCountries / @type	0..1	enum	تمثّل هذه السمة نوع مواصفات Userالبُلدان. القيمتان الصالحتان هما include وexclude. إذا تم ضبط سمة type في Userالبُلدان على include، يسري العرض الترويجي على المستخدمين المقيمين في البُلدان المُدرَجة. إذا كانت قيمة سمة Userالبُلدان type هي exclude، ينطبق العرض الترويجي على المستخدمين من خارج البُلدان المدرَجة. أما في حال ترك سمة type في بلدان المستخدم بدون ضبط، فسيتم التعامل معها على أنّها include، وسيتم تطبيق العرض الترويجي على المستخدمين في البُلدان المدرَجة.
Promotions / HotelPromotions / Promotion / UserCountries / Country	1..300	Country	تحدّد هذه السمة بلدًا واحدًا يكون فيه المستخدمون مؤهلين للاستفادة من العرض الترويجي.
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code	1	string	رمز CLDR للبلد، مثل DE أو FR. يُرجى العلم أنّ رمز CLDR للبلد في بعض البلدان يختلف عن رمز البلد المكوّن من حرفَين وفقًا لمعيار ISO. بالإضافة إلى ذلك، لا يمكن استخدام رموز CLDR للمناطق.

أمثلة

الرسالة الأساسية

يعرض المثال التالي رسالة Promotions أساسية:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <BookingDates>
         <DateRange start="2020-07-01" end="2020-07-31" days_of_week="MTWHF"/>
         <DateRange start="2020-09-01" end="2020-09-30"/>
      </BookingDates>
      <BookingWindow min="7" max="330"/>
      <CheckinDates>
         <DateRange start="2020-10-01" end="2020-10-31" days_of_week="FSU"/>
      </CheckinDates>
      <CheckoutDates>
         <DateRange start="2020-10-08" end="2020-11-07" days_of_week="FSU"/>
      </CheckoutDates>
      <Devices>
        <Device type="mobile"/>
        <Device type="tablet"/>
      </Devices>
      <Discount percentage="20" applied_nights="2"/>
      <LengthOfStay min="2" max="14"/>
      <RatePlans>
         <RatePlan id="234"/>
         <RatePlan id="567"/>
      </RatePlans>
      <RoomTypes>
         <RoomType id="123"/>
         <RoomType id="456"/>
      </RoomTypes>
      <Stacking type="base"/>
      <UserCountries>
        <Country code="US"/>
        <Country code="GB"/>
      </UserCountries>
    </Promotion>
  </HotelPromotions>
</Promotions>

حالة المستودع

يوضّح المثال التالي كيفية إنشاء خصم في حال وجود مخزون زائد بالقرب من تاريخ الوصول:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <BookingWindow max="7"/>
      <Discount percentage="10"/>
      <InventoryCount min="3"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

حذف عرض ترويجي واحد

يوضّح المثال التالي كيفية حذف عرض ترويجي واحد لأحد المواقع:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1" action="delete"/>
  </HotelPromotions>
</Promotions>

حذف جميع الإعلانات الترويجية

يوضّح المثال التالي كيفية حذف جميع العروض الترويجية لأحد المواقع:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1" action="overlay"/>
</Promotions>

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

يوضّح المثال التالي كيفية إضافة <HotelPromotions> لموقع يضم عرضًا ترويجيًا جديدًا واحدًا أو أكثر. عند تفعيل action="overlay"، يتم حذف جميع العروض الترويجية المخزَّنة قبل تخزين العروض الترويجية المحدّدة في الرسالة الحالية:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1" action="overlay">
    <Promotion id="1">
      <BookingDates>
         <DateRange start="2020-09-01" end="2020-09-30"/>
      </BookingDates>
      <Discount percentage="10"/>
      <RoomTypes>
         <RoomType id="123"/>
         <RoomType id="456"/>
      </RoomTypes>
      <RatePlans>
         <RatePlan id="234"/>
         <RatePlan id="567"/>
      </RatePlans>
      <Stacking type="base"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

3 أنواع مختلفة للتكديس

يوضّح المثال التالي حالة تطبيق ثلاثة عروض ترويجية مختلفة (base وsecond وany). يُرجى العلم أنّه لن يتم تطبيق عرض none الترويجي لأنّ العروض الترويجية الأخرى تقدّم خصمًا أفضل. إذا كان السعر الأصلي 100 دولار أمريكي، سيكون السعر المخفّض 72.90 دولار أمريكي.

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <Discount percentage="10"/>
      <Stacking type="base"/>
    </Promotion>
    <Promotion id="2">
      <Discount percentage="10"/>
      <Stacking type="second"/>
    </Promotion>
    <Promotion id="3">
      <Discount percentage="10"/>
      <Stacking type="any"/>
    </Promotion>
    <Promotion id="4">
      <Discount percentage="25"/>
      <Stacking type="none"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

بدون نوع تكديس

يوضّح المثال التالي حالة يتم فيها استخدام العرض الترويجي none لأنّ مجموعة العروض الترويجية الأخرى تقدّم خصمًا أصغر. إذا كان السعر الأصلي 100 دولار، فسيكون السعر المخفض هو 75 دولارًا.

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <Discount percentage="10"/>
      <Stacking type="base"/>
    </Promotion>
    <Promotion id="2">
      <Discount percentage="10"/>
      <Stacking type="any"/>
    </Promotion>
    <Promotion id="3">
      <Discount percentage="25"/>
      <Stacking type="none"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

حدود مدة الحجز

يوضّح المثال التالي حالة يتم فيها استخدام العنصر BookingWindow مع تحديد حدود البداية والنهاية كنوع المدة ISO 8601. وتتطلّب فترة الحجز هذه الحجز في الساعة 6:00 مساءً أو قبل يوم الوصول بيوم الوصول، وفي اليوم الثاني قبل الوصول أو بعد الساعة 12:00 في اليوم الثاني قبل الوصول.

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <BookingWindow min="P1DT6H" max="P2DT12H"/>
      <Discount percentage="20"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

تواريخ الحجز وتواريخ أو وقت

يوضّح المثال التالي حالة استخدام العنصر BookingDates مع السمتَين start وend كأنواع DateTime. يتطلّب قيد تاريخ الحجز هذا أن يحدث الحجز بين الساعة 6:30 في 01-07-2020 وبين الساعة 6:45 في 2020-07-02.

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <BookingDates>
         <DateRange start="2020-07-01T06:30:00" end="2020-07-02T18:45:00"/>
      </BookingDates>
      <Discount percentage="20"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

النطاقات الزمنية السنوية

يوضّح المثال التالي حالة يحتوي فيها العنصر CheckInDates على DateRanges يتضمّن حقلَين start وend بدون سنوات. في هذا المثال، ينطبق العرض الترويجي على تواريخ تسجيل الوصول بين 12/29 و2/1، بغض النظر عن السنة. تكون النطاقات الزمنية السنوية التي تتخطى حدود العام الجديد غير صالحة، لذا يتم التعبير عن النطاق الزمني في شكل نطاقين زمنيين متجاورين.

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <CheckInDates>
         <DateRange start="12-29" end="12-31"/>
         <DateRange start="01-01" end="01-02"/>
      </CheckInDates>
      <Discount percentage="20"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

خصم على FreeNights

يقدم المثال التالي خصومات على ليلتين بنسبة 50٪ لكل أربع ليالٍ تم إقامتها للنطاق المحدد من تواريخ الحجز. بالنسبة لبرنامج رحلة لمدة عشر ليالٍ، سيتم خصم إجمالي أربع ليالٍ بنسبة 50٪.

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <BookingDates>
        <DateRange start="2022-01-01" end="2022-05-31"/>
      </BookingDates>
      <Discount>
        <FreeNights stay_nights="4" discount_nights="2" discount_percentage="50" night_selection="cheapest" repeats="true"/>
      </Discount>
    </Promotion>
  </HotelPromotions>
</Promotions>

في المثال التالي، خصومات ليلة واحدة بنسبة 50٪ لكل ثلاث ليالٍ تم إقامتها في نطاقات تواريخ الإقامة المحددة. يتم احتساب ليالي الإقامة المتداخلة فقط بينما تؤهّلك للحصول على الخصم. بالنسبة إلى برنامج الرحلة التالي عند تسجيل الوصول في 2022-01-01 وتسجيل المغادرة في 07-01-2022، سيتم تطبيق ليالي الإقامة المؤهلة والخصومات على النحو التالي.

• 2022-01-01 (إقامة)
• 2022-01-02 (إقامة)
• 2022-01-03
• 2022-01-04 (سعر مخفَّض)
• 2022-01-05 (إقامة)
• 2022-01-06 (إقامة)

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <StayDates application="overlap">
        <DateRange start="2022-01-01" end="2022-01-02"/>
        <DateRange start="2022-01-04" end="2022-01-06"/>
      </StayDates>
      <Discount>
        <FreeNights stay_nights="3" discount_nights="1" discount_percentage="50" night_selection="last" repeats="true"/>
      </Discount>
    </Promotion>
  </HotelPromotions>
</Promotions>

الاختيار المُرتب

يقدّم المثال التالي خصمَين، أحدهما بخصم 20% والآخر خصم 15%. وأثناء التقييم، يتم تطبيق الخصم بنسبة 15% فقط لأنّه يحصل على ترتيب أدنى.

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <Discount percentage="15" rank="25"/>
    </Promotion>
    <Promotion id="2">
      <Discount percentage="20" rank="50"/>
    </Promotion>
  </HotelPromotions>
</Promotions>

BestDailyDiscount

يقدّم المثال التالي خصمًا على إقامة لمدة ليلتين من خلال تطبيق حزمة BestDailyDiscount مع Discount.

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
 <HotelPromotions hotel_id="HotelID" action="overlay">
   <Promotion id="general">
     <BestDailyDiscount fixed_amount="20"/>
   </Promotion>
   <Promotion id="may">
     <BestDailyDiscount fixed_amount="50"/>
     <StayDates application="overlap">
        <DateRange start="2023-05-01" end="2023-05-31"/>
     </StayDates>
   </Promotion>
   <Promotion id="fiesta">
     <Discount fixed_amount_per_night="5"/>
     <Stacking type="any"/>
   </Promotion>
 </HotelPromotions>
</Promotions>

يمكنك إقامة لمدة ليلتين في الفترة من 30 أبريل 2023 إلى 2 مايو 2023. وللحساب، يتم أولاً العثور على مجموعة من أفضل الخصومات اليومية التي تحقّق أكبر خصم.

في الليلة الأولى، يكون العرض الترويجي "عام" هو المبلغ المؤهَّل الوحيد الذي يتضمن خصمًا ثابتًا بقيمة 20.

وفي الليلة الثانية، يقدّم العرض الترويجي "قد" خصمًا أعلى من الخصم "عام". لذلك، عند تحديد "قد"، يكون مبلغ الخصم الثابت هو 50.

وبالنسبة إلى الإقامة، يمكن تطبيق خصومات العرض الترويجي "المهرجان" على 5 في الليلة أو إجمالي 10 خصومات. يمكن إضافة مجموعة من أفضل الخصومات اليومية لأنّه تم ضبط نوع تجميع البيانات لـ "fiesta" على any. إذا تم ضبط القيمة على base، لن يتم تطبيق سوى مجموعة من أفضل الخصومات اليومية أو خصم "المهرجان". يمكنك الاطّلاع على وصف "Stacking" للحصول على مزيد من المعلومات.

"بشكل عام، يحصل سعر الإقامة على خصم بقيمة 20 + 50 + 10 = 80 بمبلغ ثابت.

الردود

البنية

تستخدم الرسالة PromotionsResponse البنية التالية:

<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="timestamp"
                    id="message_ID"
                    partner="partner_key">
  <!-- Either Success or Issues are populated. -->
  <Success/>
  <Issues>
    <Issue code="issue_code"
           status="issue_type">
      issue_description
    </Issue>
  </Issues>
</PromotionsResponse>

العناصر والسمات

تحتوي الرسالة PromotionsResponse على العناصر والسمات التالية:

العنصر / @Attribute	عدد مرات الظهور	النوع	الوصف
PromotionsResponse	1	Complex element	العنصر الجذر الذي يشير إلى نجاح أو مشاكل رسالة طلب عروض ترويجية تم استلامها.
PromotionsResponse / @timestamp	1	DateTime	تاريخ إنشاء هذه الرسالة ووقتها.
PromotionsResponse / @id	1	string	المعرّف الفريد من رسالة العروض الترويجية المرتبطة
PromotionsResponse / @partner	1	string	حساب الشريك لهذه الرسالة
PromotionsResponse / Success	0..1	Success	يشير هذا الرمز إلى أنّه تمت معالجة رسالة العروض الترويجية بنجاح بدون تحذيرات أو أخطاء أو حالات إخفاق. تحتوي كل رسالة على <Success> أو <Issues>.
PromotionsResponse / Issues	0..1	Issues	حدثت حاوية لمشكلة واحدة أو أكثر أثناء معالجة رسالة "العروض الترويجية". تحتوي كل رسالة على <Success> أو <Issues>.
PromotionsResponse / Issues / Issue	1..n	Issue	تمثّل هذه السمة وصف التحذير أو الخطأ أو الخطأ الذي حدث أثناء معالجة رسالة "العروض الترويجية". يمكن العثور على تفاصيل حول هذه المشاكل في رسائل الخطأ لحالة الخلاصة.
PromotionsResponse / Issues / Issue / @code	1	integer	معرِّف المشكلة.
PromotionsResponse / Issues / Issue / @status	1	enum	نوع المشكلة التي حدثت. القيم الصالحة هي warning وerror وfailure.

أمثلة

تم الإجراء بنجاح

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

<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="2020-05-18T16:20:00-04:00"
                    id="12345678"
                    partner="partner_key">
  <Success/>
</PromotionsResponse>

المشاكل

في ما يلي رد على رسالة ترويجية لم تتم معالجتها بسبب حدوث أخطاء.

<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="2020-05-18T16:20:00-04:00"
                    id="12345678"
                    partner="partner_key">
  <Issues>
    <Issue code="1001" status="error">Example</Issue>
  </Issues>
</PromotionsResponse>