Omówienie
Ten interfejs API umożliwia określenie możliwych rabatów. Spośród podanych promocji Google stosuje kwalifikującą się promocję lub zestaw promocji, które prowadzą do uzyskania najniższej ceny. Jeśli szukasz interfejsu API, który obsługuje dowolne korekty cen, które mogą zwiększać lub zmniejszać cenę, gdy są spełnione określone warunki, rozważ skorzystanie z naszego interfejsu Rate Modifications API. Pamiętaj, że jeśli występują oba interfejsy API, modyfikacje stawek są stosowane przed promocjami.
Żądania
Składnia
Wiadomość Promotions
używa tej 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, percentage_of_base, fixed_amount,
fixed_amount_per_night, fixed_price, or fixed_price_per_night;
applied_nights is only used with percentage, fixed_amount_per_night,
and fixed_price_per_night. -->
<Discount percentage="float" percentage_of_base="float"
fixed_amount="float" fixed_amount_per_night="float"
fixed_price="float" fixed_price_per_night="float"
applied_nights="integer_1_to_99" rank="integer_1_to_99">
<!-- FreeNights may not be used in conjunction with attributes on Discount -->
<FreeNights stay_nights="integer" discount_nights="integer"
discount_percentage="float" night_selection="[cheapest|last]"
repeats="boolean"/>
</Discount>
<!-- Exactly one of Discount or BestDailyDiscount must be specified.
Specify only one of percentage, fixed_amount, or fixed_price. -->
<BestDailyDiscount percentage="float" fixed_amount="float" fixed_price="float"/>
<Devices>
<Device type="[desktop|tablet|mobile]"/>
</Devices>
<InventoryCount min="integer" max="integer"/>
<LengthOfStay min="integer" max="integer"/>
<MembershipRateRule id="RateRuleID"/>
<MinimumAmount before_discount="integer"/>
<Occupancy min="integer" max="integer"/>
<RatePlans>
<RatePlan id="PackageID_1"/>
<RatePlan id="PackageID_2"/>
</RatePlans>
<RoomTypes>
<RoomType id="RoomID_1"/>
<RoomType id="RoomID_2"/>
</RoomTypes>
<Stacking type="[any|base|none|second]"/>
<StayDates application="[all|any|overlap]">
<DateRange start="[YYYY-]MM-DD" end="[YYYY-]MM-DD" days_of_week="MTWHFSU_or_subset"/>
</StayDates>
<UserCountries type="[include|exclude]">
<Country code="country_code"/>
</UserCountries>
</Promotion>
</HotelPromotions>
</Promotions>
Elementy i atrybuty
Wiadomość o promocji zawiera te elementy i atrybuty:
Element / @Attribute | Wystąpienia | Typ | Opis |
---|---|---|---|
Promotions | 1 | Complex element | Element główny wiadomości o promocjach. |
Promotions / @partner | 1 | string | Konto partnera, na którym jest wysyłana wiadomość. Ta wartość ciągu znaków to wartość „klucza 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 być zgodna z wartością atrybutu |
Promotions / @id | 1 | string | Unikalny identyfikator tego komunikatu żądania. 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 dla usługi. Każda promocja dotyczy jednej usługi. Jeśli nie jest używana opcja |
Promotions / HotelPromotions / @hotel_id | 1 | string | Unikalny identyfikator usługi. Ta wartość musi być zgodna z identyfikatorem hotelu określonym za pomocą elementu
<id> w elemencie <listing> w pliku danych z listą hoteli. Identyfikator hotelu jest też widoczny w Hotel Center. |
Promotions / HotelPromotions / @action | 0..1 | enum | Jeśli została określona, wartość musi być Jeśli nie określisz inaczej, każda promocja określona w bieżącym komunikacie jest:
|
Promotions / HotelPromotions / Promotion | 0..99 | Promotion | Pojedyncza promocja obiektu. Pamiętaj, że jeśli nie określisz wartoś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 być Jeśli podasz wartość |
Promotions / HotelPromotions / Promotion / BookingDates | 0..1 | BookingDates | Konteiner dla co najmniej jednego zakresu określającego, kiedy musi nastąpić rezerwacja, aby można było zastosować promocję. |
Promotions / HotelPromotions / Promotion / BookingDates / DateRange | 1..99 | DateRange | Zakres określający, kiedy rezerwacja musi zostać dokonana, aby promocja mogła zostać zastosowana. |
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @start | 0..1 | Date lub DateTime | Data lub data i godzina rozpoczęcia (według strefy czasowej usługi) obejmująca zakres.
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end | 0..1 | Date lub DateTime | Data lub data i godzina zakończenia (według strefy czasowej usługi) włącznie z zakresem.
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week | 0..1 | string | Dni tygodnia dozwolone w wybranym zakresie dat. Jeśli nie określisz inaczej, wszystkie dni w zakresie dat są dozwolone. Każda litera w ciągu odpowiada jednemu dniowi. Na przykład „MTWHF” określa, że w zakresie dat dozwolone są dni robocze. Prawidłowe znaki:
Dozwolona jest dowolna kombinacja znaków. |
Promotions / HotelPromotions / Promotion / BookingWindow | 0..1 | BookingWindow | Określa okres, w którym rezerwacja musi nastąpić w stosunku do daty zameldowania (na podstawie strefy czasowej obiektu). Okno rezerwacji może wynosić co najmniej 7 dni, ale nie więcej niż 180 dni przed zameldowaniem. |
Promotions / HotelPromotions / Promotion / BookingWindow / @min | 0..1 | integer or duration | Minimalny czas przed zameldowaniem, w którym musi nastąpić rezerwacja, aby promocja mogła zostać zastosowana. Jeśli nie podasz żadnej opcji lub jeśli jej wartość to 0 , nie będzie minimalnej wartości.
Prawidłowe typy wartości:
|
Promotions / HotelPromotions / Promotion / BookingWindow / @max | 0..1 | integer or duration | Maksymalna liczba dni przed zameldowaniem, w których musi nastąpić rezerwacja, aby można było zastosować promocję. Jeśli nie podasz żadnej opcji lub jeśli jej wartość jest 0 , nie ma maksymalnej wartości.
Prawidłowe typy wartości:
|
Promotions / HotelPromotions / Promotion / Ceiling | 0..1 | Ceiling |
Określa ograniczenia dotyczące maksymalnej wartości, jaką może mieć stawka po zastosowaniu promocji. Promocje muszą zawsze zawierać wartość Jeśli skumulowanie jest skonfigurowane, do jednego pobytu może mieć zastosowanie kilka promocji z Przykład: Ustalanie ceny za 1 noc, gdy
Oto kolejność obliczeń:
Fakt, że 60 to bardziej restrykcyjny ogólny limit, jest nieistotny, ponieważ obowiązuje on tylko w przypadku danej promocji i nie może obejmować całego zbioru promocji. |
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night | 1 | float |
Maksymalna kwota, jaką można ustawić jako stawkę za noc po zastosowaniu zniżki. Jeśli podany jest też element
|
Promotions / HotelPromotions / Promotion / Floor | 0..1 | Floor |
Określa ograniczenia dotyczące minimalnej wartości, jaką może mieć stawka po zastosowaniu promocji. Promocje muszą zawsze zawierać wartość Logika Jeśli skumulowanie jest skonfigurowane, do jednego pobytu może mieć zastosowanie kilka promocji z Przykład: Ustalanie ceny za 1 noc, gdy
Oto kolejność obliczeń:
Fakt, że 90 to bardziej rygorystyczna ogólna wartość minimalna, nie ma znaczenia, ponieważ obowiązuje tylko w przypadku danej promocji i nie może być jednej wartości minimalnej dla całego zbioru promocji. |
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night | 1 | float |
Minimalna kwota, jaką można ustawić dla stawki za noc po zastosowaniu rabatu. Jeśli podano też element
|
Promotions / HotelPromotions / Promotion / CheckinDates | 0..1 | CheckinDates | Kontener zawierający co najmniej 1 okres, w którym musi nastąpić potwierdzenie zalogowania, aby promocja mogła zostać zastosowana. |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange | 1..20 | DateRange | Zakres dat określający, kiedy musi nastąpić zameldowanie, aby promocja mogła zostać zastosowana. 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 (według strefy czasowej usługi) obejmująca zakres dat. Data ta musi być wcześniejsza lub równa dacie end . Jeśli nie podasz wartości start , zakres dat będzie obejmował wszystkie daty. |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @end | 0..1 | Date or YearlessDate | Data końcowa (zgodnie ze strefą czasową usługi) zakresu dat. Data musi być taka sama jak data start lub późniejsza. Jeśli nie podasz parametru end , zakres dat będzie nieograniczony pod względem daty zakończenia. |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @days_of_week | 0..1 | string | Dni tygodnia dozwolone w wybranym zakresie dat. Jeśli nie określisz inaczej, wszystkie dni w zakresie dat są dozwolone. Każda litera w ciągu odpowiada jednemu dniowi. Na przykład „MTWHF” określa, że w zakresie dat dozwolone są dni robocze. Prawidłowe znaki:
Dozwolona jest dowolna kombinacja znaków. |
Promotions / HotelPromotions / Promotion / CheckoutDates | 0..1 | CheckoutDates | Pojemnik z co najmniej jednym zakresem dat, który określa, kiedy musi nastąpić płatność, aby promocja mogła zostać zastosowana. |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange | 1..20 | DateRange | Zakres dat określający, kiedy musi nastąpić wymeldowanie, aby promocja mogła zostać zastosowana. 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 (według strefy czasowej usługi) obejmująca zakres dat. Data ta musi być wcześniejsza lub równa dacie end . Jeśli nie podasz wartości start , zakres dat będzie obejmował wszystkie daty. |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @end | 0..1 | Date or YearlessDate | Data końcowa (zgodnie ze strefą czasową usługi) zakresu dat. Data musi być taka sama jak data start lub późniejsza. Jeśli nie podasz parametru end , zakres dat będzie nieograniczony pod względem daty zakończenia. |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @days_of_week | 0..1 | string | Dni tygodnia dozwolone w wybranym zakresie dat. Jeśli nie określisz inaczej, wszystkie dni w zakresie dat są dozwolone. Każda litera w ciągu odpowiada jednemu dniowi. Na przykład „MTWHF” określa, że w zakresie dat dozwolone są dni robocze. Prawidłowe znaki:
Dozwolona jest dowolna kombinacja znaków. |
Promotions / HotelPromotions / Promotion / Devices | 0..1 | Devices | Kontenery do wyświetlania listy urządzeń użytkownika kwalifikujących się do promocji. Jeśli to konieczne, rabat jest oferowany tylko uprawnionym użytkownikom na wymienionych urządzeniach. Jeśli nie zostanie określony, rabat zostanie zaproponowany kwalifikującym się użytkownikom 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ść musi być desktop , tablet lub mobile . |
Promotions / HotelPromotions / Promotion / Discount | 1 | Discount | Musisz podać dokładnie jedną z tych właściwości: Określa rabat, który ma być zastosowany w przypadku tej promocji. |
Promotions / HotelPromotions / Promotion / Discount / @percentage | 0..1 | float | Wymagane jest podanie dokładnie jednej z tych właściwości: Wartość dziesiętna z zakresu 0–100, która określa procent rabatu.
Jest ona stosowana do Przykłady:
|
Promotions / HotelPromotions / Promotion / Discount / @percentage_of_base | 0..1 | float | Wymagane jest podanie dokładnie jednej z tych właściwości: Wartość dziesiętna z zakresu 0–100, która określa procent rabatu od ceny podstawowej. Podobnie jak w przypadku reguły W przeciwieństwie do Przykład:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount | 0..1 | float | Wymagane jest podanie dokładnie jednej z tych właściwości: Stałe kwoty, które zostaną odjęte od sumy stawek za noc Przykłady:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night | 0..1 | float | Wymagane jest podanie dokładnie jednej z tych właściwości: stały rabat zastosowany do każdej z Przykłady:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_price | 0..1 | float | Wymagane jest podanie dokładnie jednej z tych właściwości: Jeśli określono Jeśli Przykłady:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night | 0..1 | float | Wymagane jest podanie dokładnie jednej z tych właściwości: Jeśli określono Jeśli Jeśli podano parametr Przykłady:
|
Promotions / HotelPromotions / Promotion / Discount / @applied_nights | 0..1 | integer | Należy go używać tylko w przypadku atrybutów Liczba nocy, do których ma zastosowanie rabat, począwszy od najtańszej. Musi być liczbą całkowitą z zakresu od 1 do 99. Jeśli nie zostanie określony, zniżka zostanie zastosowana do wszystkich nocy. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights | 0..1 | FreeNights | Określa rabat na określone noce pobytu, gdy spełniona jest minimalna długość pobytu. Jeśli użyto tego elementu, atrybuty elementu nadrzędnego Discount są niedozwolone. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights | 1 | integer | Liczba wymaganych nocy, aby można było zastosować rabat. Każda zniżka jest stosowana do osobnego segmentu nocy pobytu. Na przykład w przypadku pobytu na 10 nocy, w którym |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_nights | 1 | integer | Liczba nocy ze zniżką w każdym segmencie pobytu. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage | 1 | float | Rabat zastosowany do nocy objętych rabatem. Jeśli ta wartość jest 50 , każda wybrana noc jest objęta 50% rabatem. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection | 1 | string | Musi to być wartość cheapest lub last . Jeśli last , noce na końcu segmentu pobytu są objęte rabatem. Jeśli cheapest , najtańsze noce w ramach segmentu noclegów są objęte rabatem. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats | 1 | boolean | Określ, czy rabat może być stosowany w przypadku wielu segmentów dotyczących liczby nocy pobytu. Jeśli Jeśli np. |
Promotions / HotelPromotions / Promotion / Discount / @rank | 0..1 | integer | Przypisuje tej promocji pozycję i włącza ją do selekcji wg poziomu, w której tylko promocja z najniższą pozycją jest wybierana do zastosowania. Wartości muszą mieścić się w przedziale od 1 do 99 włącznie. Jeśli kilka promocji ma ten sam ranking, jedna z nich zostanie wybrana losowo i zastosowana. |
Promotions / HotelPromotions / Promotion / BestDailyDiscount | 1 | Discount | Musisz podać dokładnie jedną z tych właściwości: Określa rabat dzienny, który może być zastosowany do jednej nocy pobytu. Jest to sprzeczne z wartością Każda usługa może mieć jedną grupę promocji, która jest uważana za „najlepszą codzienną”. Oznacza to, że w przypadku każdej nocy pobytu wybierana jest i może być stosowana jedna „najlepsza zniżka na dzień”, która kwalifikuje się do zastosowania i daje największy rabat na daną noc. Wartość W przypadku tego typu rabatu można określić opcję |
Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage | 0..1 | float | Wymagane jest dokładnie jedno z tych atrybutów: Wartość dziesiętna z zakresu 0–100, która określa procent rabatu.
Jest ona stosowana do Przykłady:
|
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount | 0..1 | float | Wymagane jest dokładnie jedno z tych atrybutów: Stałe kwoty do odjęcia od jednej stawki za noc:
Przykłady:
|
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price | 0..1 | float | Wymagane jest dokładnie jedno z tych atrybutów: Jeśli określono Przykłady:
|
Promotions / HotelPromotions / Promotion / InventoryCount | 0..1 | InventoryCount | Określa ograniczenia dotyczące liczby pokoi, które muszą być dostępne, aby można było zastosować tę promocję. Rabat jest stosowany tylko do nocy, które spełniają ograniczenia. Niedozwolone w przypadku rabatu fixed_amount . Pamiętaj, że liczba dostępnych pokoi jest określana za pomocą parametru 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 mogła zostać zastosowana do stawki za noc. Jeśli nie określisz tu żadnej wartości, nie będzie minimalnej wartości. |
Promotions / HotelPromotions / Promotion / InventoryCount / @max | 0..1 | integer | Maksymalna liczba pokoi, które muszą być dostępne, aby promocja mogła zostać zastosowana do stawki za noc. Jeśli nie podasz żadnej wartości, nie będzie limitu. |
Promotions / HotelPromotions / Promotion / LengthOfStay | 0..1 | LengthOfStay | Określa limity długości pobytu, w których można zastosować tę promocję. Promocja nie jest stosowana, gdy długość pobytu wykracza poza minimalne lub maksymalne limity. |
Promotions / HotelPromotions / Promotion / LengthOfStay / @min | 0..1 | integer | Minimalna liczba noclegów, które można wykorzystać w ramach promocji. Jeśli nie określisz tu żadnej wartości, nie będzie limitów. |
Promotions / HotelPromotions / Promotion / LengthOfStay / @max | 0..1 | integer | Maksymalna liczba noclegów, które można opłacić w ramach promocji. Jeśli nie określisz tu żadnej wartości, nie będzie limitu. |
Promotions / HotelPromotions / Promotion / MembershipRateRule | 0..1 | MembershipRateRule |
Kontenery dla reguły dotyczącej stawki członkostwa, która powoduje wyświetlenie określonego interfejsu użytkownika w przypadku powiązanego rabatu. Ten element nie powinien być określony, chyba że podano też parametr |
Promotions / HotelPromotions / Promotion / MembershipRateRule / @id | 1 | string |
Identyfikator reguły dotyczącej stawek powiązanej z programem członkostwa. |
Promotions / HotelPromotions / Promotion / MinimumAmount | 0..1 | MinimumAmount | Określa minimalną sumę dziennych stawek za pokój (przy użyciu większej wartości z AmountBeforeTax lub AmountAfterTax ), która musi zostać przekroczona, aby można było zastosować promocję. |
Promotions / HotelPromotions / Promotion / MinimumAmount / @before_discount | 1 | integer | Wartość, która musi zostać przekroczona, aby promocja mogła zostać zastosowana. |
Promotions / HotelPromotions / Promotion / Occupancy | 0..1 | Occupancy | Definiuje ograniczenia dotyczące liczby osób, w przypadku których promocja jest stosowana. Promocja nie jest stosowana, gdy liczba osób przekracza minimalną lub maksymalną liczbę. |
Promotions / HotelPromotions / Promotion / Occupancy / @min | 0..1 | integer | Aby można było zastosować rabat, liczba osób określona 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 osób określona przez użytkownika nie może przekraczać tej wartości. |
Promotions / HotelPromotions / Promotion / RatePlans | 0..1 | RatePlans | Kontener z listą planów cenowych, do których ma zastosowanie promocja.
Jeśli nie podasz wartości <RatePlans> , promocja będzie obowiązywać w przypadku wszystkich planów cenowych. |
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan | 1..n | RatePlan | Określa plan taryfowy. Pakiet usług jest zdefiniowany przez kombinację pakietu, stawek i dostępności, jak określono w transakcjach (dane obiektu), wiadomościach OTA_HotelRateAmountNotifRQ i OTA_HotelAvailNotifRQ oraz identyfikatorze PackageID. |
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id | 1 | string | Unikalny identyfikator planu cenowego. Ta wartość jest mapowana na wartość parametru PackageID w polu <PackageData> w wiadomości Transakcja (dane usługi) oraz na atrybut RatePlanCode w polu <StatusApplicationControl> w obu wiadomościach <OTA_HotelRateAmountNotifRQ> i <OTA_HotelAvailNotifRQ> .
Maksymalna liczba znaków to 50. |
Promotions / HotelPromotions / Promotion / RoomTypes | 0..1 | RoomTypes | Kontener z listą typów pokoi, do których ma zastosowanie promocja.
Promocja jest stosowana do każdego określonego <RoomType> . Jeśli <RoomTypes> nie jest określony, promocja dotyczy wszystkich pokoi. |
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType | 1..n | RoomType | Określa typ pokoju. Typ pokoju jest zdefiniowany w elemencie <RoomData> w wiadomości Transakcja (dane obiektu) i jest odwoływany za pomocą wartości <RoomID> . (jej wartość <RoomID> jest też używana przez atrybut InvTypeCode w wiadomościach OTA_HotelRateAmountNotifRQ). |
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id | 1 | string | Unikalny identyfikator asortymentu (typ pokoju). Ta wartość jest mapowana na <RoomID> w wiadomości dotyczącej transakcji (danych usługi).
Maksymalna liczba znaków to 50. |
Promotions / HotelPromotions / Promotion / Stacking | 0..1 | Stacking | Określa, jak można łączyć promocje. Jeśli nie zostanie określona, przyjmuje się, że wartość „type” to base . |
Promotions / HotelPromotions / Promotion / Stacking / @type | 1 | enum | W zależności od tego ustawienia do jednej stawki można zastosować kilka promocji:
Spośród dozwolonych kombinacji do stawki zostanie zastosowany zestaw promocji, który zapewnia największy rabat. |
Promotions / HotelPromotions / Promotion / StayDates | 0..1 | StayDates | Konteiner zawierający co najmniej 1 zakres dat, który określa sposób stosowania promocji, na przykład w przypadku rabatów sezonowych. |
Promotions / HotelPromotions / Promotion / StayDates / @application | 1 | enum | Opisuje, jak należy zastosować promocję. 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, w których ma obowiązywać promocja. Obsługiwany jest też format YearlessDate.
Jeśli chcesz ustawić zakres |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @start | 0..1 | Date or YearlessDate | Data rozpoczęcia (według strefy czasowej usługi) obejmująca zakres dat. Data ta musi być wcześniejsza lub równa dacie end . Jeśli nie podasz wartości start , zakres dat będzie obejmował wszystkie daty.
Jeśli wartość |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end | 0..1 | Date or YearlessDate | Data końcowa (zgodnie ze strefą czasową usługi) zakresu dat. Data musi być taka sama jak data start lub późniejsza. Jeśli nie podasz wartości end , zakres dat będzie obejmował wszystkie daty od start .
Jeśli wartość |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @days_of_week | 0..1 | string | Dni tygodnia dozwolone w wybranym zakresie dat. Jeśli nie określisz inaczej, wszystkie dni w zakresie dat są dozwolone. Każda litera w ciągu odpowiada jednemu dniowi. Na przykład „MTWHF” określa, że w zakresie dat dozwolone są dni robocze. Prawidłowe znaki:
Dozwolona jest dowolna kombinacja znaków. |
Promotions / HotelPromotions / Promotion / UserCountries | 0..1 | UserCountries | Kontener z listą lokalizacji użytkowników (krajów) kwalifikujących się do promocji. Jeśli to konieczne, zniżka będzie dostępna tylko dla kwalifikujących się użytkowników z wymienionych krajów. Jeśli nie zostanie określony, zniżka zostanie zaproponowana kwalifikującym się użytkownikom z dowolnego kraju. |
Promotions / HotelPromotions / Promotion / UserCountries / @type | 0..1 | enum | Typ specyfikacji UserCountries.
Prawidłowe wartości to Jeśli parametr UserCountries Jeśli parametr UserCountries Jeśli parametr UserCountries |
Promotions / HotelPromotions / Promotion / UserCountries / Country | 1..300 | Country | Określa jeden kraj, w którym użytkownicy kwalifikują się do promocji. |
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code | 1 | string | kod kraju CLDR,
na przykład DE lub FR . Pamiętaj, że w przypadku niektórych krajów kod CLDR nie jest taki sam jak 2-literowy kod ISO. Nie są też obsługiwane kody regionów CLDR. |
Przykłady
Obowiązuje limit 500 promocji na usługę. Aby usunąć promocje z usługi, zapoznaj się z przykładem „Usuwanie promocji”.
Podstawowa wiadomość
Ten przykład pokazuje 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
Z poniższego przykładu dowiesz się, jak utworzyć rabat, jeśli w pobliżu daty dostawy jest nadwyżka asortymentu:
<?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ąć jedną promocję dla 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>
Usuwanie wszystkich promocji
Poniższy przykład pokazuje, jak usunąć wszystkie promocje dotyczące 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" action="overlay"/>
</Promotions>
Nakładanie wszystkich promocji
Ten przykład pokazuje, jak nałożyć <HotelPromotions>
na usługę z co najmniej 1 nową promocją. Jeśli action="overlay"
, wszystkie zapisane promocje są usuwane przed zapisaniem promocji określonych w bieżącej wiadomości:
<?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
W następującym przykładzie pokazano przypadek, w którym zastosowano 3 różne promocje (base
, second
, any
). Pamiętaj, że promocja none
nie zostanie zastosowana, ponieważ pozostałe promocje oferują lepsze rabaty. Jeśli pierwotna cena wynosiła 100 PLN, cena promocyjna wyniesie 72,90 PLN.
<?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>
Brak typu układania
W tym przykładzie wykorzystano promocję none
, ponieważ kombinacja innych promocji daje mniejszy rabat. Jeśli pierwotna cena wynosiła 100 zł, cena po rabacie 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>
Limity czasu trwania okna rezerwacji
Przykład poniżej pokazuje przypadek, w którym element BookingWindow
jest używany z wartościami początkowymi i końcowymi zdefiniowanymi jako typ czasu trwania według standardu ISO 8601. Ta opcja rezerwacji wymaga dokonania rezerwacji do godziny 18:00 dnia poprzedzającego przyjazd oraz do godziny 12:00 drugiego dnia poprzedzającego przyjazd.
<?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>
Zakres dat i godzin rezerwacji
Ten przykład pokazuje przypadek, w którym element BookingDates
jest używany z atrybutami start
i end
jako typami DateTime. Ta data rezerwacji wymaga, aby rezerwacja została dokonana
między 6:30 01.07.2020 r. i 18:45 2. 07.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
Ten przykład pokazuje przypadek, w którym element CheckInDates
zawiera element DateRanges
, który ma pola start
i end
bez lat. W tym przykładzie promocja obowiązuje w dniach zameldowania od 29 grudnia do 2 stycznia, niezależnie od roku. Zakresy dat bez roku, które przekraczają granicę nowego roku, są nieprawidłowe, dlatego zakres dat jest wyrażany jako 2 sąsiadujące 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 tym przykładzie każda z 4 nocy jest objęta 50% rabatem, a cena 2 nocy wynosi 0 PLN. W przypadku planu podróży obejmującego 10 nocy zniżka 50% zostałaby przyznana na 4 noce.
<?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 cena za jedną noc jest obniżona o 50% za każdą z 3 nocy w ramach określonych zakresów dat pobytu. Do rabatu brane są pod uwagę tylko noce pobytu, które się pokrywają. W przypadku tej trasy z zameldowaniem w dniu 2022-01-01 i wymeldowaniem w dniu 2022-01-07 rabaty i noclegi kwalifikujące się do rabatu są stosowane w następujący sposób:
- 2022-01-01 (pobyt)
- 2022-01-02 (pobyt)
- 2022-01-03
- 2022-01-04 (z rabatem)
- 2022-01-05 (pobyt)
- 2022-01-06 (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 rankingowy
W tym przykładzie oferowane są 2 rabaty: jeden o wysokości 20%, a drugi o wysokości 15%. Podczas oceny uwzględniany jest tylko rabat o wysokości 15%, ponieważ ma on niższą rangę.
<?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 tym przykładzie rabat na pobyt na 2 noce jest przyznawany przez zastosowanie BestDailyDiscount
w połączeniu z 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 trwający 2 noce w dniach od 30 kwietnia do 2 maja 2023 r. Podczas obliczeń najpierw jest wybierana kombinacja najlepszych rabatów dziennych, która daje największy rabat.
W przypadku pierwszej nocy tylko promocja „Ogólna” jest kwalifikowana do rabatu w wysokości 20%.
W przypadku drugiej nocy promocja „w maju” oferuje większy rabat niż promocja „ogólna”. Gdy wybrana jest opcja „Może”, kwota stałego rabatu wynosi 50.
Następnie w przypadku pobytu zniżki promocyjne „fiesta” zmniejszają się do 5 zł za noc, czyli łącznie 10 zł. Może być ona połączona z kombinacją najlepszych zniżek dziennych, ponieważ dla „fiesta” ustawiono typ nakładania any
. Jeśli ustawisz wartość base
, zostanie zastosowana tylko kombinacja najlepszych zniżek na dany dzień lub zniżka „fiesta”. Więcej informacji znajdziesz w opisie funkcji Stacking
.
Ogólnie cena pobytu jest obniżona o 20 + 50 + 10 = 80 zł.
Odpowiedzi
Składnia
Wiadomość PromotionsResponse
używa tej 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 / @Attribute | Wystąpienia | Typ | Opis |
---|---|---|---|
PromotionsResponse | 1 | Complex element | Element główny wskazujący, czy otrzymane żądanie dotyczące promocji zostało zrealizowane, czy też wystąpiły z nim problemy. |
PromotionsResponse / @timestamp | 1 | DateTime | Data i godzina utworzenia tej wiadomości. |
PromotionsResponse / @id | 1 | string | Unikalny identyfikator z powiązanego komunikatu z promocjami. |
PromotionsResponse / @partner | 1 | string | Konto partnera, na którym jest wysyłana wiadomość. |
PromotionsResponse / Success | 0..1 | Success | Wskazuje, że wiadomość dotycząca promocji została przetworzona bez ostrzeżeń, błędów ani niepowodzeń.
W każdej wiadomości występuje element |
PromotionsResponse / Issues | 0..1 | Issues | Kontener dla co najmniej 1 problemu, który wystąpił podczas przetwarzania wiadomości o promocjach.
W każdej wiadomości występuje element |
PromotionsResponse / Issues / Issue | 1..n | Issue | Opis ostrzeżenia, błędu lub niepowodzenia napotkanego podczas przetwarzania wiadomości z promocjami. Szczegółowe informacje o tych problemach znajdziesz w komunikatach o błędach 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
Sukces
Poniżej znajduje się odpowiedź na pomyślnie przetworzone wiadomości dotyczące promocji.
<?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 znajduje się odpowiedź na wiadomość dotyczącą promocji, 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>