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 áp dụng chương trình khuyến mãi đủ điều kiện hoặc một nhóm các chương trình khuyến mãi đưa ra mức giá thấp nhất. Nếu bạn đang tìm một API hỗ trợ đ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á. Xin 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 khi áp dụng 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 Chương trình khuyến mãi có các thành phần và thuộc tính sau:
Phần tử / @Thuộc tính | Số lần xuất hiện | Loại | Nội dung 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ư này. Giá trị của 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ó một 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 cho 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 của cơ sở lưu trú. Mỗi chương trình khuyến mãi áp dụng cho một cơ sở lưu trú. Trừ phi bạn sử 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 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ị này phải là Nếu không được chỉ định, mỗi chương trình khuyến mãi được chỉ định trong thông báo hiện tại sẽ:
|
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). |
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ự hợp lệ 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ị này 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 dùng để 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 | Dải ô 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ú), tính cả phạm vi ngày.
|
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ả phạm vi ngày.
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week | 0..1 | string | Ngày trong tuần được phép sử 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 sử dụng trong phạm vi ngày. Mỗi ký tự trong chuỗi chỉ định một ngày. Ví dụ: "MTWHF" cho biết những ngày trong tuần được cho phép 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 | Cho biết khoảng thời gian mà việc đặt phòng phải diễn ra tương ứng 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 trước là ít nhất 7 ngày, nhưng không được 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 khi nhận phòng (khi khách phải đặt phòng) để được hưởng chương trình khuyến mãi. Nếu bạn không chỉ định thuộc tính này hoặc giá trị của thuộc tính này là 0 , thì sẽ không có giá trị 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 thuộc tính 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 đ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ể được đặ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 định cấu hình 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:
Trên thực tế, 60 là mức trần tổng thể nghiêm ngặt hơn không phù hợp vì nó chỉ hợp lệ với chương trình khuyến mãi của chính nó và không thể có mức trần duy nhất nào trải rộng toàn bộ ngăn xếp quảng cáo. |
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night | 1 | float |
Số tiền tối đa mà bạn có thể đặt mức giá mỗi đêm sau khi áp dụng chiết khấu. Nếu cũng chỉ định một 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à bạn 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 định cấu hình 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:
Trên thực tế, 90 là giá sàn tổng thể chặt chẽ hơn là không phù hợp vì giá trị này chỉ hợp lệ với chương trình khuyến mãi của chính nó và không có giá sàn nào trải dài toàn bộ ngăn xếp chương trình 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 mức giá mỗi đêm sau khi áp dụng chiết khấu. Nếu một 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 áp dụng chương trình khuyến mãi. Không bắt buộc phải sử dụng phần tử này nếu bạn đ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 giống với ngày end . Nếu bạn không chỉ định start , phạm vi ngày sẽ không có giới hạn về 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 , phạm vi ngày sẽ không có giới hạn đối với 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 sử 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 sử dụng trong phạm vi ngày. Mỗi ký tự trong chuỗi chỉ định một ngày. Ví dụ: "MTWHF" cho biết những ngày trong tuần được cho phép 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 áp dụng chương trình khuyến mãi. Không bắt buộc phải sử dụng phần tử này nếu bạn đ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 giống với ngày end . Nếu bạn không chỉ định start , phạm vi ngày sẽ không có giới hạn về 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 , phạm vi ngày sẽ không có giới hạn đối với 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 sử 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 sử dụng trong phạm vi ngày. Mỗi ký tự trong chuỗi chỉ định một ngày. Ví dụ: "MTWHF" cho biết những ngày trong tuần được cho phép 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 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 xác định, người dùng đủ điều kiện và đang sử dụng bất kỳ thiết bị nào đều đượ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 tham gia 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 giá trị Cho biết 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 giá trị Một giá trị thập phân từ 0 đến 100 để xác định tỷ lệ 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 giá trị Số tiền cố định sẽ được trừ vào tổng của đơn giá theo đê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 giá trị 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 giá trị Nếu bạn chỉ định giá mỗi đêm là Nếu mục đích của 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 giá trị Nếu bạn chỉ định giá mỗi đêm là Nếu mục đích của Nếu bạn chỉ định Ví dụ:
|
Promotions / HotelPromotions / Promotion / Discount / @applied_nights | 0..1 | integer | Bạn chỉ nên 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à một số nguyên từ 1 đến 99. Nếu bạn không chỉ định, khoản 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 đá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 sử dụng phần tử này. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights | 1 | integer | Số đêm bắt buộc để áp dụng chiết khấu. Mỗi khoản chiết khấu sẽ được áp dụng cho một phân đoạn số đêm lưu trú riêng biệt. 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 phân đoạn số đêm lưu trú. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage | 1 | float | Khoản chiết khấu được áp dụng cho các đêm chiết khấu. Nếu giá trị này là 50 , thì mỗi đêm bạn chọn sẽ được giảm 50%. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection | 1 | string | Phải là cheapest hoặc last . Nếu là last , thì các đêm ở cuối phân đoạn số đêm lưu trú sẽ được chiết khấu. Nếu là cheapest , thì những đêm có giá rẻ nhất trong phân đoạn số đêm lưu trú sẽ được chiết khấu. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats | 1 | boolean | Liệu có thể áp dụng khoản chiết khấu cho những phân khúc đêm lưu trú
nhiều lần hay không. Nếu là Ví dụ: nếu |
Promotions / HotelPromotions / Promotion / Discount / @rank | 0..1 | integer | Chỉ định một thứ hạng cho chương trình khuyến mãi này và đưa chương trình khuyến mãi đó vào lựa chọn theo thứ 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 giá trị Xác định một khoản 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 duy nhất đượ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 hằng ngày" đủ đ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 không thể 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 giá trị Một giá trị thập phân từ 0 đến 100 để xác định tỷ lệ 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 giá trị Số tiền cố định sẽ được 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 giá trị Nếu bạn chỉ định giá mỗi đêm là Ví dụ:
|
Promotions / HotelPromotions / Promotion / InventoryCount | 0..1 | InventoryCount | Xác định các 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 này. Chiết khấu chỉ được áp dụng cho
những đêm đáp ứng quy định hạn chế. Không được áp dụng đối với khoản chiết khấu fixed_amount . Xin lưu ý rằng số lượng phòng trống sẽ đượ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 còn trống tối thiểu phải được dành ra cho chương trình khuyến mãi sẽ được áp dụng cho đơn giá theo đêm. Nếu bạn không xác định giá trị này, thì sẽ không có giá trị tối thiểu. |
Promotions / HotelPromotions / Promotion / InventoryCount / @max | 0..1 | integer | Số lượng phòng còn trống tối đa phải được dành ra cho chương trình khuyến mãi sẽ được áp dụng cho đơn giá theo đê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 thời gian lưu trú mà chương trình khuyến mãi có thể được áp dụng. Chương trình khuyến mãi không được áp dụng khi 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 trong thời gian lưu trú được phép áp dụng chương trình khuyến mãi. 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 / LengthOfStay / @max | 0..1 | integer | Số đêm tối đa trong thời gian lưu trú được phép áp dụng chương trình khuyến mãi. 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 / MembershipRateRule | 0..1 | MembershipRateRule |
Vùng chứa cho một quy tắc giá của thành viên kích hoạt một phiên bản giao diện người dùng cụ thể cho mức chiết khấu được liên kết. 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á phòng tối thiểu của các ngày trong ngày (dùng AmountBeforeTax hoặc AmountAfterTax giá trị lớn hơn) 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 | Bạn phải vượt quá giá trị này để được áp dụng chương trình khuyến mãi. |
Promotions / HotelPromotions / Promotion / Occupancy | 0..1 | Occupancy | Xác định các quy định hạn chế về số người lưu trú được áp dụng chương trình khuyến mãi này. Chương trình khuyến mãi không áp dụng khi số người lưu trú vượt quá giới hạn tối thiểu và tối đa. |
Promotions / HotelPromotions / Promotion / Occupancy / @min | 0..1 | integer | Số người lưu trú do người dùng chỉ định ít nhất phải là giá trị này thì mới được áp dụng chiết khấu. |
Promotions / HotelPromotions / Promotion / Occupancy / @max | 0..1 | integer | Số người lưu trú do người dùng chỉ định phải nằm trong giá trị tối đa này thì mới được áp dụng 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> , chương trình khuyến mãi sẽ áp dụng cho mọi 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á 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ủa cơ sở lưu trú), OTA_HotelRateAmountNotifRQ và OTA_HotelAvailNotifRQ, và được xác định bằng PackageID. |
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id | 1 | string | Giá trị nhận dạng riêng biệt của gói giá. Giá trị này liên kết 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ẽ được á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 tất cả các 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 liên kết 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 | Cho biết cách kết hợp các chương trình khuyến mãi. Nếu không được chỉ định, "type" 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á 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 mang lại mức chiết khấu lớn nhất sẽ được áp dụng cho giá phòng. |
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ư để phù hợp với 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 các ngày mà chương trình khuyến mãi sẽ được áp dụng. Đị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 giống với ngày end . Nếu bạn không chỉ định start , phạm vi ngày sẽ không có giới hạn về 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 , phạm vi ngày sẽ không có giới hạn đối với 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 sử 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 sử dụng trong phạm vi ngày. Mỗi ký tự trong chuỗi chỉ định một ngày. Ví dụ: "MTWHF" cho biết những ngày trong tuần được cho phép 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 xác định, chỉ những người dùng đủ điều kiện ở các quốc gia được liệt kê mới được hưởng mức giá chiết khấu. Nếu không xác định, người dùng đủ điều kiện ở mọi quốc gia đều được hưởng mức giá chiết khấu. |
Promotions / HotelPromotions / Promotion / UserCountries / @type | 0..1 | enum | Loại thông số UserCountry.
Các giá trị hợp lệ là Nếu bạn đặt Nếu Nếu bạn không đặt |
Promotions / HotelPromotions / Promotion / UserCountries / Country | 1..300 | Country | Xác định 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 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 trình bày 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 đây cho thấy cách tạo chiết khấu nếu còn hàng thừa khi đã gần 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 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ả chiến dịch quảng bá
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>
Phủ tất cả chương trình khuyến mãi
Ví dụ sau đây trình bày 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 một trường hợp trong đó ba chương trình khuyến mãi khác nhau sẽ á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 có mức chiết khấu tốt hơn. Nếu giá ban đầu 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ó kiểu xếp chồng
Ví dụ sau đây cho thấy một trường hợp trong đó chương trình khuyến mãi none
được sử dụng vì sự kết hợp của các chương trình khuyến mãi khác cung cấp mức chiết khấu nhỏ hơn. Nếu giá ban đầu 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 lượng đặt trước
Ví dụ sau đây cho thấy một trường hợp trong đó phần tử BookingWindow
được sử dụng với giới hạn bắt đầu và giới hạn kết thúc được xác định là kiểu Thời lượng ISO 8601. Quy định hạn chế về thời hạn đặt phòng này yêu cầu bạn phải đặt phòng 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 phòng theo ngày giờ
Ví dụ sau đây cho thấy một trường hợp mà phần tử BookingDates
được dùng với thuộc tính start
và end
làm loại DateTime. Quy định hạn chế về ngày đặt phòng này yêu cầu bạn phải đặt phòng trong khoảng thời gian từ 06:30 ngày 1 tháng 7 năm 2020 đến 18:45 ngày 2 tháng 7 năm 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 theo năm
Ví dụ sau đây cho thấy một trường hợp trong đó phần tử CheckInDates
chứa DateRanges
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. Phạm vi ngày không theo năm vượt qua ranh giới năm mới là không hợp lệ, vì vậy, DateScope được biểu thị bằng hai phạm vi ngày liền kề.
<?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 chiết khấu 50% cho hai đêm mỗi 4 đêm lưu trú trong phạm vi ngày đặt phòng đã chỉ định. Đối với lịch 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 là chiết khấu 50% cho một đêm đối với mỗi ba đêm lưu trú trong phạm vi ngày lưu trú đã chỉ định. Chỉ các đêm lưu trú trùng lặp mới được tính vào đủ điều kiện hưở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à ngày trả phòng vào ngày 7 tháng 1 năm 2022, số đêm lưu trú đủ điều kiện và khoản chiết khấu sẽ được áp dụng như sau.
- 01-01-2022 (ở lại)
- 2022-01-02 (ở lại)
- 2022-01-03
- 04/01/2022 (đã chiết khấu)
- 05-01-2022 (ở lại)
- 06-01-2022 (ở lạ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">
<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 theo thứ hạng
Ví dụ sau đây đưa ra 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ỉ có chiết khấu 15% được áp dụng vì 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>
BestDailyDiscount
Ví dụ sau đây chiết khấu thời gian lưu trú 2 đêm bằng cách áp dụng BestDailyDiscount
xếp chồng cù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>
Hãy cân nhắ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, trước tiên bạn sẽ tìm thấy tổ hợp các khoản chiết khấu hằng ngày hiệu quả nhất để có được mức chiết khấu sâu nhất.
Đố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ể" mang đến mức chiết khấu sâu hơn so với mức chiết khấu "chung". Vì vậy, khi chọn "có thể", số tiền chiết khấu cố định là 50.
Sau đó, đối với lượt lưu trú, chương trình khuyến mãi "fiesta" sẽ giảm giá còn 5 đêm mỗi đêm, tức là tổng cộng 10. Bạn có thể xếp chồng sự kiện 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" có kiểu xếp chồng được đặt thành any
. Nếu bạn đặt giá trị này thành base
, thì chỉ tổ hợp chiết khấu tốt nhất hằng ngày hoặc chiết khấu "fiesta" mới được áp dụng. Hãy xem nội dung mô tả về Stacking
để biết thêm thông tin.
"Nhìn chung, giá của lượt lưu trú sẽ được chiết khấu theo số tiền cố định là 20 + 50 + 10 = 80.
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 | Nội dung 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 vấn đề. |
PromotionsResponse / @timestamp | 1 | DateTime | Ngày và giờ tạo thông báo này. |
PromotionsResponse / @id | 1 | string | Giá trị 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ư 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 lượt xử lý thất bại.
|
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 gặp phải 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ề các vấn đề này trong Thông báo lỗi về trạng thái 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 vấn đề mà bạn 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 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>