Informações gerais
Essa API permite especificar os possíveis descontos. O Google aplica a promoção qualificada ou o conjunto de promoções que gera o menor preço entre as promoções especificadas. Se você estiver procurando uma API que ofereça suporte a ajustes arbitrários de taxas que possam aumentar ou diminuir o preço quando as condições forem atendidas, considere nossa API Rate Overrides. Se as duas APIs estiverem presentes, as modificações de tarifas serão aplicadas antes das promoções.
Pedidos
Sintaxe
A mensagem Promotions
usa a seguinte sintaxe:
<?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>
Elementos e atributos
A mensagem de promoções tem os seguintes elementos e atributos:
Elemento / @Attribute | Ocorrências | Tipo | Descrição |
---|---|---|---|
Promotions | 1 | Complex element | O elemento raiz de uma mensagem de promoções. |
Promotions / @partner | 1 | string | A conta do parceiro para esta mensagem. Esse valor de string é o valor "Chave do parceiro" listado na
página de configurações da conta na Central para Hotéis.
Se você tem um back-end que fornece feeds para
várias contas, esse valor precisa corresponder ao valor do atributo
|
Promotions / @id | 1 | string | Um identificador exclusivo para essa mensagem de solicitação. Esse valor é retornado na mensagem de resposta. Os caracteres permitidos são a-z, A-Z, 0-9, _ (sublinhado) e - (hífen). |
Promotions / @timestamp | 1 | DateTime | A data e a hora de criação da mensagem. |
Promotions / HotelPromotions | 0..n | HotelPromotions | Promoções de uma propriedade. Cada promoção se aplica a uma única propriedade. A menos que |
Promotions / HotelPromotions / @hotel_id | 1 | string | O identificador exclusivo da propriedade. Esse valor precisa corresponder ao ID do hotel especificado usando
<id> no elemento <listing> no Feed de lista de hotéis. O ID do hotel também aparece na Central para Hotéis. |
Promotions / HotelPromotions / @action | 0..1 | enum | Se especificado, o valor precisa ser Se não for especificado, cada promoção especificada na mensagem atual será:
|
Promotions / HotelPromotions / Promotion | 0..99 | Promotion | Uma única promoção de uma propriedade. Se Se você precisar usar mais de 99 promoções, entre em contato com seu Gerente técnico de contas (TAM). |
Promotions / HotelPromotions / Promotion / @id | 1 | string | Identificador exclusivo da promoção. O número máximo de caracteres permitidos é 40. Os caracteres permitidos são a-z, A-Z, 0-9, _ (sublinhado), - (hífen) e . (ponto final). |
Promotions /HotelPromotions / Promotion / @action | 0..1 | enum | Se especificado, o valor precisa ser Se |
Promotions / HotelPromotions / Promotion / BookingDates | 0..1 | BookingDates | Um contêiner para um ou mais intervalos que definem quando a reserva precisa ocorrer para que a promoção seja aplicada. |
Promotions / HotelPromotions / Promotion / BookingDates / DateRange | 1..99 | DateRange | Um intervalo que especifica quando é necessário fazer a reserva para que a promoção seja aplicada. |
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @start | 0..1 | Date ou DateTime | A data ou data e hora de início (com base no fuso horário da propriedade), inclusive do intervalo.
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end | 0..1 | Date ou DateTime | A data ou data/hora de término (com base no fuso horário da propriedade), inclusive do intervalo.
|
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week | 0..1 | string | Os dias da semana permitidos no período. Se não for especificado, todos os dias serão permitidos no período. Cada caractere da string especifica um dia. Por exemplo, "MTWHF" especifica que os dias da semana são permitidos no período. Os caracteres válidos são:
Qualquer combinação de caracteres é válida. |
Promotions / HotelPromotions / Promotion / BookingWindow | 0..1 | BookingWindow | Especifica o período em que a reserva precisa ocorrer em relação à data do check-in (com base no fuso horário da propriedade). Por exemplo, a janela de reserva pode ser definida como de 7 a 180 dias antes do check-in. |
Promotions / HotelPromotions / Promotion / BookingWindow / @min | 0..1 | integer or duration | A duração mínima antes do check-in, quando a reserva precisa ocorrer
para que a promoção seja aplicada. Se isso não for especificado ou o valor
for 0 , não há valor mínimo.
Os tipos de valor válidos são:
|
Promotions / HotelPromotions / Promotion / BookingWindow / @max | 0..1 | integer or duration | O número máximo de dias antes do check-in em que a reserva precisa ocorrer
para que a promoção seja aplicada. Se isso não for especificado ou o valor
for 0 , não haverá um valor máximo.
Os tipos de valor válidos são:
|
Promotions / HotelPromotions / Promotion / Ceiling | 0..1 | Ceiling |
Define restrições sobre o valor máximo que uma taxa pode ser definida depois que as promoções são aplicadas. As promoções sempre precisam especificar um Se o empilhamento estiver configurado, várias promoções com Exemplos Preços de uma estadia em que
Esta é a ordem de cálculo:
O fato de 60 é um limite geral mais rigoroso é irrelevante, já que é válido apenas para sua própria promoção, e não pode haver um limite único que abranja toda a pilha de promoções. |
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night | 1 | float |
O valor máximo de definição de uma tarifa por noite após a aplicação do desconto. Se um elemento
|
Promotions / HotelPromotions / Promotion / Floor | 0..1 | Floor |
Define restrições sobre o valor mínimo que pode ser definido para uma taxa depois que as promoções são aplicadas. As promoções sempre precisam especificar um A lógica Se o empilhamento estiver configurado, várias promoções com Exemplos Preços de uma estadia em que
Esta é a ordem de cálculo:
O fato de que 90 é um valor mínimo mais rigoroso é irrelevante, já que ele é válido apenas para a própria promoção, e não pode haver um único andar que abranja toda a pilha de promoções. |
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night | 1 | float |
O valor mínimo para definir uma tarifa por noite após a aplicação do desconto. Se um elemento
|
Promotions / HotelPromotions / Promotion / CheckinDates | 0..1 | CheckinDates | Um contêiner para um ou mais períodos que definem quando o check-in precisa ocorrer para que a promoção seja aplicada. |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange | 1..20 | DateRange | Um período que especifica quando o check-in precisa ocorrer para que a promoção seja aplicada. Esse elemento não será necessário se você estiver excluindo uma ou mais promoções. O formato YearlessDate também é aceito.
|
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @start | 0..1 | Date or YearlessDate | A data de início (com base no fuso horário da propriedade), inclusive, do período. Essa data precisa ser anterior ou igual à data de end . Se start não for especificado, o período
será efetivamente ilimitado em termos de data de início. |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @end | 0..1 | Date or YearlessDate | A data de término do período, com base no fuso horário da propriedade. Essa data precisa ser igual ou posterior à data start . Se end não for especificado, o período
será efetivamente ilimitado em termos de data de término. |
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @days_of_week | 0..1 | string | Os dias da semana permitidos no período. Se não for especificado, todos os dias serão permitidos no período. Cada caractere da string especifica um dia. Por exemplo, "MTWHF" especifica que os dias da semana são permitidos no período. Os caracteres válidos são:
Qualquer combinação de caracteres é válida. |
Promotions / HotelPromotions / Promotion / CheckoutDates | 0..1 | CheckoutDates | Um contêiner para um ou mais períodos que definem quando o check-out precisa ocorrer para que a promoção seja aplicada. |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange | 1..20 | DateRange | Um período que especifica quando o check-out precisa ocorrer para que a promoção seja aplicada. Esse elemento não será necessário se você estiver excluindo uma ou mais promoções. O formato YearlessDate também é aceito.
|
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @start | 0..1 | Date or YearlessDate | A data de início (com base no fuso horário da propriedade), inclusive, do período. Essa data precisa ser anterior ou igual à data de end . Se start não for especificado, o período
será efetivamente ilimitado em termos de data de início. |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @end | 0..1 | Date or YearlessDate | A data de término do período, com base no fuso horário da propriedade. Essa data precisa ser igual ou posterior à data start . Se end não for especificado, o período
será efetivamente ilimitado em termos de data de término. |
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @days_of_week | 0..1 | string | Os dias da semana permitidos no período. Se não for especificado, todos os dias serão permitidos no período. Cada caractere da string especifica um dia. Por exemplo, "MTWHF" especifica que os dias da semana são permitidos no período. Os caracteres válidos são:
Qualquer combinação de caracteres é válida. |
Promotions / HotelPromotions / Promotion / Devices | 0..1 | Devices | Contêiner para listar os dispositivos de usuários qualificados para a promoção. Se especificado, somente os usuários qualificados nos dispositivos listados recebem a tarifa com desconto. Se não for especificada, a tarifa com desconto vai ser oferecida aos usuários qualificados em qualquer dispositivo. |
Promotions / HotelPromotions / Promotion / Devices / Device | 1..3 | Device | Define um tipo de dispositivo do usuário qualificado para a promoção. |
Promotions / HotelPromotions / Promotion / Devices / Device / @type | 1 | enum | Um tipo de dispositivo. O valor precisa ser desktop ,
tablet ou mobile . |
Promotions / HotelPromotions / Promotion / Discount | 1 | Discount | É preciso especificar exatamente Especifica o desconto a ser aplicado para esta promoção. |
Promotions / HotelPromotions / Promotion / Discount / @percentage | 0..1 | float | É obrigatório ter exatamente Um valor decimal de 0 a 100 que especifica o desconto percentual.
Ela é aplicada a Exemplos:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount | 0..1 | float | É obrigatório ter exatamente Um valor fixo a ser subtraído da soma das tarifas por noite de Exemplos:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night | 0..1 | float | É obrigatório ter exatamente Um desconto fixo aplicado a cada uma das diárias de Exemplos:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_price | 0..1 | float | É obrigatório ter exatamente Se as tarifas por noite de Se o objetivo de Exemplos:
|
Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night | 0..1 | float | É obrigatório ter exatamente Se as taxas de Se o objetivo de Se Exemplos:
|
Promotions / HotelPromotions / Promotion / Discount / @applied_nights | 0..1 | integer | Só deve ser usada com
O número de noites a que o desconto é aplicado, começando pela mais barata. Precisa ser um número inteiro de 1 a 99. Se não for especificado, o desconto será aplicado a todas as noites. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights | 0..1 | FreeNights | Especifica um desconto em determinadas noites de uma estadia quando a duração mínima
da estadia é atingida. Se esse elemento for usado, atributos no elemento pai Discount
não serão permitidos. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights | 1 | integer | Número de noites necessárias para o desconto ser aplicado. Cada desconto é aplicado a um segmento separado de diárias de estadia. Por exemplo, para uma estadia de 10 noites em que |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_nights | 1 | integer | O número de noites com desconto em cada segmento de diárias de estadia. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage | 1 | float | O desconto aplicado às noites de desconto. Se esse valor
for 50 , cada diária selecionada vai ter 50% de desconto. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection | 1 | string | Precisa ser cheapest ou last . Se for last , as noites no final do segmento de estadia são descontadas. Se cheapest , as noites mais baratas dentro do segmento de noites de estadia têm desconto. |
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats | 1 | boolean | Define se o desconto pode ser aplicado a vários segmentos de estadia. Se for Por exemplo, se |
Promotions / HotelPromotions / Promotion / Discount / @rank | 0..1 | integer | Atribui uma classificação a essa promoção e a ativa na seleção classificada, em que apenas a promoção com a menor classificação é selecionada para ser aplicada. Os valores precisam estar entre 1 e 99. Se várias promoções compartilharem a mesma classificação, uma delas será selecionada e aplicada arbitrariamente. |
Promotions / HotelPromotions / Promotion / BestDailyDiscount | 1 | Discount | É preciso especificar exatamente Especifica um desconto diário que pode ser aplicado a uma noite de estadia. Isso contrasta com o Cada propriedade pode ter um único grupo de promoções que são consideradas "melhores diários". Isso significa que a promoção "melhor diária" de cada noite de estadia é selecionada e pode ser aplicada.
|
Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage | 0..1 | float | É necessário ter exatamente Um valor decimal de 0 a 100 que especifica o desconto percentual.
Ela é aplicada a Exemplos:
|
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount | 0..1 | float | É necessário ter exatamente Um valor fixo a ser subtraído de uma única tarifa
de Exemplos:
|
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price | 0..1 | float | É necessário ter exatamente Se as tarifas por noite de Exemplos:
|
Promotions / HotelPromotions / Promotion / InventoryCount | 0..1 | InventoryCount | Define restrições sobre o número de quartos que precisam estar disponíveis para que essa promoção seja aplicada. O desconto é aplicado apenas às noites que atendem à restrição. Não permitido com o desconto de fixed_amount . O número de quartos disponíveis é especificado com OTA_HotelInvCountNotifRQ (InvCount ) ou OTA_HotelAvailNotifRQ (BookingLimit ). |
Promotions / HotelPromotions / Promotion / InventoryCount / @min | 0..1 | integer | O número mínimo de quartos que precisam estar disponíveis para que a promoção seja aplicada à diária. Se isso não for especificado, não haverá um mínimo. |
Promotions / HotelPromotions / Promotion / InventoryCount / @max | 0..1 | integer | O número máximo de quartos que precisam estar disponíveis para que a promoção seja aplicada à diária. Se isso não for especificado, não haverá um valor máximo. |
Promotions / HotelPromotions / Promotion / LengthOfStay | 0..1 | LengthOfStay | Define os limites de duração da estadia dentro dos quais esta promoção pode ser aplicada. A promoção não é aplicada quando a duração da estadia está fora dos limites mínimo e máximo. |
Promotions / HotelPromotions / Promotion / LengthOfStay / @min | 0..1 | integer | O número mínimo de noites permitidas na estadia para que a promoção seja aplicada. Se isso não for especificado, não há um valor mínimo. |
Promotions / HotelPromotions / Promotion / LengthOfStay / @max | 0..1 | integer | O número máximo de noites permitidas na estadia para que a promoção seja aplicada. Se isso não for especificado, não haverá um valor máximo. |
Promotions / HotelPromotions / Promotion / MembershipRateRule | 0..1 | MembershipRateRule |
Contêiner de uma regra de tarifação de associação que aciona um tratamento de IU específico para o desconto associado. Esse elemento não deve ser especificado, a menos que |
Promotions / HotelPromotions / Promotion / MembershipRateRule / @id | 1 | string |
ID da regra de tarifação associada a um programa de assinatura. |
Promotions / HotelPromotions / Promotion / MinimumAmount | 0..1 | MinimumAmount | Especifica a soma mínima das diárias de quarto diárias (usando o maior valor de AmountBeforeTax ou AmountAfterTax ) que precisam ser excedidas para que a promoção seja aplicada. |
Promotions / HotelPromotions / Promotion / MinimumAmount / @before_discount | 1 | integer | O valor que precisa ser excedido para que a promoção seja aplicada. |
Promotions / HotelPromotions / Promotion / Occupancy | 0..1 | Occupancy | Define restrições de ocupação para as quais esta promoção é aplicada. A promoção não é aplicada quando a ocupação está fora dos limites mínimo e máximo. |
Promotions / HotelPromotions / Promotion / Occupancy / @min | 0..1 | integer | A ocupação especificada pelo usuário precisa ser pelo menos desse valor para que o desconto seja aplicado. |
Promotions / HotelPromotions / Promotion / Occupancy / @max | 0..1 | integer | A ocupação especificada pelo usuário precisa ser no máximo esse valor para que o desconto seja aplicado. |
Promotions / HotelPromotions / Promotion / RatePlans | 0..1 | RatePlans | Contêiner de uma lista de planos de tarifas a que a promoção se aplica.
Se <RatePlans> não for especificado, a promoção
será aplicada a todos os planos de preços. |
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan | 1..n | RatePlan | Especifica um plano de tarifa. Um plano de tarifas é definido por uma combinação de pacotes, tarifas e disponibilidade, conforme definido nas mensagens de transação (dados da propriedade), OTA_HotelRateAmountNotifRQ e OTA_HotelAvailNotifRQ e identificado pelo PackageID. |
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id | 1 | string | O identificador exclusivo do plano de tarifa. Esse valor é mapeado para o valor de PackageID em <PackageData> em uma mensagem de Transação (dados da propriedade) e no atributo RatePlanCode em <StatusApplicationControl> nas mensagens <OTA_HotelRateAmountNotifRQ> e <OTA_HotelAvailNotifRQ> .
O número máximo de caracteres permitido é 50. |
Promotions / HotelPromotions / Promotion / RoomTypes | 0..1 | RoomTypes | Contêiner com uma lista de tipos de quarto a que a promoção se aplica.
A promoção é aplicada a cada <RoomType>
especificado. Se <RoomTypes> não for especificado, a
promoção vai ser aplicada a todos os quartos. |
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType | 1..n | RoomType | Especifica um tipo de quarto. Um tipo de quarto é definido em um elemento <RoomData> em uma mensagem de transação (dados da propriedade) e é referenciado usando o valor <RoomID> . O valor <RoomID> também é referenciado pelo atributo InvTypeCode nas mensagens OTA_HotelRateAmountNotifRQ. |
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id | 1 | string | O identificador exclusivo do inventário (tipo de quarto). Esse valor é mapeado para <RoomID> em uma mensagem de transação (dados da propriedade).
O número máximo de caracteres permitido é 50. |
Promotions / HotelPromotions / Promotion / Stacking | 0..1 | Stacking | Especifica como as promoções podem ser combinadas. Se não for especificado, o "tipo"
será considerado base . |
Promotions / HotelPromotions / Promotion / Stacking / @type | 1 | enum | Várias promoções podem ser aplicadas a uma única taxa, dependendo dessa configuração:
Das combinações permitidas, o conjunto de promoções que gera o maior desconto é aplicado à taxa. |
Promotions / HotelPromotions / Promotion / StayDates | 0..1 | StayDates | Um contêiner para um ou mais períodos que determinam como a promoção é aplicada, por exemplo, para acomodar descontos sazonais. |
Promotions / HotelPromotions / Promotion / StayDates / @application | 1 | enum | Descreve como aplicar a promoção. Os valores válidos são:
Esse atributo precisa ser sempre especificado.
|
Promotions / HotelPromotions / Promotion / StayDates / DateRange | 1..99 | DateRange | Um período que especifica as datas em que a promoção será aplicada. O formato YearlessDate também é aceito.
|
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @start | 0..1 | Date or YearlessDate | A data de início (com base no fuso horário da propriedade), inclusive, do período. Essa data precisa ser anterior ou igual à data de end . Se start não for especificado, o período
será efetivamente ilimitado em termos de data de início. |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end | 0..1 | Date or YearlessDate | A data de término do período, com base no fuso horário da propriedade. Essa data precisa ser igual ou posterior à data start . Se end não for especificado, o período
será efetivamente ilimitado em termos de data de término. |
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @days_of_week | 0..1 | string | Os dias da semana permitidos no período. Se não for especificado, todos os dias serão permitidos no período. Cada caractere da string especifica um dia. Por exemplo, "MTWHF" especifica que os dias da semana são permitidos no período. Os caracteres válidos são:
Qualquer combinação de caracteres é válida. |
Promotions / HotelPromotions / Promotion / UserCountries | 0..1 | UserCountries | Contêiner para listar os locais dos usuários (países) qualificados para a promoção. Se especificado, somente os usuários qualificados nos países listados recebem a taxa com desconto. Se não for especificada, a tarifa com desconto vai ser oferecida aos usuários qualificados em qualquer país. |
Promotions / HotelPromotions / Promotion / UserCountries / @type | 0..1 | enum | O tipo de especificação UserCountry.
Os valores válidos são Se o campo Se o Se o campo |
Promotions / HotelPromotions / Promotion / UserCountries / Country | 1..300 | Country | Define um país onde os usuários estão qualificados para a promoção. |
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code | 1 | string | Um código de país CLDR (link em inglês), como DE ou FR . Em alguns casos, o código CLDR não é igual ao código ISO de duas letras. Além disso, códigos de região CLDR não são compatíveis. |
Exemplos
Mensagem básica
O exemplo a seguir mostra uma mensagem Promotions
básica:
<?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>
Condição de inventário
O exemplo a seguir mostra como criar um desconto se houver inventário em excesso perto da data de chegada:
<?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>
Excluir uma promoção
O exemplo a seguir mostra como excluir uma promoção de uma propriedade:
<?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>
Excluir todas as promoções
O exemplo a seguir mostra como excluir todas as promoções de uma propriedade:
<?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>
Sobrepor todas as promoções
O exemplo a seguir mostra como sobrepor <HotelPromotions>
em uma propriedade com uma ou mais promoções novas. Quando action="overlay"
, todas as promoções armazenadas são excluídas antes de armazenar as promoções especificadas na mensagem atual:
<?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>
Três tipos diferentes de empilhamento
O exemplo a seguir mostra um caso em que três promoções diferentes seriam
aplicadas (base
, second
, any
). A promoção none
não seria
aplicada, já que as outras promoções oferecem um desconto melhor. Se o preço
original fosse de US $100, o preço com desconto seria de US $72,90.
<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
id="123_abc"
timestamp="2020-05-18T16:20:00-04:00">
<HotelPromotions hotel_id="Property_1">
<Promotion id="1">
<Discount percentage="10"/>
<Stacking type="base"/>
</Promotion>
<Promotion id="2">
<Discount percentage="10"/>
<Stacking type="second"/>
</Promotion>
<Promotion id="3">
<Discount percentage="10"/>
<Stacking type="any"/>
</Promotion>
<Promotion id="4">
<Discount percentage="25"/>
<Stacking type="none"/>
</Promotion>
</HotelPromotions>
</Promotions>
Nenhum tipo de empilhamento
O exemplo a seguir mostra um caso em que a promoção none
é usada porque a combinação de outras promoções oferece um desconto menor. Se o
preço original fosse de R $100, o preço com desconto seria de R $75.
<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
id="123_abc"
timestamp="2020-05-18T16:20:00-04:00">
<HotelPromotions hotel_id="Property_1">
<Promotion id="1">
<Discount percentage="10"/>
<Stacking type="base"/>
</Promotion>
<Promotion id="2">
<Discount percentage="10"/>
<Stacking type="any"/>
</Promotion>
<Promotion id="3">
<Discount percentage="25"/>
<Stacking type="none"/>
</Promotion>
</HotelPromotions>
</Promotions>
Limites de duração da janela de reserva
O exemplo a seguir mostra um caso em que o elemento BookingWindow
é usado com os limites inicial e final definidos como um tipo de duração
ISO 8601. Essa restrição de janela de reserva requer a reserva até as 18h do dia anterior à chegada e a partir das 12h no 2o dia antes da chegada.
<?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>
Limites de data e hora das datas de reserva
O exemplo a seguir mostra um caso em que o elemento BookingDates
é usado com os atributos start
e end
como
tipos DateTime. Essa restrição de data exige que a reserva ocorra entre 06h30 de 01/07/2020 e 18h45 de 02/07/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>
Períodos sem ano
O exemplo a seguir mostra um caso em que o elemento CheckInDates
contém DateRanges
que têm campos start
e
end
sem anos. Neste exemplo, a promoção se aplica a datas de check-in entre 29/12 e 2/1, independentemente do ano. Os períodos sem ano que ultrapassam o limite de ano novo são inválidos. Portanto, o período é expresso como dois períodos adjacentes.
<?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>
Desconto do FreeNights
O exemplo a seguir oferece um desconto de 50% em duas noites para cada quatro noites de estadia no período especificado de datas de reserva. Para um itinerário de dez noites, um total de quatro noites teria um desconto de 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>
O próximo exemplo dá um desconto de 50% em uma noite para cada três noites de estadia para os períodos especificados de estadia. Somente as noites de estadia sobrepostas contam para a qualificação para o desconto. Para o itinerário a seguir com check-in em 01/01/2022 e check-out em 07/01/2022, as noites qualificadas de estadia e descontos são aplicados da seguinte maneira.
- 01/01/2022 (estadia)
- 02/01/2022 (estadia)
- 2022-01-03
- 04/01/2022 (com desconto)
- 05/01/2022 (estadia)
- 06/01/2022 (estadia)
<?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>
Seleção classificada
O exemplo a seguir oferece dois descontos, um de 20% e outro de 15%. Durante a avaliação, apenas o desconto de 15% é aplicado porque tem uma classificação mais baixa.
<?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>
MelhorDescontoDiário
O exemplo a seguir desconta uma estadia de duas noites aplicando
BestDailyDiscount
empilhado com um 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>
Considere uma estadia de duas noites de 30 de abril de 2023 a 2 de maio de 2023. Para os cálculos, a combinação dos melhores descontos diários que gera o maior desconto é encontrada primeiro.
Para a primeira noite, a promoção "geral" é o único valor qualificado com um desconto fixo de 20.
Para a segunda noite, a promoção "pode" oferece um desconto maior do que o desconto "geral". Portanto, quando "Pode" for selecionado, o valor de desconto fixo será 50.
Para a estadia, a promoção "fiesta" oferece descontos para 5 por noite, ou
10 no total. Ele pode ser empilhado com a combinação dos melhores descontos diários,
porque "fiesta" tem o tipo de empilhamento definido como any
. Se ele fosse definido
como base
, apenas a combinação dos melhores descontos diários ou
o desconto "fiesta" será aplicada. Confira a descrição de
Stacking
para mais informações.
No geral, o preço da estadia recebe um desconto de valor fixo de 20 + 50 + 10 = 80.
Respostas
Sintaxe
A mensagem PromotionsResponse
usa a seguinte sintaxe:
<?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>
Elementos e atributos
A mensagem PromotionsResponse
tem os seguintes elementos e atributos:
Elemento / @Attribute | Ocorrências | Tipo | Descrição |
---|---|---|---|
PromotionsResponse | 1 | Complex element | O elemento raiz que indica o sucesso ou os problemas de uma mensagem de solicitação de promoções recebida. |
PromotionsResponse / @timestamp | 1 | DateTime | A data e a hora de criação da mensagem. |
PromotionsResponse / @id | 1 | string | O identificador exclusivo da mensagem de promoções associada. |
PromotionsResponse / @partner | 1 | string | A conta do parceiro para esta mensagem. |
PromotionsResponse / Success | 0..1 | Success | Indica que a mensagem de promoções foi processada sem avisos, erros ou falhas.
Cada mensagem tem |
PromotionsResponse / Issues | 0..1 | Issues | Um contêiner para um ou mais problemas encontrados ao processar a
Mensagem de promoções.
Cada mensagem tem |
PromotionsResponse / Issues / Issue | 1..n | Issue | A descrição de um aviso, erro ou falha encontrada ao processar a mensagem de promoções. Confira detalhes sobre esses problemas em Mensagens de erro de status do feed. |
PromotionsResponse / Issues / Issue / @code | 1 | integer | O identificador do problema. |
PromotionsResponse / Issues / Issue / @status | 1 | enum | O tipo de problema encontrado. Os valores válidos são |
Exemplos
Concluído
Esta é uma resposta a uma mensagem de promoções processada.
<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="2020-05-18T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Success/>
</PromotionsResponse>
Issues
Esta é uma resposta a uma Mensagem de promoção não processada devido a erros.
<?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>