Przegląd
Ten interfejs API pozwala określić możliwe rabaty. Spośród określonych promocji Google stosuje kwalifikującą się promocję lub zestaw promocji, które prowadzą do najniższej ceny. Jeśli szukasz interfejsu API, który obsługuje dowolne dostosowania stawki, które mogą zwiększać lub zmniejszać cenę przy spełnionych warunkach, rozważ użycie interfejsu Rate Modifications API. Pamiętaj, że jeśli dostępne są oba interfejsy API, zmiany stawek są stosowane przed promocjami.
Żądania
Składnia
Komunikat Promotions
ma taką składnię:
<?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>
Elementy i atrybuty
Wiadomość z promocjami składa się z tych elementów i atrybutów:
Element / @Atrybut | Wystąpienia | Typ | Opis |
---|---|---|---|
Promotions | 1 | Complex element | Główny element komunikatu promocyjnego. |
Promotions / @partner | 1 | string | Konto partnera, z którego pochodzi ta wiadomość. Ta wartość ciągu znaków to wartość „Klucz partnera” podana na
stronie Ustawienia konta w Hotel Center.
Jeśli masz backend, który udostępnia pliki danych dla wielu kont, ta wartość musi odpowiadać wartości atrybutu |
Promotions / @id | 1 | string | Unikalny identyfikator tej wiadomości z żądaniem. Ta wartość jest zwracana w wiadomości z odpowiedzią. Dozwolone znaki to a–z, A–Z, 0–9, _ (podkreślenie) i - (łącznik). |
Promotions / @timestamp | 1 | DateTime | Data i godzina utworzenia tej wiadomości. |
Promotions / HotelPromotions | 0..n | HotelPromotions | Promocje obiektu. Każda promocja dotyczy 1 usługi. Jeśli nie korzystasz z atrybutu |
Promotions / HotelPromotions / @hotel_id | 1 | string | Unikalny identyfikator usługi. Ta wartość musi być zgodna z identyfikatorem hotelu podanym za pomocą
<id> w elemencie <listing> w pliku danych z listą hoteli. Identyfikator hotelu jest też podany w Hotel Center. |
Promotions / HotelPromotions / @action | 0..1 | enum | Jeśli została określona, wartość musi wynosić Jeśli nie podasz tu żadnej promocji, każda promocja określona w bieżącym komunikacie będzie miała jeden z tych typów:
|
Promotions / HotelPromotions / Promotion | 0..99 | Promotion | Pojedyncza promocja obiektu. Pamiętaj, że jeśli nie określono właściwości Jeśli chcesz użyć więcej niż 99 promocji, skontaktuj się z technicznym menedżerem konta (TAM). |
Promotions / HotelPromotions / Promotion / @id | 1 | string | Unikalny identyfikator promocji. Maksymalna dozwolona liczba znaków to 40. Dozwolone znaki to a–z, A–Z, 0–9, _ (podkreślenie), - (łącznik) i . (kropka). |
Promotions /HotelPromotions / Promotion / @action | 0..1 | enum | Jeśli została określona, wartość musi wynosić Jeśli podasz |
Promotions / HotelPromotions / Promotion / BookingDates | 0..1 | BookingDates | Kontener na co najmniej 1 zakres, który określa, kiedy nastąpi rezerwacja, by promocja mogła zostać zastosowana. |
Promotions / HotelPromotions / Promotion / BookingDates / DateRange | 1..99 | DateRange | Zakres określający, kiedy wymagana jest rezerwacja, aby promocja została zastosowana. |
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @start | 0..1 | Date lub DateTime | Data rozpoczęcia lub data i godzina (na podstawie strefy czasowej usługi) włącznie z zakresem.
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end | 0..1 | Date lub DateTime | Data końcowa lub data i godzina (na podstawie strefy czasowej usługi) włącznie z zakresem.
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week | 0..1 | string | Dni tygodnia, które są dozwolone w zakresie dat. Jeśli go nie podasz, dozwolone będą wszystkie dni w zakresie dat. Każdy znak w ciągu określa dzień. Na przykład ciąg „MTWHF” wskazuje, że w zakresie dat dozwolone są dni robocze. Prawidłowe znaki to:
Obowiązuje każda kombinacja znaków. |
Promotions / HotelPromotions / Promotion / BookingWindow | 0..1 | BookingWindow | Określa przedział czasu, w którym należy dokonać rezerwacji, względem daty zameldowania (na podstawie strefy czasowej obiektu). Na przykład okres rezerwacji można ustawić na co najmniej 7 dni, ale nie więcej niż 180 dni przed datą zameldowania. |
Promotions / HotelPromotions / Promotion / BookingWindow / @min | 0..1 | integer or duration | Aby promocja mogła zostać zastosowana, musi upłynąć minimalny czas, jaki musi upłynąć od zameldowania w momencie rezerwacji. Jeśli nie podasz żadnej wartości lub jej wartość wynosi 0 , wartość minimalna nie będzie minimalna.
Prawidłowe typy wartości to:
|
Promotions / HotelPromotions / Promotion / BookingWindow / @max | 0..1 | integer or duration | Aby można było skorzystać z promocji, należy podać maksymalną liczbę dni przed datą zameldowania. Jeśli nie podasz żadnej wartości lub jej wartość wynosi 0 , nie ma limitu.
Prawidłowe typy wartości to:
|
Promotions / HotelPromotions / Promotion / Ceiling | 0..1 | Ceiling |
Określa ograniczenia dotyczące maksymalnej wartości stawki po zastosowaniu promocji. Promocje muszą zawsze określać Jeśli skonfigurujesz grupowanie, do 1 miejsca zakwaterowania może się odbyć wiele promocji z atrybutem Przykład: Wycena pobytu na 1 noc, w której
Oto kolejność obliczeń:
Fakt, że 60 to większy pułap ogólny, nie ma znaczenia, ponieważ ma on zastosowanie tylko do własnej promocji i nie ma jednego limitu obejmującego cały stos promocji. |
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night | 1 | float |
Maksymalna kwota, jaką można ustawić za noc po zastosowaniu rabatu. Jeśli określono również element
|
Promotions / HotelPromotions / Promotion / Floor | 0..1 | Floor |
Określa ograniczenia dotyczące minimalnej wartości, którą można ustawić po zastosowaniu promocji. Promocje muszą zawsze określać Logika Jeśli skonfigurujesz grupowanie, do 1 miejsca zakwaterowania może się odbyć wiele promocji z atrybutem Przykład: Wycena pobytu na 1 noc, w której
Oto kolejność obliczeń:
Fakt, że 90 to bardziej rygorystyczna ogólna cena minimalna nie ma znaczenia, ponieważ obowiązuje tylko w przypadku własnej promocji i nie może istnieć żadna cena minimalna obejmująca cały stos promocji. |
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night | 1 | float |
Minimalna kwota, jaką można ustawić za noc po zastosowaniu rabatu. Jeśli określono również element
|
Promotions / HotelPromotions / Promotion / CheckinDates | 0..1 | CheckinDates | Kontener na co najmniej 1 zakres dat, który określa, kiedy musi się odprawić, aby promocja została zastosowana. |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange | 1..20 | DateRange | Zakres dat, w którym musi się odprawić, aby można było zastosować promocję. Ten element nie jest wymagany, jeśli usuwasz co najmniej 1 promocję. Obsługiwany jest też format YearlessDate.
|
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @start | 0..1 | Date or YearlessDate | Data rozpoczęcia (na podstawie strefy czasowej usługi) włącznie z datą rozpoczęcia zakresu dat. Ta data nie może być wcześniejsza niż data end . Jeśli nie określisz wartości start , zakres dat będzie w praktyce nieograniczony. |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @end | 0..1 | Date or YearlessDate | Data końcowa z zakresu dat (na podstawie strefy czasowej usługi). Ta data musi być taka sama jak data start lub później. Jeśli nie określisz wartości end , zakres dat będzie nieograniczony, jeśli chodzi o datę zakończenia. |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @days_of_week | 0..1 | string | Dni tygodnia, które są dozwolone w zakresie dat. Jeśli go nie podasz, dozwolone będą wszystkie dni w zakresie dat. Każdy znak w ciągu określa dzień. Na przykład ciąg „MTWHF” wskazuje, że w zakresie dat dozwolone są dni robocze. Prawidłowe znaki to:
Obowiązuje każda kombinacja znaków. |
Promotions / HotelPromotions / Promotion / CheckoutDates | 0..1 | CheckoutDates | Kontener na co najmniej jeden zakres dat, który określa, kiedy należy zapłacić, aby promocja została zastosowana. |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange | 1..20 | DateRange | Zakres dat, w którym musi nastąpić płatność, aby można było skorzystać z promocji. Ten element nie jest wymagany, jeśli usuwasz co najmniej 1 promocję. Obsługiwany jest też format YearlessDate.
|
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @start | 0..1 | Date or YearlessDate | Data rozpoczęcia (na podstawie strefy czasowej usługi) włącznie z datą rozpoczęcia zakresu dat. Ta data nie może być wcześniejsza niż data end . Jeśli nie określisz wartości start , zakres dat będzie w praktyce nieograniczony. |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @end | 0..1 | Date or YearlessDate | Data końcowa z zakresu dat (na podstawie strefy czasowej usługi). Ta data musi być taka sama jak data start lub później. Jeśli nie określisz wartości end , zakres dat będzie nieograniczony, jeśli chodzi o datę zakończenia. |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @days_of_week | 0..1 | string | Dni tygodnia, które są dozwolone w zakresie dat. Jeśli go nie podasz, dozwolone będą wszystkie dni w zakresie dat. Każdy znak w ciągu określa dzień. Na przykład ciąg „MTWHF” wskazuje, że w zakresie dat dozwolone są dni robocze. Prawidłowe znaki to:
Obowiązuje każda kombinacja znaków. |
Promotions / HotelPromotions / Promotion / Devices | 0..1 | Devices | Kontener z listą urządzeń użytkownika, które kwalifikują się do promocji. Jeśli zostanie określona, obniżona cena będzie dostępna tylko dla kwalifikujących się użytkowników korzystających z wymienionych urządzeń. Jeśli jej nie określisz, kwalifikujący się użytkownicy będą mogli skorzystać z rabatu na dowolnym urządzeniu. |
Promotions / HotelPromotions / Promotion / Devices / Device | 1..3 | Device | Określa jeden typ urządzenia użytkownika, które kwalifikuje się do promocji. |
Promotions / HotelPromotions / Promotion / Devices / Device / @type | 1 | enum | Typ urządzenia. Wartością musi być desktop , tablet lub mobile . |
Promotions / HotelPromotions / Promotion / Discount | 1 | Discount | Musisz podać tylko jedną z tych właściwości: Określa rabat stosowany w przypadku tej promocji. |
Promotions / HotelPromotions / Promotion / Discount / @percentage | 0..1 | float | Wymagany jest dokładnie jeden element z tych właściwości: Wartość dziesiętna od 0 do 100, która określa rabat procentowy.
Jest stosowany do Przykłady:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount | 0..1 | float | Wymagany jest dokładnie jeden element z tych właściwości: Stała kwota do odliczenia od sumy Przykłady:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night | 0..1 | float | Wymagany jest dokładnie jeden element z tych właściwości: Stały rabat stosowany do każdej z Przykłady:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_price | 0..1 | float | Wymagany jest dokładnie jeden element z tych właściwości: Jeśli określono stawki za noc w usłudze Jeśli Przykłady:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night | 0..1 | float | Wymagany jest dokładnie jeden element z tych właściwości: Jeśli określono stawki za noc w usłudze Jeśli Jeśli podasz Przykłady:
|
Promotions / HotelPromotions / Promotion / Discount / @applied_nights | 0..1 | integer | Należy jej używać tylko z Liczba nocy, do których stosowany jest rabat, zaczynając od najtańszych. Musi być liczbą całkowitą z zakresu od 1 do 99. Jeśli go nie podasz, rabat zostanie zastosowany do wszystkich nocy. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights | 0..1 | FreeNights | Określa rabat na określone noce za pobyt, jeśli obowiązuje minimalna długość pobytu. Jeśli ten element jest używany, atrybuty w nadrzędnym elemencie Discount nie są dozwolone. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights | 1 | integer | Liczba nocy wymaganych do zastosowania rabatu. Każda zniżka dotyczy osobnego segmentu noclegów. Na przykład w przypadku pobytu na 10 nocy, gdzie |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_nights | 1 | integer | Liczba nocy ze zniżką w poszczególnych segmentach noclegów. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage | 1 | float | Rabat stosowany do nocy, w których obowiązują rabaty. Jeśli ta wartość to 50 , każda wybrana noc jest niższa o 50%. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection | 1 | string | Musi to być wartość cheapest lub last . Jeśli
last , noclegi z końca segmentu pobytu są objęte rabatem. Jeśli cheapest , cena za najtańsze noclegi w segmencie pobytu zostanie obniżona. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats | 1 | boolean | Określa, czy rabat można zastosować do segmentów obejmujących wiele noclegów. Jeśli Jeśli np. |
Promotions / HotelPromotions / Promotion / Discount / @rank | 0..1 | integer | Przypisuje tej promocji pozycję i umożliwia jej wybór na poziomie rankingu. Stosowana jest tylko promocja o najniższej pozycji. Wartości muszą mieścić się w zakresie od 1 do 99 włącznie. Jeśli wiele promocji ma taką samą pozycję, jedna z nich jest wybierana i stosowana losowo. |
Promotions / HotelPromotions / Promotion / BestDailyDiscount | 1 | Discount | Musisz podać tylko jedną z tych właściwości: Określa rabat dzienny, który można zastosować do pobytu. W odróżnieniu od reguły W każdej usłudze może być 1 grupa promocji uznawanych za „najlepsze na dzień”. Oznacza to, że za każdą noc jest wybrana i może zostać zastosowana „najlepsza promocja dnia”, która jest odpowiednia i generuje największy rabat za dany nocleg. Nie można określić atrybutu Można określić |
Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage | 0..1 | float | Wymagana jest dokładnie jedna z tych wartości: Wartość dziesiętna od 0 do 100, która określa rabat procentowy.
Jest stosowany do Przykłady:
|
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount | 0..1 | float | Wymagana jest dokładnie jedna z tych wartości: Stała kwota, która zostanie odjęta od pojedynczej stawki za noc w wysokości Przykłady:
|
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price | 0..1 | float | Wymagana jest dokładnie jedna z tych wartości: Jeśli określono stawki za noc w usłudze Przykłady:
|
Promotions / HotelPromotions / Promotion / InventoryCount | 0..1 | InventoryCount | Określa ograniczenie liczby sal, które muszą być dostępne, aby można było zastosować tę promocję. Rabat jest naliczany tylko za noclegi, które spełniają te wymagania. Niedozwolone ze zniżką fixed_amount . Liczba dostępnych pokoi jest określona za pomocą atrybutu OTA_HotelInvCountNotifRQ (InvCount ) lub OTA_HotelAvailNotifRQ (BookingLimit ). |
Promotions / HotelPromotions / Promotion / InventoryCount / @min | 0..1 | integer | Minimalna liczba pokoi, które muszą być dostępne, aby promocja została zastosowana do ceny za noc. Jeśli go nie podasz, nie ma minimalnej wartości. |
Promotions / HotelPromotions / Promotion / InventoryCount / @max | 0..1 | integer | Maksymalna liczba pokoi, które muszą być dostępne, aby można było zastosować promocję do ceny za noc. Jeśli nie podasz żadnej wartości, nie będzie maksymalnej wartości. |
Promotions / HotelPromotions / Promotion / LengthOfStay | 0..1 | LengthOfStay | Określa limity długości pobytu, w ramach których można zastosować tę promocję. Promocja nie jest stosowana, gdy długość pobytu wykracza poza limity minimalnej i maksymalnej. |
Promotions / HotelPromotions / Promotion / LengthOfStay / @min | 0..1 | integer | Minimalna liczba nocy dozwolona w trakcie pobytu, aby można było skorzystać z promocji. Jeśli ta wartość nie zostanie określona, nie ma minimalnej wartości. |
Promotions / HotelPromotions / Promotion / LengthOfStay / @max | 0..1 | integer | Maksymalna liczba nocy w trakcie pobytu, aby można było skorzystać z promocji. Jeśli nie podasz żadnej wartości, nie będzie maksymalnej wartości. |
Promotions / HotelPromotions / Promotion / MembershipRateRule | 0..1 | MembershipRateRule |
Kontener na regułę dotyczącą ceny członkostwa, która wyzwala określone traktowanie w interfejsie dla powiązanego rabatu. Tego elementu nie należy określać, chyba że określono też |
Promotions / HotelPromotions / Promotion / MembershipRateRule / @id | 1 | string |
Identyfikator reguły dotyczącej ceny powiązanej z programem członkostwa. |
Promotions / HotelPromotions / Promotion / MinimumAmount | 0..1 | MinimumAmount | Określa minimalną sumę dziennych stawek za pokój (większą z wartości AmountBeforeTax lub AmountAfterTax ), którą należy przekroczyć, aby zastosować promocję. |
Promotions / HotelPromotions / Promotion / MinimumAmount / @before_discount | 1 | integer | Wartość, którą należy przekroczyć, aby zastosować promocję. |
Promotions / HotelPromotions / Promotion / Occupancy | 0..1 | Occupancy | Określa ograniczenia dotyczące obłożenia, w przypadku których stosowana jest ta promocja. Promocja nie jest stosowana, gdy liczba osób wykracza poza limity minimalne i maksymalne. |
Promotions / HotelPromotions / Promotion / Occupancy / @min | 0..1 | integer | Aby można było zastosować rabat, liczba osób określonych przez użytkownika musi wynosić co najmniej tę wartość. |
Promotions / HotelPromotions / Promotion / Occupancy / @max | 0..1 | integer | Aby można było zastosować rabat, liczba obłożenia określona przez użytkownika musi wynosić maksymalnie tę wartość. |
Promotions / HotelPromotions / Promotion / RatePlans | 0..1 | RatePlans | Kontener listy planów stawek, których dotyczy promocja.
Jeśli nie określisz wartości <RatePlans> , promocja będzie stosowana do wszystkich planów stawek. |
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan | 1..n | RatePlan | Określa plan stawek. Plan stawek jest definiowany przez połączenie pakietu, stawek i dostępności zgodnie z definicją w danych transakcji (danych obiektu), komunikatach OTA_HotelRateAmountNotifRQ i OTA_HotelAvailNotifRQ oraz określa identyfikator pakietu. |
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id | 1 | string | Unikalny identyfikator abonamentu. Ta wartość jest mapowana na wartość identyfikatora pakietu w <PackageData> w komunikacie Transakcja (dane usługi) oraz w atrybucie RatePlanCode w <StatusApplicationControl> w komunikatach <OTA_HotelRateAmountNotifRQ> i <OTA_HotelAvailNotifRQ> .
Maksymalna dozwolona liczba znaków to 50. |
Promotions / HotelPromotions / Promotion / RoomTypes | 0..1 | RoomTypes | Kontener przeznaczony na listę typów pomieszczeń, do których ma zastosowanie promocja.
Promocja jest stosowana do każdego podanego zasobu <RoomType> . Jeśli nie określisz wartości <RoomTypes> , promocja będzie stosowana do wszystkich sal. |
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType | 1..n | RoomType | Określa typ pomieszczenia. Typ pokoju jest zdefiniowany w elemencie <RoomData> w komunikacie Transakcja (dane usługi) i jest przywoływany za pomocą wartości <RoomID> . (Do jej wartości <RoomID> odwołuje się też atrybut InvTypeCode w komunikatach OTA_HotelRateAmountNotifRQ). |
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id | 1 | string | Unikalny identyfikator zasobów reklamowych (typ pomieszczenia). Ta wartość jest mapowana na <RoomID> w komunikacie transakcji (dane usługi).
Maksymalna dozwolona liczba znaków to 50. |
Promotions / HotelPromotions / Promotion / Stacking | 0..1 | Stacking | Określa sposób łączenia promocji. Jeśli jej nie określisz, przyjmuje się, że pole „type” ma wartość base . |
Promotions / HotelPromotions / Promotion / Stacking / @type | 1 | enum | W zależności od tego ustawienia do jednej stawki można zastosować wiele promocji:
Spośród dozwolonych kombinacji do stawki stosowany jest zestaw promocji, które zapewniają największy rabat. |
Promotions / HotelPromotions / Promotion / StayDates | 0..1 | StayDates | Kontener na co najmniej 1 zakres dat, który określa sposób stosowania promocji, na przykład w celu uwzględnienia rabatów sezonowych. |
Promotions / HotelPromotions / Promotion / StayDates / @application | 1 | enum | Opisuje sposób stosowania promocji. Prawidłowe wartości to:
Ten atrybut musi być zawsze określony.
|
Promotions / HotelPromotions / Promotion / StayDates / DateRange | 1..99 | DateRange | Zakres dat określający daty zastosowania promocji. Obsługiwany jest też format YearlessDate.
|
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @start | 0..1 | Date or YearlessDate | Data rozpoczęcia (na podstawie strefy czasowej usługi) włącznie z datą rozpoczęcia zakresu dat. Ta data nie może być wcześniejsza niż data end . Jeśli nie określisz wartości start , zakres dat będzie w praktyce nieograniczony. |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end | 0..1 | Date or YearlessDate | Data końcowa z zakresu dat (na podstawie strefy czasowej usługi). Ta data musi być taka sama jak data start lub później. Jeśli nie określisz wartości end , zakres dat będzie nieograniczony, jeśli chodzi o datę zakończenia. |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @days_of_week | 0..1 | string | Dni tygodnia, które są dozwolone w zakresie dat. Jeśli go nie podasz, dozwolone będą wszystkie dni w zakresie dat. Każdy znak w ciągu określa dzień. Na przykład ciąg „MTWHF” wskazuje, że w zakresie dat dozwolone są dni robocze. Prawidłowe znaki to:
Obowiązuje każda kombinacja znaków. |
Promotions / HotelPromotions / Promotion / UserCountries | 0..1 | UserCountries | Kontener z listą lokalizacji użytkowników (krajów), które kwalifikują się do promocji. Jeśli określisz rabat, obniżoną stawkę będą mogli uzyskać tylko kwalifikujący się użytkownicy z wymienionych krajów. Jeśli jej nie określisz, kwalifikujący się użytkownicy w dowolnym kraju otrzymają zniżkę. |
Promotions / HotelPromotions / Promotion / UserCountries / @type | 0..1 | enum | Typ specyfikacji krajów użytkowników.
Prawidłowe wartości to Jeśli zasada Jeśli Jeśli zasada |
Promotions / HotelPromotions / Promotion / UserCountries / Country | 1..300 | Country | Określa jeden kraj, w którym użytkownicy mogą skorzystać z promocji. |
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code | 1 | string | Kod kraju CLDR, na przykład DE lub FR . Pamiętaj, że w niektórych krajach kod kraju CLDR różni się od 2-literowego kodu ISO kraju. Kody regionów CLDR nie są też obsługiwane. |
Przykłady
Podstawowa wiadomość
Ten przykład przedstawia podstawowy komunikat Promotions
:
<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
id="123_abc"
timestamp="2020-05-18T16:20:00-04:00">
<HotelPromotions hotel_id="Property_1">
<Promotion id="1">
<BookingDates>
<DateRange start="2020-07-01" end="2020-07-31" days_of_week="MTWHF"/>
<DateRange start="2020-09-01" end="2020-09-30"/>
</BookingDates>
<BookingWindow min="7" max="330"/>
<CheckinDates>
<DateRange start="2020-10-01" end="2020-10-31" days_of_week="FSU"/>
</CheckinDates>
<CheckoutDates>
<DateRange start="2020-10-08" end="2020-11-07" days_of_week="FSU"/>
</CheckoutDates>
<Devices>
<Device type="mobile"/>
<Device type="tablet"/>
</Devices>
<Discount percentage="20" applied_nights="2"/>
<LengthOfStay min="2" max="14"/>
<RatePlans>
<RatePlan id="234"/>
<RatePlan id="567"/>
</RatePlans>
<RoomTypes>
<RoomType id="123"/>
<RoomType id="456"/>
</RoomTypes>
<Stacking type="base"/>
<UserCountries>
<Country code="US"/>
<Country code="GB"/>
</UserCountries>
</Promotion>
</HotelPromotions>
</Promotions>
Stan zasobów reklamowych
Ten przykład pokazuje, jak utworzyć rabat w sytuacji, gdy w pobliżu daty dostawy występuje nadmiarowy asortyment produktów:
<?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>
Usuwanie jednej promocji
Poniższy przykład pokazuje, jak usunąć 1 promocję usługi:
<?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>
Usuń wszystkie promocje
Poniższy przykład pokazuje, jak usunąć wszystkie promocje w usłudze:
<?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>
Nałóż wszystkie promocje
Z przykładu poniżej dowiesz się, jak zastosować metodę <HotelPromotions>
w przypadku usługi z co najmniej 1 nową promocją. Gdy ustawiona jest wartość action="overlay"
, przed zapisaniem promocji wymienionych w bieżącej wiadomości zostają usunięte wszystkie zapisane promocje:
<?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 różne typy układania
Poniższy przykład pokazuje przypadek zastosowania 3 różnych promocji (base
, second
, any
). Pamiętaj, że promocja none
nie zostałaby zastosowana, ponieważ inne promocje zapewniają lepszy rabat. Jeśli pierwotna cena wynosiła 100 zł, obniżona cena wyniesie 72,90 zł.
<?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>
Typ układania: brak
W tym przykładzie pokazano zastosowanie promocji none
, ponieważ kombinacja innych promocji zapewnia mniejszy rabat. Jeśli pierwotna cena wynosiła 100 zł, obniżona cena wyniesie 75 zł.
<?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>
Ograniczenia czasu trwania okresu rezerwacji
W przykładzie poniżej przedstawiono przypadek, w którym element BookingWindow
jest używany z granicami początkowymi i końcowymi zdefiniowanymi jako typ czasu trwania zgodny z normą ISO 8601. Ograniczenie okresu rezerwacji wymaga dokonania rezerwacji do 18:00 dnia przed przyjazdem oraz do 12:00 drugiego dnia przyjazdu lub później.
<?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>
Ograniczenia daty i godziny rezerwacji
Poniższy przykład pokazuje przypadek użycia elementu BookingDates
z atrybutami start
i end
w formie DateTime. Ograniczenie daty rezerwacji wymaga dokonania rezerwacji między 06:30 1 lipca 2020 r. a 18:45 2 lipca 2020 r.
<?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>
Zakresy dat bez roku
W przykładzie poniżej element CheckInDates
zawiera element DateRanges
, który ma pola start
i end
bez lat. W tym przykładzie promocja dotyczy daty zameldowania między 29 grudnia a 2 grudnia, niezależnie od roku. Zakresy dat bez roku, które przekraczają granicę nowego roku, są nieprawidłowe, więc zakres dat jest oznaczony jako 2 sąsiadujące ze sobą zakresy dat.
<?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>
Rabat na FreeNights
W przykładzie poniżej podajemy rabat w wysokości 50% za 2 noce za każdą 4 noce w wybranym zakresie dat. W przypadku planu podróży do 10 noclegów cena za 4 noce jest obniżona o 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>
W następnym przykładzie rabat w wysokości 50% dotyczy każdej 3 noclegów w wyznaczonym zakresie dat. Do rabatu kwalifikują się tylko te długości pobytu. W przypadku poniższego planu podróży z zameldowaniem 1 stycznia 2022 r. i wymeldowaniem 7 stycznia 2022 r. kwalifikujące się noclegi i zniżki są stosowane w następujący sposób.
- 1.01.2022 (pobyt)
- 2.01.2022 r. (nocleg)
- 2022-01-03
- 4.01.2022 r. (obniżka)
- 5.01.2022 r. (pobyt)
- 6.01.2022 (za pobyt)
<?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>
Wybór według rankingu
W przykładzie poniżej oferujemy 2 rabaty: jeden 20%, a drugi 15%. Podczas oceny stosowany jest tylko rabat 15%, ponieważ produkt ma niższą pozycję w rankingu.
<?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
W przykładzie poniżej pokazujemy rabaty za pobyt na 2 noce przez zastosowanie właściwości BestDailyDiscount
ułożonej w tabeli 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>
Rozważ pobyt na 2 noce od 30 kwietnia do 2 maja 2023 r. Dla obliczeń najpierw znajduje się połączenie najlepszych rabatów dziennych, które zapewniają największy rabat.
W przypadku pierwszej nocy „ogólna” promocja to jedyna kwalifikująca się kwota ze stałym rabatem w wysokości 20.
W drugą noc promocja „może” może obejmować większy rabat niż rabat „ogólny”. Jeśli wybierzesz opcję „może”, stała wysokość rabatu wynosi 50.
Następnie w przypadku pobytu obowiązuje rabat w ramach promocji „fiesta” do 5 za nocleg lub łącznie 10. Można je łączyć z kombinacją najlepszych rabatów dziennych, ponieważ typ grupowania „fiesta” jest ustawiony na any
. Jeśli ustawiona wartość to base
, stosowana jest tylko kombinacja najlepszych rabatów dziennych lub rabatu „fiesta”. Więcej informacji znajdziesz w opisie Stacking
.
Ogólnie cena za pobyt otrzymuje rabat w wysokości 20 + 50 + 10 = 80 zniżki w wysokości stałej.
Odpowiedzi
Składnia
Komunikat PromotionsResponse
ma taką składnię:
<?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>
Elementy i atrybuty
Wiadomość PromotionsResponse
zawiera te elementy i atrybuty:
Element / @Atrybut | Wystąpienia | Typ | Opis |
---|---|---|---|
PromotionsResponse | 1 | Complex element | Element główny wskazujący powodzenie lub problemy związane z otrzymaną wiadomością z prośbą o promocje. |
PromotionsResponse / @timestamp | 1 | DateTime | Data i godzina utworzenia tej wiadomości. |
PromotionsResponse / @id | 1 | string | Unikalny identyfikator powiązanej wiadomości o promocjach. |
PromotionsResponse / @partner | 1 | string | Konto partnera, z którego pochodzi ta wiadomość. |
PromotionsResponse / Success | 0..1 | Success | Wskazuje, że wiadomość o promocjach została przetworzona bez ostrzeżeń, błędów i błędów.
Każda wiadomość zawiera element |
PromotionsResponse / Issues | 0..1 | Issues | Kontener rozwiązania co najmniej jednego problemu, który wystąpił podczas przetwarzania wiadomości z promocjami.
Każda wiadomość zawiera element |
PromotionsResponse / Issues / Issue | 1..n | Issue | Opis ostrzeżenia, błędu lub błędu napotkanych podczas przetwarzania wiadomości z promocjami. Szczegółowe informacje o tych problemach znajdziesz w artykule Komunikaty o błędach dotyczące stanu pliku danych. |
PromotionsResponse / Issues / Issue / @code | 1 | integer | Identyfikator problemu. |
PromotionsResponse / Issues / Issue / @status | 1 | enum | Typ napotkanego problemu. Prawidłowe wartości to |
Przykłady
Gotowe
Poniżej znajdziesz odpowiedź na pomyślnie przetworzoną wiadomość z promocjami.
<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="2020-05-18T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Success/>
</PromotionsResponse>
Problemy
Poniżej znajdziesz odpowiedź na wiadomość z promocjami, która nie została przetworzona z powodu błędów.
<?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>