نمای کلی
این API به شما امکان میدهد تخفیفهای ممکن را مشخص کنید. از بین تبلیغات مشخص شده، گوگل تبلیغات واجد شرایط یا مجموعهای از تبلیغات را که منجر به کمترین قیمت میشود، اعمال میکند. اگر به دنبال API هستید که از تنظیمات نرخ دلخواه پشتیبانی میکند و میتواند در صورت برآورده شدن شرایط، قیمت را افزایش یا کاهش دهد، API اصلاح نرخ ما را در نظر بگیرید. توجه داشته باشید که اگر هر دو API وجود داشته باشند، تغییرات نرخ قبل از تبلیغات اعمال میشوند.
درخواستها
نحو
پیام 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, percentage_of_base, 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" percentage_of_base="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 | حساب کاربری همکار برای این پیام. این مقدار رشتهای، مقدار «کلید همکار» است که در صفحه تنظیمات حساب کاربری در مرکز هتل فهرست شده است. اگر یک backend دارید که برای چندین حساب کاربری فید ارائه میدهد، این مقدار باید با مقدار ویژگی |
| Promotions / @id | 1 | string | یک شناسه منحصر به فرد برای این پیام درخواست. این مقدار در پیام پاسخ برگردانده میشود. کاراکترهای مجاز عبارتند از az، AZ، 0-9، _ (زیرخط) و - (خط تیره). |
| Promotions / @timestamp | 1 | DateTime | تاریخ و زمان ایجاد این پیام. |
| Promotions / HotelPromotions | 0..n | HotelPromotions | تبلیغات برای یک ملک. هر تبلیغ برای یک ملک واحد اعمال میشود. مگر اینکه از |
| Promotions / HotelPromotions / @hotel_id | 1 | string | شناسه منحصر به فرد برای ملک. این مقدار باید با شناسه هتل مشخص شده با استفاده از <id> در عنصر <listing> در فید فهرست هتل مطابقت داشته باشد. شناسه هتل همچنین در مرکز هتل فهرست شده است. |
| Promotions / HotelPromotions / @action | 0..1 | enum | در صورت مشخص شدن، مقدار باید اگر مشخص نشده باشد، هر تبلیغ مشخص شده در پیام فعلی یکی از موارد زیر است:
|
| Promotions / HotelPromotions / Promotion | 0..99 | Promotion | یک تبلیغ واحد برای یک ویژگی. توجه داشته باشید که اگر اگر نیاز به استفاده از بیش از ۹۹ پیشنهاد دارید، با مدیر فنی حساب خود (TAM) تماس بگیرید. |
| Promotions / HotelPromotions / Promotion / @id | 1 | string | یک شناسه منحصر به فرد برای تبلیغ. حداکثر تعداد کاراکترهای مجاز ۴۰ است. کاراکترهای مجاز عبارتند از az، AZ، ۰-۹، _ (زیرخط)، - (خط تیره) و . (نقطه). |
| Promotions /HotelPromotions / Promotion / @action | 0..1 | enum | اگر مشخص شده باشد، مقدار باید اگر |
| 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 | تاریخ شروع یا تاریخ-زمان (بر اساس منطقه زمانی ملک)، شامل محدوده.
|
| Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end | 0..1 | Date یا DateTime | تاریخ پایان یا تاریخ-زمان (بر اساس منطقه زمانی ملک)، شامل محدوده.
|
| Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week | 0..1 | string | روزهای هفته که در محدوده تاریخ مجاز هستند. اگر مشخص نشده باشند، همه روزها در محدوده تاریخ مجاز هستند. هر کاراکتر در رشته یک روز را مشخص میکند. به عنوان مثال، "MTWHF" مشخص میکند که روزهای هفته در محدوده تاریخ مجاز هستند. کاراکترهای معتبر عبارتند از:
هر ترکیب کاراکتری معتبر است. |
| Promotions / HotelPromotions / Promotion / BookingWindow | 0..1 | BookingWindow | مدت زمانی را که رزرو باید نسبت به تاریخ ورود (بر اساس منطقه زمانی ملک) انجام شود، مشخص میکند. برای مثال، میتوان بازه زمانی رزرو را حداقل ۷ روز و حداکثر ۱۸۰ روز قبل از ورود تنظیم کرد. |
| Promotions / HotelPromotions / Promotion / BookingWindow / @min | 0..1 | integer or duration | برای اعمال این پیشنهاد، حداقل مدت زمان قبل از ورود به سیستم هنگام رزرو باید مشخص شود. اگر این مقدار مشخص نشده باشد یا مقدار آن 0 باشد، حداقل زمانی وجود ندارد.انواع مقادیر معتبر عبارتند از:
|
| Promotions / HotelPromotions / Promotion / BookingWindow / @max | 0..1 | integer or duration | حداکثر تعداد روزهای قبل از ورود هنگام رزرو باید انجام شود تا این پیشنهاد اعمال شود. اگر این مقدار مشخص نشده باشد یا مقدار آن 0 باشد، حداکثری وجود ندارد.انواع مقادیر معتبر عبارتند از:
|
| Promotions / HotelPromotions / Promotion / Ceiling | 0..1 | Ceiling | محدودیتهایی را در مورد حداکثر مقداری که یک نرخ میتواند پس از اعمال تخفیفها روی آن تنظیم شود، تعریف میکند. تخفیفها همیشه باید یک اگر چیدمان بر روی هم پیکربندی شده باشد، چندین پیشنهاد ویژه با مثال: قیمتگذاری برای اقامت یک شبه که در آن
ترتیب محاسبه به این صورت است:
این واقعیت که ۶۰ یک سقف کلی سختگیرانهتر است، بیربط است زیرا فقط برای تبلیغات خودش معتبر است و نمیتوان یک سقف واحد داشت که کل مجموعه تبلیغات را در بر بگیرد. |
| Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night | 1 | float | حداکثر مبلغی که میتوان پس از اعمال تخفیف، نرخ هر شب را تعیین کرد. اگر یک عنصر |
| Promotions / HotelPromotions / Promotion / Floor | 0..1 | Floor | محدودیتهایی را در مورد حداقل مقداری که میتوان پس از اعمال تخفیفها برای یک نرخ تعیین کرد، تعریف میکند. تخفیفها همیشه باید یک منطق اگر چیدمان اتاقها (Stacking) پیکربندی شده باشد، میتوان چندین پیشنهاد ویژه با مثال: قیمتگذاری برای اقامت یک شبه که در آن
ترتیب محاسبه به این صورت است:
این واقعیت که ۹۰ یک کف کلی سختگیرانهتر است، بیربط است، زیرا فقط برای تبلیغات خودش معتبر است و هیچ کف واحدی نمیتواند کل مجموعه تبلیغات را در بر بگیرد. |
| Promotions / HotelPromotions / Promotion / Floor / @amount_per_night | 1 | float | حداقل مبلغی که میتوان پس از اعمال تخفیف، نرخ هر شب را تعیین کرد. اگر یک عنصر |
| Promotions / HotelPromotions / Promotion / CheckinDates | 0..1 | CheckinDates | ظرفی برای یک یا چند محدوده تاریخ که مشخص میکند چه زمانی باید ورود انجام شود تا تخفیف اعمال شود. |
| Promotions / HotelPromotions / Promotion / CheckinDates / DateRange | 1..20 | DateRange | یک محدوده تاریخی که مشخص میکند چه زمانی باید ثبت نام انجام شود تا تخفیف اعمال شود. اگر یک یا چند تخفیف را حذف میکنید، این عنصر لازم نیست. فرمت YearlessDate نیز پشتیبانی میشود.
|
| 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" مشخص میکند که روزهای هفته در محدوده تاریخ مجاز هستند. کاراکترهای معتبر عبارتند از:
هر ترکیب کاراکتری معتبر است. |
| Promotions / HotelPromotions / Promotion / CheckoutDates | 0..1 | CheckoutDates | یک ظرف برای یک یا چند محدوده تاریخ که مشخص میکند چه زمانی باید تسویه حساب انجام شود تا این پیشنهاد ویژه اعمال شود. |
| Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange | 1..20 | DateRange | یک محدوده تاریخی که مشخص میکند چه زمانی باید تسویه حساب انجام شود تا تخفیف اعمال شود. اگر یک یا چند تخفیف را حذف میکنید، این عنصر لازم نیست. فرمت YearlessDate نیز پشتیبانی میشود.
|
| 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" مشخص میکند که روزهای هفته در محدوده تاریخ مجاز هستند. کاراکترهای معتبر عبارتند از:
هر ترکیب کاراکتری معتبر است. |
| 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 | دقیقاً یکی از موارد تخفیفی که برای این تبلیغ اعمال میشود را مشخص میکند. |
| Promotions / HotelPromotions / Promotion / Discount / @percentage | 0..1 | float | دقیقاً یکی از یک مقدار اعشاری از ۰ تا ۱۰۰ که درصد تخفیف را مشخص میکند. این مقدار روی مثالها:
|
| Promotions / HotelPromotions / Promotion / Discount / @percentage_of_base | 0..1 | float | دقیقاً یکی از یک مقدار اعشاری از ۰ تا ۱۰۰ که درصد تخفیف پایه را مشخص میکند. مشابه برخلاف مثال:
|
| Promotions / HotelPromotions / Promotion / Discount / @fixed_amount | 0..1 | float | دقیقاً یکی از مبلغ ثابتی که از مجموع نرخهای شبانه مثالها:
|
| Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night | 0..1 | float | دقیقاً یکی از یک تخفیف ثابت برای هر یک از نرخهای شبانه مثالها:
|
| Promotions / HotelPromotions / Promotion / Discount / @fixed_price | 0..1 | float | دقیقاً یکی از اگر نرخهای شبانهی اگر قرار است مثالها:
|
| Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night | 0..1 | float | دقیقاً یکی از اگر نرخهای شبی اگر قرار است اگر مثالها:
|
| Promotions / HotelPromotions / Promotion / Discount / @applied_nights | 0..1 | integer | این فقط باید با تعداد شبهایی که تخفیف به آنها اعمال میشود، از ارزانترین شروع میشود. باید یک عدد صحیح از ۱ تا ۹۹ باشد. در صورت عدم مشخص کردن، تخفیف برای همه شبها اعمال میشود. |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights | 0..1 | FreeNights | تخفیفی را برای شبهای خاصی از اقامت، در صورت رعایت حداقل مدت اقامت، مشخص میکند. در صورت استفاده از این عنصر، ویژگیهای عنصر والد Discount مجاز نیستند. |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights | 1 | integer | تعداد شبهای مورد نیاز برای اعمال تخفیف. هر تخفیف برای بخش جداگانهای از شبهای اقامت اعمال میشود. برای مثال، برای یک اقامت ۱۰ شبه که در آن |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_nights | 1 | integer | تعداد شبهای تخفیفدار در هر بخش از شبهای اقامت. |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage | 1 | float | تخفیفی که برای شبهای تخفیف اعمال میشود. اگر این مقدار 50 باشد، هر شب انتخاب شده ۵۰٪ تخفیف دارد. |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection | 1 | string | باید یا cheapest باشد یا last . اگر last ، شبهای انتهاییِ بخشِ شبهای اقامت شامل تخفیف میشوند. اگر cheapest ، ارزانترین شبهای داخلِ بخشِ شبهای اقامت شامل تخفیف میشوند. |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats | 1 | boolean | آیا تخفیف میتواند برای چندین بخش شب اقامت اعمال شود؟ اگر برای مثال، اگر |
| Promotions / HotelPromotions / Promotion / Discount / @rank | 0..1 | integer | به این ارتقاء یک رتبه اختصاص میدهد و آن را در انتخاب رتبهبندیشده قرار میدهد، که در آن فقط ارتقاء با کمترین رتبه برای اعمال انتخاب میشود. مقادیر باید بین ۱ تا ۹۹ باشند، شامل. اگر چندین ارتقاء رتبه یکسانی داشته باشند، یکی به طور دلخواه انتخاب و اعمال میشود. |
| Promotions / HotelPromotions / Promotion / BestDailyDiscount | 1 | Discount | دقیقاً یکی از موارد تخفیف روزانهای را مشخص میکند که ممکن است برای یک شب اقامت اعمال شود. این در تضاد با هر هتل ممکن است یک گروه واحد از پیشنهادات ویژه داشته باشد که به عنوان «بهترین پیشنهاد روزانه» در نظر گرفته میشوند. این بدان معناست که برای هر شب اقامت، تنها پیشنهاد ویژه «بهترین پیشنهاد روزانه» که واجد شرایط است و بیشترین تخفیف را برای آن شب ارائه میدهد، انتخاب و اعمال میشود. میتوان تخفیف روزانه را با میتوان برای این نوع تخفیف، |
| Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage | 0..1 | float | دقیقاً یکی از یک مقدار اعشاری از ۰ تا ۱۰۰ که درصد تخفیف را مشخص میکند. این مقدار روی مثالها:
|
| Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount | 0..1 | float | دقیقاً یکی از مبلغ ثابتی که از یک نرخ شبانه مثالها:
|
| Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price | 0..1 | float | دقیقاً یکی از اگر نرخ شبی مثالها:
|
| 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 | محفظهای برای قانون نرخ عضویت که یک رابط کاربری خاص را برای تخفیف مرتبط فعال میکند. این عنصر نباید مشخص شود مگر اینکه |
| 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 | یک طرح نرخ را مشخص میکند. یک طرح نرخ با ترکیبی از بسته، نرخها و در دسترس بودن، همانطور که در پیامهای Transaction (Property Data)، OTA_HotelRateAmountNotifRQ و OTA_HotelAvailNotifRQ تعریف شده و توسط PackageID شناسایی میشود، تعریف میشود. |
| Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id | 1 | string | شناسه منحصر به فرد برای طرح نرخ. این مقدار به مقدار PackageID در <PackageData> در یک پیام Transaction (Property Data) و در ویژگی RatePlanCode در <StatusApplicationControl> در هر دو پیام <OTA_HotelRateAmountNotifRQ> و <OTA_HotelAvailNotifRQ> نگاشت میشود. حداکثر تعداد کاراکتر مجاز ۵۰ است. |
| 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> در یک پیام تراکنش (دادههای ویژگی) نگاشت میشود. حداکثر تعداد کاراکترهای مجاز ۵۰ است. |
| Promotions / HotelPromotions / Promotion / Stacking | 0..1 | Stacking | نحوه ترکیب تبلیغات را مشخص میکند. اگر مشخص نشود، "نوع" به صورت base در نظر گرفته میشود. |
| Promotions / HotelPromotions / Promotion / Stacking / @type | 1 | enum | بسته به این تنظیمات، میتوان چندین پیشنهاد ویژه را روی یک نرخ واحد اعمال کرد:
از بین ترکیبات مجاز، مجموعهای از پیشنهادات که بیشترین تخفیف را به همراه دارند، به نرخ اعمال میشوند. |
| Promotions / HotelPromotions / Promotion / StayDates | 0..1 | StayDates | ظرفی برای یک یا چند محدوده تاریخی که نحوه اعمال تبلیغات را تعیین میکند، مانند اعمال تخفیفهای فصلی. |
| Promotions / HotelPromotions / Promotion / StayDates / @application | 1 | enum | نحوه اعمال تبلیغات را شرح میدهد. مقادیر معتبر عبارتند از:
این ویژگی همیشه باید مشخص شود.
|
| Promotions / HotelPromotions / Promotion / StayDates / DateRange | 1..99 | DateRange | یک محدوده تاریخی که تاریخهای اعمال تخفیف را مشخص میکند. فرمت YearlessDate نیز پشتیبانی میشود.
اگر میخواهید محدودهی |
| 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 مشخص نشده باشد، محدوده تاریخ عملاً از تاریخ start به بعد نامحدود است. اگر مقدار |
| Promotions / HotelPromotions / Promotion / StayDates / DateRange / @days_of_week | 0..1 | string | The days of the week that are allowed in the date range. If not specified, all days are allowed in the date range. Each character in the string specifies a day. For example, "MTWHF" specifies that weekdays are allowed in the date range. Valid characters are:
Any character combination is valid. |
| Promotions / HotelPromotions / Promotion / UserCountries | 0..1 | UserCountries | Container for listing the user locations (countries) that are eligible for the promotion. If specified, only eligible users in the listed countries are offered the discounted rate. If not specified, eligible users in any country are offered the discounted rate. |
| Promotions / HotelPromotions / Promotion / UserCountries / @type | 0..1 | enum | The type of UserCountries specification. Valid values are If the UserCountries If the UserCountries If the UserCountries |
| Promotions / HotelPromotions / Promotion / UserCountries / Country | 1..300 | Country | Defines one country where users are eligible for the promotion. |
| Promotions / HotelPromotions / Promotion / UserCountries / Country / @code | 1 | string | A CLDR country code , such as DE or FR . Note that, for some countries, the CLDR country code isn't the same as the 2-letter ISO country code. Also, CLDR region codes are not supported. |
مثالها
There is a limit of 500 promotions per property. Refer to "Delete one promotion" example to remove promotions from a property.
Basic message
The following example shows a basic Promotions message:
<?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>
Inventory condition
The following example shows how to create a discount if there is excess inventory close to the arrival date:
<?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>
Delete one promotion
The following example shows how to delete one promotion for a property:
<?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>
Delete all promotions
The following example shows how to delete all promotions for a property:
<?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>
Overlay all promotions
The following example shows how to overlay <HotelPromotions> for a property with one or more new promotions. When action="overlay" , all stored promotions are deleted prior to storing the promotions specified in the current message:
<?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 Different Stacking Types
The following example shows a case where three different promotions would be applied ( base , second , any ). Note that the none promotion wouldn't be applied since the other promotions provide a better discount. If the original price was $100, the discounted price would be $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 Stacking Type
The following example shows a case where the none promotion is used because the combination of other promotions provides a smaller discount. If the original price was $100, the discounted price would be $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>
Booking Window Duration Bounds
The following example shows a case where the BookingWindow element is used with its start and end bounds defined as an ISO 8601 Duration type. This booking window restriction requires booking on or before 18:00 the day prior to arrival, and on or after 12:00 on the 2nd day before arrival.
<?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>
Booking Dates DateTime Bounds
The following example shows a case where the BookingDates element is used with start and end attributes as DateTime types. This booking date restriction requires booking to occur between 06:30 on 2020-07-01 and 18:45 on 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>
Yearless date ranges
The following example shows a case where the CheckInDates element contains DateRanges that have start and end fields without years. In this example, the promotion applies to check-in dates between 12/29 and 1/2, regardless of the year. Yearless date ranges that cross the new-year boundary are invalid, so the DateRange is expressed as two adjacent date ranges.
<?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 discount
The following example discounts two nights 50% for each four nights stayed for the specified range of booking dates. For a ten night itinerary, a total of four nights would be discounted 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>
The next example discounts one night 50% for each three nights stayed for the specified ranges of stay dates. Only the overlapping nights of stay count towards qualifying for the discount. For the following itinerary with check-in on 2022-01-01 and check-out on 2022-01-07, the qualified nights of stay and discounts are applied as follows.
- 2022-01-01 (stay)
- 2022-01-02 (stay)
- 2022-01-03
- 2022-01-04 (discounted)
- 2022-01-05 (stay)
- 2022-01-06 (stay)
<?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>
Ranked Selection
The following example offers two discounts, one for 20% off and another for 15% off. During evaluation, only the 15% discount is applied because it has a lower rank.
<?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
The following example discounts a two night stay by applying BestDailyDiscount stacked with a 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>
Consider a two night stay from April 30, 2023 to May 2, 2023 For calculation, the combination of best daily discounts that yields the deepest discount is found first.
For the first night, the "general" promotion is the only eligible amount with a fixed discount of 20.
For the second night, the "may" promotion offers a deeper discount than the "general" discount. So, when "may" is selected the fixed discount amount is 50.
Then for the stay, the "fiesta" promotion discounts to 5 per night, or 10 total. It can be stacked with the combination of best daily discounts because "fiesta" has stacking type set to any . If it were set to base , then only the combination of best daily discounts or the "fiesta" discount is applied. See description of Stacking for more information.
`Overall, the price of the stay receives a 20 + 50 + 10 = 80 fixed amount discount.
پاسخها
نحو
The PromotionsResponse message uses the following syntax:
<?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>
Elements and Attributes
The PromotionsResponse message has the following elements and attributes:
| Element / @Attribute | Occurrences | نوع | توضیحات |
|---|---|---|---|
| PromotionsResponse | 1 | Complex element | The root element indicating the success or issues for a received Promotions request message. |
| PromotionsResponse / @timestamp | 1 | DateTime | The creation date and time of this message. |
| PromotionsResponse / @id | 1 | string | The unique identifier from the associated Promotions message. |
| PromotionsResponse / @partner | 1 | string | The partner account for this message. |
| PromotionsResponse / Success | 0..1 | Success | Indicates that the Promotions message was processed successfully without warnings, errors, or failures. Either |
| PromotionsResponse / Issues | 0..1 | Issues | A container for one or more issues encountered while processing the Promotions message. Either |
| PromotionsResponse / Issues / Issue | 1..n | Issue | The description of a warning, error, or failure encountered while processing the Promotions message. Details on these issues can be found in Feed Status Error Messages . |
| PromotionsResponse / Issues / Issue / @code | 1 | integer | The identifier for the issue. |
| PromotionsResponse / Issues / Issue / @status | 1 | enum | The type of issue encountered. Valid values are |
مثالها
موفقیت
The following is a response to a successfully processed Promotions message.
<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="2020-05-18T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Success/>
</PromotionsResponse>
مسائل
The following is a response to a Promotions message not processed due to errors.
<?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>