Tổng quan
API này cho phép bạn chỉ định các khoản chiết khấu có thể có. Trong số các chương trình khuyến mãi đã chỉ định, Google sẽ áp dụng chương trình khuyến mãi đủ điều kiện hoặc nhóm chương trình khuyến mãi dẫn đến mức giá thấp nhất. Nếu bạn đang tìm một API hỗ trợ tính năng điều chỉnh mức giá tuỳ ý có thể tăng hoặc giảm giá khi đáp ứng các điều kiện, hãy cân nhắc sử dụng API Sửa đổi giá của chúng tôi. Lưu ý rằng nếu có cả hai API, thì các nội dung sửa đổi giá sẽ được áp dụng trước chương trình khuyến mãi.
Yêu cầu
Cú pháp
Thông báo Promotions sử dụng cú pháp sau:
<?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>
Phần tử và thuộc tính
Thông báo Khuyến mãi có các phần tử và thuộc tính sau:
| Phần tử / @Thuộc tính | Số lần xuất hiện | Loại | Mô tả |
|---|---|---|---|
| Promotions | 1 | Complex element | Thành phần gốc của thông báo khuyến mãi. |
| Promotions / @partner | 1 | string | Tài khoản đối tác dùng cho thông báo này. Giá trị chuỗi này là giá trị của "Khoá đối tác" được liệt kê trên
trang Cài đặt tài khoản trong Hotel Center.
Nếu bạn có phần phụ trợ cung cấp nguồn cấp dữ liệu cho nhiều tài khoản, thì giá trị này cần phải khớp với giá trị thuộc tính |
| Promotions / @id | 1 | string | Giá trị nhận dạng duy nhất của thông báo yêu cầu này. Giá trị này được trả về trong thông báo phản hồi. Các ký tự được phép là a-z, A-Z, 0-9, _ (dấu gạch dưới) và - (dấu gạch ngang). |
| Promotions / @timestamp | 1 | DateTime | Ngày và giờ tạo thông báo này. |
| Promotions / HotelPromotions | 0..n | HotelPromotions | Chương trình khuyến mãi cho cơ sở lưu trú. Mỗi chương trình khuyến mãi sẽ áp dụng cho một cơ sở lưu trú duy nhất. Trừ phi bạn dùng |
| Promotions / HotelPromotions / @hotel_id | 1 | string | Giá trị nhận dạng duy nhất của cơ sở lưu trú. Giá trị này phải khớp với mã khách sạn được chỉ định bằng cách sử dụng phần tử
<id> trong phần tử <listing> của Nguồn cấp dữ liệu danh sách khách sạn. Mã khách sạn cũng có trong Hotel Center. |
| Promotions / HotelPromotions / @action | 0..1 | enum | Nếu được chỉ định, giá trị phải là Nếu không được chỉ định, thì mỗi chương trình khuyến mãi được chỉ định trong thông báo hiện tại sẽ là:
|
| Promotions / HotelPromotions / Promotion | 0..99 | Promotion | Một chương trình khuyến mãi duy nhất cho một cơ sở lưu trú. Xin lưu ý rằng nếu bạn không chỉ định Nếu bạn cần sử dụng hơn 99 chương trình khuyến mãi, hãy liên hệ với Nhà quản lý tài khoản hỗ trợ kỹ thuật (TAM) của bạn. |
| Promotions / HotelPromotions / Promotion / @id | 1 | string | Giá trị nhận dạng duy nhất của chương trình khuyến mãi. Số lượng ký tự tối đa được phép là 40. Các ký tự được phép là a-z, A-Z, 0-9, _ (dấu gạch dưới), - (dấu gạch ngang) và . (dấu chấm). |
| Promotions /HotelPromotions / Promotion / @action | 0..1 | enum | Nếu được chỉ định, giá trị phải là Nếu bạn chỉ định |
| Promotions / HotelPromotions / Promotion / BookingDates | 0..1 | BookingDates | Vùng chứa một hoặc nhiều phạm vi xác định thời điểm phải đặt phòng để được áp dụng chương trình khuyến mãi. |
| Promotions / HotelPromotions / Promotion / BookingDates / DateRange | 1..99 | DateRange | Phạm vi xác định thời điểm phải đặt phòng để được áp dụng chương trình khuyến mãi. |
| Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @start | 0..1 | Date hoặc DateTime | Ngày bắt đầu hoặc ngày giờ (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi.
|
| Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end | 0..1 | Date hoặc DateTime | Ngày kết thúc hoặc ngày giờ (dựa trên múi giờ của cơ sở lưu trú), tính cả 2 ngày này.
|
| Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week | 0..1 | string | Ngày trong tuần được phép dùng trong phạm vi ngày. Nếu bạn không chỉ định, tất cả các ngày đều được phép trong phạm vi ngày. Mỗi ký tự trong chuỗi xác định một ngày. Ví dụ: "MTWHF" cho biết rằng được phép sử dụng các ngày làm việc trong tuần trong phạm vi ngày. Các ký tự hợp lệ là:
Mọi tổ hợp ký tự đều hợp lệ. |
| Promotions / HotelPromotions / Promotion / BookingWindow | 0..1 | BookingWindow | Xác định khoảng thời gian tương ứng với ngày nhận phòng so với ngày nhận phòng (dựa trên múi giờ của cơ sở lưu trú). Ví dụ: bạn có thể đặt thời hạn đặt phòng là ít nhất 7 ngày, nhưng không quá 180 ngày, trước ngày nhận phòng. |
| Promotions / HotelPromotions / Promotion / BookingWindow / @min | 0..1 | integer or duration | Thời gian tối thiểu trước thời điểm nhận phòng khi phải đặt phòng để chương trình khuyến mãi được áp dụng. Nếu bạn không chỉ định giá trị này hoặc giá trị của thuộc tính này là 0, thì sẽ không có giới hạn tối thiểu.
Các loại giá trị hợp lệ là:
|
| Promotions / HotelPromotions / Promotion / BookingWindow / @max | 0..1 | integer or duration | Số ngày tối đa phải đặt phòng trước ngày nhận phòng để được hưởng chương trình khuyến mãi. Nếu bạn không chỉ định giá trị này hoặc giá trị của chỉ số này là 0, thì sẽ không có giới hạn tối đa.
Các loại giá trị hợp lệ là:
|
| Promotions / HotelPromotions / Promotion / Ceiling | 0..1 | Ceiling |
Xác định các quy định hạn chế về giá trị tối đa mà một mức giá có thể đặt sau khi áp dụng chương trình khuyến mãi. Chương trình khuyến mãi phải luôn chỉ định Nếu bạn thiết lập tính năng xếp chồng, thì nhiều chương trình khuyến mãi có Ví dụ: Giá cho 1 đêm lưu trú trong đó
Sau đây là thứ tự tính toán:
Thực tế, 60 là mức trần tổng thể nghiêm ngặt hơn là không phù hợp vì chỉ áp dụng cho chương trình khuyến mãi riêng và không thể có một mức trần duy nhất nào trải rộng ra toàn bộ ngăn xếp chương trình khuyến mãi. |
| Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night | 1 | float |
Số tiền tối đa mà bạn có thể đặt giá mỗi đêm sau khi áp dụng chiết khấu. Nếu cũng chỉ định phần tử
|
| Promotions / HotelPromotions / Promotion / Floor | 0..1 | Floor |
Xác định các quy định hạn chế về giá trị tối thiểu mà một mức giá có thể đặt sau khi áp dụng chương trình khuyến mãi. Chương trình khuyến mãi phải luôn chỉ định Logic Nếu bạn thiết lập tính năng xếp chồng, thì nhiều chương trình khuyến mãi có Ví dụ: Giá cho 1 đêm lưu trú trong đó
Sau đây là thứ tự tính toán:
Thực tế là 90 là giá sàn tổng thể nghiêm ngặt hơn vì giá trị này chỉ hợp lệ cho chương trình khuyến mãi riêng và không thể có một giá sàn duy nhất trong toàn bộ hệ thống khuyến mãi. |
| Promotions / HotelPromotions / Promotion / Floor / @amount_per_night | 1 | float |
Số tiền tối thiểu mà bạn có thể đặt giá mỗi đêm sau khi áp dụng chiết khấu. Nếu cũng chỉ định phần tử
|
| Promotions / HotelPromotions / Promotion / CheckinDates | 0..1 | CheckinDates | Vùng chứa một hoặc nhiều phạm vi ngày dùng để xác định thời điểm phải nhận phòng để được áp dụng chương trình khuyến mãi. |
| Promotions / HotelPromotions / Promotion / CheckinDates / DateRange | 1..20 | DateRange | Phạm vi ngày xác định thời điểm phải nhận phòng để được hưởng chương trình khuyến mãi. Bạn không cần dùng phần tử này nếu đang xoá một hoặc nhiều chương trình khuyến mãi. Định dạng YearlessDate cũng được hỗ trợ.
|
| Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @start | 0..1 | Date or YearlessDate | Ngày bắt đầu (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trước hoặc trùng với ngày end. Nếu bạn không chỉ định start, thì phạm vi ngày sẽ không giới hạn nếu tính theo ngày bắt đầu. |
| Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @end | 0..1 | Date or YearlessDate | Ngày kết thúc (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trùng hoặc sau ngày start. Nếu bạn không chỉ định end, thì phạm vi ngày sẽ không giới hạn khi có ngày kết thúc. |
| Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @days_of_week | 0..1 | string | Ngày trong tuần được phép dùng trong phạm vi ngày. Nếu bạn không chỉ định, tất cả các ngày đều được phép trong phạm vi ngày. Mỗi ký tự trong chuỗi xác định một ngày. Ví dụ: "MTWHF" cho biết rằng được phép sử dụng các ngày làm việc trong tuần trong phạm vi ngày. Các ký tự hợp lệ là:
Mọi tổ hợp ký tự đều hợp lệ. |
| Promotions / HotelPromotions / Promotion / CheckoutDates | 0..1 | CheckoutDates | Vùng chứa một hoặc nhiều phạm vi ngày dùng để xác định thời điểm phải trả phòng để được áp dụng chương trình khuyến mãi. |
| Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange | 1..20 | DateRange | Phạm vi ngày xác định thời điểm phải trả phòng để được hưởng chương trình khuyến mãi. Bạn không cần dùng phần tử này nếu đang xoá một hoặc nhiều chương trình khuyến mãi. Định dạng YearlessDate cũng được hỗ trợ.
|
| Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @start | 0..1 | Date or YearlessDate | Ngày bắt đầu (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trước hoặc trùng với ngày end. Nếu bạn không chỉ định start, thì phạm vi ngày sẽ không giới hạn nếu tính theo ngày bắt đầu. |
| Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @end | 0..1 | Date or YearlessDate | Ngày kết thúc (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trùng hoặc sau ngày start. Nếu bạn không chỉ định end, thì phạm vi ngày sẽ không giới hạn khi có ngày kết thúc. |
| Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @days_of_week | 0..1 | string | Ngày trong tuần được phép dùng trong phạm vi ngày. Nếu bạn không chỉ định, tất cả các ngày đều được phép trong phạm vi ngày. Mỗi ký tự trong chuỗi xác định một ngày. Ví dụ: "MTWHF" cho biết rằng được phép sử dụng các ngày làm việc trong tuần trong phạm vi ngày. Các ký tự hợp lệ là:
Mọi tổ hợp ký tự đều hợp lệ. |
| Promotions / HotelPromotions / Promotion / Devices | 0..1 | Devices | Vùng chứa để liệt kê các thiết bị của người dùng đủ điều kiện tham gia chương trình khuyến mãi. Nếu được xác định, chỉ những người dùng đủ điều kiện và đang sử dụng các thiết bị trong danh sách mới được hưởng mức giá chiết khấu. Nếu không chỉ định, người dùng đủ điều kiện và sử dụng mọi thiết bị sẽ được hưởng mức giá chiết khấu. |
| Promotions / HotelPromotions / Promotion / Devices / Device | 1..3 | Device | Xác định một loại thiết bị của người dùng đủ điều kiện cho chương trình khuyến mãi. |
| Promotions / HotelPromotions / Promotion / Devices / Device / @type | 1 | enum | Một loại thiết bị. Giá trị phải là desktop, tablet hoặc mobile. |
| Promotions / HotelPromotions / Promotion / Discount | 1 | Discount | Bạn phải chỉ định chính xác một trong hai trong số Xác định mức chiết khấu sẽ áp dụng cho chương trình khuyến mãi này. |
| Promotions / HotelPromotions / Promotion / Discount / @percentage | 0..1 | float | Bạn phải cung cấp chính xác một trong các thuộc tính Giá trị thập phân từ 0 đến 100 để xác định mức chiết khấu theo phần trăm.
Giá trị này được áp dụng cho Ví dụ:
|
| Promotions / HotelPromotions / Promotion / Discount / @fixed_amount | 0..1 | float | Bạn phải cung cấp chính xác một trong các thuộc tính Số tiền cố định sẽ được trừ vào tổng của
đơn giá mỗi đêm Ví dụ:
|
| Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night | 0..1 | float | Bạn phải cung cấp chính xác một trong các thuộc tính Một mức chiết khấu cố định được áp dụng cho từng mức giá mỗi đêm Ví dụ:
|
| Promotions / HotelPromotions / Promotion / Discount / @fixed_price | 0..1 | float | Bạn phải cung cấp chính xác một trong các thuộc tính Nếu bạn chỉ định giá mỗi đêm Nếu Ví dụ:
|
| Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night | 0..1 | float | Bạn phải cung cấp chính xác một trong các thuộc tính Nếu bạn chỉ định giá mỗi đêm Nếu Nếu bạn chỉ định Ví dụ:
|
| Promotions / HotelPromotions / Promotion / Discount / @applied_nights | 0..1 | integer | Bạn chỉ nên sử dụng thuộc tính này với Số đêm được áp dụng chiết khấu, bắt đầu bằng đêm có giá thấp nhất. Phải là số nguyên từ 1 đến 99. Nếu bạn không chỉ định, mức chiết khấu sẽ được áp dụng cho tất cả các đêm. |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights | 0..1 | FreeNights | Xác định mức chiết khấu cho một số đêm lưu trú nhất định khi người dùng đáp ứng thời gian lưu trú tối thiểu. Bạn không được phép sử dụng các thuộc tính trên phần tử Discount mẹ nếu phần tử này được sử dụng. |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights | 1 | integer | Số đêm cần thiết để áp dụng chiết khấu. Mỗi mức chiết khấu sẽ được áp dụng cho một giai đoạn riêng biệt của số đêm lưu trú. Ví dụ: đối với thời gian lưu trú 10 đêm, trong đó |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_nights | 1 | integer | Số đêm chiết khấu trong mỗi giai đoạn của số đêm lưu trú. |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage | 1 | float | Ưu đãi chiết khấu được áp dụng cho những đêm được giảm giá. Nếu giá trị này là 50, thì mỗi đêm đã chọn sẽ được giảm giá 50%. |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection | 1 | string | Phải là cheapest hoặc last. Nếu
last, thì những đêm ở cuối giai đoạn lưu trú
sẽ được giảm giá. Nếu giá cheapest, thì những đêm rẻ nhất trong phân đoạn số đêm lưu trú sẽ được giảm giá. |
| Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats | 1 | boolean | Liệu có thể áp dụng chiết khấu cho nhiều chặng lưu trú qua đêm hay không. Nếu giá là Ví dụ: nếu |
| Promotions / HotelPromotions / Promotion / Discount / @rank | 0..1 | integer | Chỉ định chương trình khuyến mãi này một thứ hạng và đưa nó vào lựa chọn xếp hạng, trong đó chỉ chương trình khuyến mãi có thứ hạng thấp nhất mới được chọn để áp dụng. Giá trị phải nằm trong khoảng từ 1 đến 99. Nếu nhiều chương trình khuyến mãi có cùng thứ hạng, thì một chương trình khuyến mãi sẽ được chọn và áp dụng tuỳ ý. |
| Promotions / HotelPromotions / Promotion / BestDailyDiscount | 1 | Discount | Bạn phải chỉ định chính xác một trong hai trong số Xác định một mức chiết khấu hằng ngày có thể áp dụng cho một đêm lưu trú. Điều này trái ngược với Mỗi cơ sở lưu trú có thể có một nhóm chương trình khuyến mãi được coi là "tốt nhất hằng ngày". Điều này có nghĩa là đối với mỗi đêm lưu trú, chương trình khuyến mãi "tốt nhất trong ngày" duy nhất đủ điều kiện và mang lại mức chiết khấu cao nhất cho đêm đó sẽ được chọn và có thể được áp dụng. Bạn có thể không chỉ định Bạn có thể chỉ định |
| Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage | 0..1 | float | Bạn phải cung cấp chính xác một trong các thuộc tính Giá trị thập phân từ 0 đến 100 để xác định mức chiết khấu theo phần trăm.
Giá trị này được áp dụng cho Ví dụ:
|
| Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount | 0..1 | float | Bạn phải cung cấp chính xác một trong các thuộc tính Số tiền cố định sẽ bị trừ vào một mức giá mỗi đêm Ví dụ:
|
| Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price | 0..1 | float | Bạn phải cung cấp chính xác một trong các thuộc tính Nếu bạn chỉ định giá mỗi đêm Ví dụ:
|
| Promotions / HotelPromotions / Promotion / InventoryCount | 0..1 | InventoryCount | Xác định quy định hạn chế về số lượng phòng phải còn trống để được áp dụng chương trình khuyến mãi. Ưu đãi giảm giá chỉ được áp dụng cho
những đêm đáp ứng quy định ràng buộc. Không được áp dụng với mức chiết khấu fixed_amount. Xin lưu ý rằng số lượng phòng còn trống
được chỉ định bằng
OTA_HotelInvCountNotifRQ (InvCount)
hoặc OTA_HotelAvailNotifRQ
(BookingLimit). |
| Promotions / HotelPromotions / Promotion / InventoryCount / @min | 0..1 | integer | Số lượng phòng tối thiểu phải còn trống để được hưởng chương trình khuyến mãi sẽ được áp dụng cho giá mỗi đêm. Nếu bạn không xác định giá trị này, thì sẽ không có giới hạn tối thiểu. |
| Promotions / HotelPromotions / Promotion / InventoryCount / @max | 0..1 | integer | Số lượng phòng tối đa phải còn trống để được hưởng chương trình khuyến mãi sẽ được áp dụng cho giá mỗi đêm. Nếu bạn không xác định giá trị này, thì sẽ không có giới hạn tối đa. |
| Promotions / HotelPromotions / Promotion / LengthOfStay | 0..1 | LengthOfStay | Xác định giới hạn của thời gian lưu trú để có thể áp dụng chương trình khuyến mãi. Chương trình khuyến mãi sẽ không được áp dụng nếu thời gian lưu trú nằm ngoài giới hạn tối thiểu và giới hạn tối đa. |
| Promotions / HotelPromotions / Promotion / LengthOfStay / @min | 0..1 | integer | Số đêm tối thiểu được phép trong thời gian lưu trú để được hưởng chương trình khuyến mãi. Nếu bạn không chỉ định giá trị này, thì sẽ không có giới hạn tối thiểu. |
| Promotions / HotelPromotions / Promotion / LengthOfStay / @max | 0..1 | integer | Số đêm tối đa được phép trong thời gian lưu trú để được hưởng chương trình khuyến mãi. Nếu bạn không chỉ định giá trị này, thì sẽ không có giới hạn tối đa. |
| Promotions / HotelPromotions / Promotion / MembershipRateRule | 0..1 | MembershipRateRule |
Vùng chứa quy tắc giá thành viên sẽ kích hoạt một phiên bản giao diện người dùng cụ thể cho khoản chiết khấu tương ứng. Bạn không nên chỉ định phần tử này trừ phi bạn cũng đã chỉ định |
| Promotions / HotelPromotions / Promotion / MembershipRateRule / @id | 1 | string |
Mã của quy tắc giá liên kết với một chương trình thành viên. |
| Promotions / HotelPromotions / Promotion / MinimumAmount | 0..1 | MinimumAmount | Xác định tổng giá trị tối thiểu của giá phòng hằng ngày (sử dụng giá trị lớn hơn là AmountBeforeTax hoặc AmountAfterTax) mà bạn phải vượt quá để được áp dụng chương trình khuyến mãi. |
| Promotions / HotelPromotions / Promotion / MinimumAmount / @before_discount | 1 | integer | Giá trị phải vượt quá thì chương trình khuyến mãi mới được áp dụng. |
| Promotions / HotelPromotions / Promotion / Occupancy | 0..1 | Occupancy | Xác định các quy định hạn chế về sức chứa được áp dụng chương trình khuyến mãi này. Chương trình khuyến mãi sẽ không được áp dụng khi số người lưu trú nằm ngoài giới hạn tối thiểu và tối đa. |
| Promotions / HotelPromotions / Promotion / Occupancy / @min | 0..1 | integer | Sức chứa do người dùng chỉ định tối thiểu phải bằng giá trị này thì mới được áp dụng mức chiết khấu. |
| Promotions / HotelPromotions / Promotion / Occupancy / @max | 0..1 | integer | Sức chứa do người dùng chỉ định phải có giá trị tối đa bằng giá trị này thì mới được áp dụng mức chiết khấu. |
| Promotions / HotelPromotions / Promotion / RatePlans | 0..1 | RatePlans | Vùng chứa danh sách các gói giá được áp dụng chương trình khuyến mãi.
Nếu bạn không chỉ định <RatePlans>, thì chương trình khuyến mãi sẽ áp dụng cho tất cả gói giá. |
| Promotions / HotelPromotions / Promotion / RatePlans / RatePlan | 1..n | RatePlan | Xác định một gói giá. Gói giá được xác định bằng tổ hợp gói giá, giá và tình trạng phòng, như xác định trong các thông báo Giao dịch (Dữ liệu cơ sở lưu trú), OTA_HotelRateAmountNotifRQ và OTA_HotelAvailNotifRQ, đồng thời được xác định bằng PackageID. |
| Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id | 1 | string | Giá trị nhận dạng duy nhất của gói giá. Giá trị này tương ứng với giá trị PackageID trong <PackageData> trong thông báo Giao dịch (Dữ liệu của cơ sở lưu trú) và trong thuộc tính RatePlanCode của <StatusApplicationControl> trong cả thông báo <OTA_HotelRateAmountNotifRQ> và <OTA_HotelAvailNotifRQ>.
Số lượng ký tự tối đa được phép là 50. |
| Promotions / HotelPromotions / Promotion / RoomTypes | 0..1 | RoomTypes | Vùng chứa danh sách các loại phòng được áp dụng chương trình khuyến mãi.
Chương trình khuyến mãi sẽ áp dụng cho từng <RoomType> được chỉ định. Nếu bạn không chỉ định <RoomTypes>, chương trình khuyến mãi sẽ áp dụng cho mọi phòng. |
| Promotions / HotelPromotions / Promotion / RoomTypes / RoomType | 1..n | RoomType | Xác định một loại phòng. Loại phòng được xác định trong phần tử <RoomData> của thông báo Giao dịch (Dữ liệu của cơ sở lưu trú) và được tham chiếu bằng giá trị <RoomID>. (Giá trị <RoomID> cũng được thuộc tính InvTypeCode trong các thông báo OTA_HotelRateAmountNotifRQ tham chiếu.) |
| Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id | 1 | string | Giá trị nhận dạng duy nhất của quỹ phòng (loại phòng). Giá trị này tương ứng với <RoomID> trong thông báo Giao dịch (Dữ liệu của cơ sở lưu trú).
Số lượng ký tự tối đa được phép là 50. |
| Promotions / HotelPromotions / Promotion / Stacking | 0..1 | Stacking | Xác định cách kết hợp các chương trình khuyến mãi. Nếu không chỉ định, thì "loại" sẽ được giả định là base. |
| Promotions / HotelPromotions / Promotion / Stacking / @type | 1 | enum | Bạn có thể áp dụng nhiều chương trình khuyến mãi cho một mức giá duy nhất tuỳ thuộc vào chế độ cài đặt này:
Trong số các cách kết hợp được phép, tập hợp các chương trình khuyến mãi tạo ra mức chiết khấu lớn nhất sẽ được áp dụng cho giá. |
| Promotions / HotelPromotions / Promotion / StayDates | 0..1 | StayDates | Vùng chứa một hoặc nhiều phạm vi ngày dùng để xác định cách áp dụng chương trình khuyến mãi, chẳng hạn như để áp dụng các khoản chiết khấu theo mùa. |
| Promotions / HotelPromotions / Promotion / StayDates / @application | 1 | enum | Mô tả cách áp dụng chương trình khuyến mãi. Các giá trị hợp lệ là:
Thuộc tính này phải luôn được chỉ định.
|
| Promotions / HotelPromotions / Promotion / StayDates / DateRange | 1..99 | DateRange | Phạm vi ngày xác định những ngày áp dụng chương trình khuyến mãi. Định dạng YearlessDate cũng được hỗ trợ.
|
| Promotions / HotelPromotions / Promotion / StayDates / DateRange / @start | 0..1 | Date or YearlessDate | Ngày bắt đầu (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trước hoặc trùng với ngày end. Nếu bạn không chỉ định start, thì phạm vi ngày sẽ không giới hạn nếu tính theo ngày bắt đầu. |
| Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end | 0..1 | Date or YearlessDate | Ngày kết thúc (dựa trên múi giờ của cơ sở lưu trú) trong phạm vi ngày. Ngày này phải trùng hoặc sau ngày start. Nếu bạn không chỉ định end, thì phạm vi ngày sẽ không giới hạn khi có ngày kết thúc. |
| Promotions / HotelPromotions / Promotion / StayDates / DateRange / @days_of_week | 0..1 | string | Ngày trong tuần được phép dùng trong phạm vi ngày. Nếu bạn không chỉ định, tất cả các ngày đều được phép trong phạm vi ngày. Mỗi ký tự trong chuỗi xác định một ngày. Ví dụ: "MTWHF" cho biết rằng được phép sử dụng các ngày làm việc trong tuần trong phạm vi ngày. Các ký tự hợp lệ là:
Mọi tổ hợp ký tự đều hợp lệ. |
| Promotions / HotelPromotions / Promotion / UserCountries | 0..1 | UserCountries | Vùng chứa để liệt kê vị trí của người dùng (quốc gia) đủ điều kiện tham gia chương trình khuyến mãi. Nếu được chỉ định, chỉ những người dùng đủ điều kiện ở các quốc gia trong danh sách mới được hưởng mức giá chiết khấu. Nếu không chỉ định, người dùng đủ điều kiện ở bất kỳ quốc gia nào đều được cung cấp mức giá chiết khấu. |
| Promotions / HotelPromotions / Promotion / UserCountries / @type | 0..1 | enum | Loại đặc tả UserCountry.
Các giá trị hợp lệ là Nếu bạn đặt Nếu Nếu bạn không đặt Usercountries |
| Promotions / HotelPromotions / Promotion / UserCountries / Country | 1..300 | Country | Xác định một quốc gia nơi người dùng đủ điều kiện hưởng chương trình khuyến mãi. |
| Promotions / HotelPromotions / Promotion / UserCountries / Country / @code | 1 | string | Mã quốc gia theo CLDR, chẳng hạn như DE hoặc FR. Xin lưu ý rằng đối với một số quốc gia, mã quốc gia theo CLDR không giống với mã quốc gia gồm 2 chữ cái theo tiêu chuẩn ISO. Ngoài ra, mã vùng CLDR không được hỗ trợ. |
Ví dụ
Thông báo cơ bản
Ví dụ sau đây thể hiện một thông báo Promotions cơ bản:
<?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>
Tình trạng quỹ phòng
Ví dụ sau cho biết cách tạo chiết khấu nếu có hàng tồn kho vượt quá ngày đến:
<?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>
Xoá một chương trình khuyến mãi
Ví dụ sau đây trình bày cách xoá một chương trình khuyến mãi của một cơ sở lưu trú:
<?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>
Xoá tất cả chương trình khuyến mãi
Ví dụ sau đây trình bày cách xoá tất cả chương trình khuyến mãi của một cơ sở lưu trú:
<?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>
Lớp phủ tất cả chương trình khuyến mãi
Ví dụ sau cho biết cách phủ <HotelPromotions> cho một cơ sở lưu trú có một hoặc nhiều chương trình khuyến mãi mới. Khi action="overlay", tất cả chương trình khuyến mãi đã lưu trữ sẽ bị xoá trước khi lưu trữ chương trình khuyến mãi được chỉ định trong thông báo hiện tại:
<?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 kiểu xếp chồng
Ví dụ sau đây cho thấy trường hợp có 3 chương trình khuyến mãi khác nhau sẽ được áp dụng (base, second, any). Xin lưu ý rằng chương trình khuyến mãi none sẽ không được áp dụng vì các chương trình khuyến mãi khác sẽ có mức chiết khấu thấp hơn. Nếu giá gốc là 100 USD, thì giá chiết khấu sẽ là 72,90 USD.
<?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>
Không có loại xếp chồng nào
Ví dụ sau đây cho thấy một trường hợp chương trình khuyến mãi none được sử dụng vì việc kết hợp các chương trình khuyến mãi khác sẽ mang đến mức chiết khấu nhỏ hơn. Nếu giá gốc là 100 USD, thì giá chiết khấu sẽ là 75 USD.
<?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>
Giới hạn thời hạn đặt trước
Ví dụ sau đây cho thấy trường hợp phần tử BookingWindow được sử dụng với ranh giới bắt đầu và kết thúc được xác định là loại Thời lượng ISO 8601. Theo quy định hạn chế về thời hạn đặt trước này, bạn phải đặt vé vào hoặc trước 18:00 của ngày trước khi đến và vào hoặc sau 12:00 của ngày thứ 2 trước khi đến.
<?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>
Giới hạn ngày đặt trước
Ví dụ sau đây cho thấy trường hợp phần tử BookingDates được sử dụng với các thuộc tính start và end dưới dạng loại DateTime. Theo quy định hạn chế về ngày đặt phòng này, việc đặt phòng phải diễn ra trong khoảng thời gian từ 06:30 ngày 1/7/2020 đến 18:45 ngày 2/7/2020.
<?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>
Phạm vi ngày không có năm
Ví dụ sau đây cho thấy trường hợp phần tử CheckInDates chứa DateRanges có các trường start và end không có năm. Trong ví dụ này, chương trình khuyến mãi áp dụng cho ngày nhận phòng từ ngày 29/12 đến ngày 2/1, bất kể năm nào. Các phạm vi ngày không có năm vượt qua ranh giới năm mới là không hợp lệ, vì vậy, Phạm vi ngày được biểu thị dưới dạng hai phạm vi ngày liền nhau.
<?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>
Giảm giá FreeNights
Ví dụ sau đây giảm 50% phí cho 2 đêm cho mỗi 4 đêm đã lưu trú trong phạm vi ngày đặt phòng được chỉ định. Đối với hành trình 10 đêm, tổng cộng 4 đêm sẽ được giảm giá 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>
Ví dụ tiếp theo sẽ giảm giá 50% cho một đêm cho mỗi 3 đêm lưu trú trong phạm vi ngày lưu trú đã chỉ định. Chỉ những đêm lưu trú trùng lặp mới được tính vào điều kiện áp dụng chiết khấu. Đối với hành trình sau đây có ngày nhận phòng vào ngày 1 tháng 1 năm 2022 và trả phòng vào ngày 7 tháng 1 năm 2022, số đêm lưu trú đủ điều kiện và các khoản chiết khấu sẽ được áp dụng như sau.
- 2022-01-01 (lưu trú)
- 2022-01-02 (lưu trú)
- 2022-01-03
- 04-01-2022 (giảm giá)
- 2022-01-05 (lưu trú)
- 2022-01-06 (lưu trú)
<?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>
Lựa chọn đã xếp hạng
Ví dụ sau đây có hai mức chiết khấu, một là giảm 20% và một là giảm 15%. Trong quá trình đánh giá, chỉ mức chiết khấu 15% được áp dụng vì nó có thứ hạng thấp hơn.
<?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>
Giảm giá hàng ngày tốt nhất
Ví dụ sau đây chiết khấu cho thời gian lưu trú hai đêm bằng cách áp dụng BestDailyDiscount xếp chồng với 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>
Cân nhắc việc lưu trú 2 đêm từ ngày 30 tháng 4 năm 2023 đến ngày 2 tháng 5 năm 2023. Để tính toán, chúng tôi sẽ tìm thấy tổ hợp các khoản chiết khấu hằng ngày tốt nhất để mang lại mức chiết khấu cao nhất trước tiên.
Đối với đêm đầu tiên, chương trình khuyến mãi "chung" là số tiền duy nhất đủ điều kiện với mức chiết khấu cố định là 20.
Đối với đêm thứ hai, chương trình khuyến mãi "có thể" giảm giá sâu hơn so với chiết khấu "chung". Vì vậy, khi bạn chọn "có thể", số tiền chiết khấu cố định là 50.
Sau đó, đối với thời gian lưu trú, chương trình khuyến mãi "fiesta" giảm giá xuống còn 5 người mỗi đêm, hoặc
tổng cộng 10 phòng. Bạn có thể xếp chồng các gói này với tổ hợp các khoản chiết khấu hằng ngày tốt nhất vì "fiesta" đã đặt kiểu xếp chồng thành any. Nếu bạn đặt giá trị này thành base, thì chỉ có tổ hợp các khoản chiết khấu hằng ngày tốt nhất hoặc mức chiết khấu "fiesta" mới được áp dụng. Hãy xem nội dung mô tả của Stacking để biết thêm thông tin.
`Tổng thể, giá của lượt lưu trú nhận được khoản chiết khấu 20 + 50 + 10 = 80 số tiền cố định.
Phản hồi
Cú pháp
Thông báo PromotionsResponse sử dụng cú pháp sau:
<?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>
Phần tử và thuộc tính
Thông báo PromotionsResponse có các phần tử và thuộc tính như sau:
| Phần tử / @Thuộc tính | Số lần xuất hiện | Loại | Mô tả |
|---|---|---|---|
| PromotionsResponse | 1 | Complex element | Phần tử gốc cho biết thông báo yêu cầu Chương trình khuyến mãi nhận được đã thành công hay gặp lỗi. |
| PromotionsResponse / @timestamp | 1 | DateTime | Ngày và giờ tạo thông báo này. |
| PromotionsResponse / @id | 1 | string | Mã nhận dạng duy nhất lấy từ thông báo Chương trình khuyến mãi được liên kết. |
| PromotionsResponse / @partner | 1 | string | Tài khoản đối tác dùng cho thông báo này. |
| PromotionsResponse / Success | 0..1 | Success | Cho biết rằng thông báo Chương trình khuyến mãi đã được xử lý thành công
mà không có cảnh báo, lỗi hoặc xử lý hỏng.
|
| PromotionsResponse / Issues | 0..1 | Issues | Vùng chứa một hoặc nhiều vấn đề gặp phải trong quá trình xử lý thông báo Chương trình khuyến mãi.
|
| PromotionsResponse / Issues / Issue | 1..n | Issue | Nội dung mô tả về cảnh báo, lỗi hoặc lỗi xảy ra trong quá trình xử lý thông báo Chương trình khuyến mãi. Bạn có thể xem thông tin chi tiết về những vấn đề này trong Thông báo lỗi về trạng thái của nguồn cấp dữ liệu. |
| PromotionsResponse / Issues / Issue / @code | 1 | integer | Giá trị nhận dạng của vấn đề. |
| PromotionsResponse / Issues / Issue / @status | 1 | enum | Loại sự cố đã gặp phải. Các giá trị hợp lệ là |
Ví dụ
Thành công
Dưới đây là phản hồi cho một thông báo Chương trình khuyến mãi được xử lý thành công.
<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="2020-05-18T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Success/>
</PromotionsResponse>
Vấn đề
Dưới đây là phản hồi cho một thông báo Chương trình khuyến mãi không được xử lý do lỗi.
<?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>