الإعلانات الترويجية

نظرة عامة

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

الكائن Requests

البنية

تستخدم رسالة 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 يومًا على الأقل من تاريخ تسجيل الوصول. ويجب حجز قيمة P30DT6H عند الساعة 3:00 بعد الظهر في اليوم الثلاثين قبل الوصول إلى الوجهة.
Promotions / HotelPromotions / Promotion / BookingWindow / @max	0..1	integer or duration	الحدّ الأقصى لعدد الأيام التي تسبق تسجيل الوصول والتي يجب أن يتم خلالها الحجز لكي يتم تطبيق العرض الترويجي. وإذا لم يتم تحديد هذه القيمة أو كانت قيمتها 0، ما مِن حد أقصى. أنواع القيم الصالحة هي: عدد صحيح: عدد الأيام قبل تاريخ تسجيل الوصول. على سبيل المثال، تشير القيمة 30 إلى أنّ العرض الترويجي ينطبق فقط على الحجوزات قبل 30 يومًا على الأكثر من تاريخ تسجيل الوصول. المدة ISO 8601 (بالأيام والساعات والدقائق): عدد الأيام (والساعات/الدقائق اختياريًا) قبل تاريخ تسجيل الوصول. على سبيل المثال، تشير القيمة P30D إلى أنّ العرض الترويجي ينطبق فقط على الحجوزات قبل 30 يومًا على الأكثر من تاريخ تسجيل الوصول. وتتطلّب قيمة P30DT6H الحجز في الساعة 30: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، ولكن لا يتم تحديدها باستخدام TaxFeeInfo.
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، ولكن لا يتم تحديدها باستخدام TaxFeeInfo.
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، معدّل العرض الترويجي = المجموع(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 (أو أقل قيمة N في حال تحديد 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، سيتم تطبيق السعر الجديد على أقل عدد من الليالي. أمثلة: إذا كان تحديد سعر إقامة لمدة ليلتَين تساوي 90 أو 90 في AmountBeforeTax، وتتراوح قيم AmountAfterTax بين 100 و100 وfixed_price 80، يكون معدّل العرض الترويجي 80 + 80 = 160. إذا كان تحديد سعر إقامة لمدة ليلتَين في AmountBeforeTax هو 100 أو 100، وfixed_amount 80، وتحديد ضريبة TaxFeeInfo بنسبة 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 صحيحة)، يتم توفير شريحتَين لإقامة لمدة 10 ليالٍ: من الليالي الأولى إلى الليالي الرابعة، والليلة الخامسة إلى الثامنة، ولا تشكّل الليالي التاسعة والعاشرة جزءًا من شريحة الإقامة ليلة.
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 ليالٍ، إذا كانت قيمة repeats هي true، سيتم تقديم خصم على قسمَين (الليلة من 1 إلى 4 والليلة من 5 إلى 8)، أما إذا كانت قيمة repeats هي false، سيتم خصم شريحة واحدة فقط (الليلة من 1 إلى 4 ليالٍ).
Promotions / HotelPromotions / Promotion / Discount / @rank	0..1	integer	يعيّن هذا العرض الترويجي ترتيبًا ويفعّله في اختيار الترتيب، حيث يتم اختيار العرض الترويجي الأقل ترتيبًا فقط لتطبيقه. يجب أن تتراوح القيم بين 1 و99، بشكل شامل. إذا يتشارك عدّة عروض ترويجية في الترتيب نفسه، يتم اختيار أحد العروض الترويجية بشكل عشوائي وتطبيقه.
Promotions / HotelPromotions / Promotion / BestDailyDiscount	1	Discount	يجب تحديد سمة واحدة فقط من Discount أو BestDailyDiscount. تحدّد هذه العلامة خصمًا يوميًا يمكن تطبيقه على ليلة الإقامة. وتختلف هذه السياسة عن سياسة Discount التي تطبّق الخصومات على الإقامات بأكملها. قد يحتوي كل موقع على مجموعة واحدة من العروض الترويجية التي تُعتبر "الأفضل يوميًا". وهذا يعني أنّه بالنسبة إلى كل ليلة إقامة، يتم اختيار العرض الترويجي الفردي "أفضل عرض يومي" المؤهّل والذي يحقّق أعلى خصم لتلك الليلة، وقد يتم تطبيقه. لا يمكن تحديد السمة Stacking مع BestDailyDiscount. يتم دمج الخصومات "أفضل يوم" التي تؤدي إلى أعلى خصم لكل ليلة، ويتم التعامل معها على أنّها خصم على إقامة واحدة (أي Discount) مع ضبط نوع التكدس على base. تتم مقارنة هذا الخصم المجمَّع بالعروض الترويجية المؤهلة الأخرى من خلال <خصومات> ويمكن جمعه معها للعثور على العرض أو المجموعة التي تحقّق أكبر خصم. يتم اختيار إمّا الجمع بين 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	المعرّف الفريد لخطة الأسعار ترتبط هذه القيمة بقيمة PackageID في <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	تحدّد هذه العلامة كيفية جمع العروض الترويجية. وإذا لم يتم تحديد ذلك، يُفترض أن تكون قيمة "type" هي 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، يتم تطبيق الخصم كنسبة مئوية من مدة الإقامة الكاملة. إذا تمّ ضبط percentage وapplication على overlap وفقًا للسمة <Discount>، يتم تطبيق الخصم كنسبة مئوية من أسعار الإقامة في الليلة الواحدة في الليالي المتداخلة. إنّ <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	تمثّل هذه السمة نوع مواصفات بلدان المستخدم. القيمتان الصالحتان هما include وexclude. وإذا تم ضبط السمة type في "بلدان المستخدمين" على include، يسري العرض الترويجي على المستخدمين في البلدان المدرَجة. إذا كانت قيمة 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 Duration. إنّ القيود المفروضة على فترة الحجز هذه تتطلب الحجز في الساعة 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. يتطلب فرض قيود على تاريخ الحجز أن يتم الحجز بين الساعة 06:30 صباحًا في يوم 01-07-2020 والساعة 18: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٪ لكل أربع ليالٍ تبقى للنطاق المحدد لتواريخ الحجز. بالنسبة إلى برنامج رحلة مدته 10 ليالٍ، سيتم خصم إجمالي 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% لكل ثلاث ليالٍ بقيت للنطاقات المحدّدة لتواريخ الإقامة. يتم فقط احتساب عدد ليالي الإقامة المتداخلة حتى تكون مؤهّلة للحصول على الخصم. بالنسبة إلى برنامج الرحلة التالي الذي تم تسجيل الوصول فيه في 01-01-2022 وتسجيل المغادرة في 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 مع إضافة 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، سيتم تطبيق مجموعة أفضل الخصومات اليومية أو خصم "fiesta" فقط. يمكنك الاطّلاع على وصف 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>