Promoções

Visão geral

Com essa API, você pode especificar possíveis descontos. Das promoções especificadas, o Google aplica a promoção ou o conjunto de promoções qualificados que resultam no menor preço. Se você estiver procurando uma API que ofereça suporte a ajustes de taxa arbitrários que podem aumentar ou diminuir o preço quando as condições forem atendidas, considere a API Rate Modifications. Se as duas APIs estiverem presentes, as modificações de taxa serão aplicadas antes das promoções.

Solicitações

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, 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>

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ção.
Promotions / @partner	1	string	A conta de parceiro desta mensagem. Esse valor de string é a "Chave do parceiro" listada na página "Configurações da conta" da Central para Hotéis. Se você tiver um back-end que forneça feeds para várias contas, esse valor precisará corresponder ao valor do atributo ID especificado no elemento <RequestorID> das mensagens <OTA_HotelRateAmountNotifRQ> e <OTA_HotelAvailNotifRQ> para a mesma conta.
Promotions / @id	1	string	Um identificador exclusivo para esta mensagem de solicitação. Esse valor é retornado na mensagem de resposta. Os caracteres permitidos são a-z, A-Z, 0-9, _ (sublinhado) e - (traço).
Promotions / @timestamp	1	DateTime	A data e a hora de criação desta mensagem.
Promotions / HotelPromotions	0..n	HotelPromotions	Promoções de uma propriedade. Cada promoção se aplica a uma única propriedade. A menos que <Stacking> seja usado, a promoção com o maior desconto será aplicada à reserva quando várias promoções forem qualificadas.
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> do feed de lista de hotéis. O ID do hotel também está listado na Central para Hotéis.
Promotions / HotelPromotions / @action	0..1	enum	Se especificado, o valor precisa ser "overlay". Quando o valor é "overlay", todas as promoções armazenadas são excluídas antes de armazenar as promoções especificadas na mensagem atual. Se não for especificado, cada promoção na mensagem atual será: Added (se nenhuma das promoções armazenadas tiver o mesmo id) Updated (se uma promoção armazenada tiver o mesmo id) Deleted (se uma promoção armazenada tiver o mesmo id e o valor do atributo action para a promoção especificada na mensagem atual for "delete")
Promotions / HotelPromotions / Promotion	0..99	Promotion	Uma única promoção para uma propriedade. Se action="overlay" e um <Promotion> não forem especificados, todas as promoções da propriedade serão excluídas. 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	Um 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), - (traço) e . (ponto final).
Promotions /HotelPromotions / Promotion / @action	0..1	enum	Se especificado, o valor precisa ser delete. Se não for especificado e uma promoção com o mesmo id não for armazenada, essa promoção será armazenada. Caso contrário, se não for especificado e uma promoção com o mesmo id for armazenada, a promoção atual será atualizada. Se delete for especificado, a promoção armazenada com o mesmo id será excluída. Ao usar delete, não inclua elementos filhos em <Promotion>. Além disso, delete não é permitido com <HotelPromotions action="overlay"/>.
Promotions / HotelPromotions / Promotion / BookingDates	0..1	BookingDates	Um contêiner para um ou mais intervalos que definem quando a reserva precisa ser feita para que a promoção seja aplicada.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange	1..99	DateRange	Um intervalo que especifica quando a reserva precisa ser feita 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 período. A data ou data e hora especificada por start precisa ser anterior ou igual à data ou data e hora especificada por end. Se start não for especificado, o intervalo será efetivamente ilimitado em termos de horário de início. Se start for preenchido como data "AAAA-MM-DD", ele será interpretado como data e hora "AAAA-MM-DDT00:00:00".
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end	0..1	Date ou DateTime	A data ou data e hora de término (com base no fuso horário da propriedade), inclusive, do período. A data ou data/hora especificada por end precisa ser posterior ou igual à data ou data/hora especificada por start. Se end não for especificado, o intervalo será efetivamente ilimitado em termos de horário de término. Se end for fornecido como data "AAAA-MM-DD", ele será interpretado como data e hora "AAAA-MM-DDT23:59:59".
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 na 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: M para segunda-feira T para terça-feira W para quarta-feira H para quinta-feira F para sexta-feira S para sábado U para domingo 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 de check-in (com base no fuso horário da propriedade). Por exemplo, a janela de reserva pode ser definida para pelo menos 7 dias, mas não mais de 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 em que a reserva precisa ser feita para que a promoção seja aplicada. Se não for especificado ou se o valor for 0, não haverá um mínimo. Os tipos de valor válidos são: Número inteiro:o número de dias antes da data de check-in. Por exemplo, um valor de 30 indica que a promoção só se aplica a reservas feitas pelo menos 30 dias antes da data de check-in. Duração ISO 8601 (dias, horas e minutos): o número de dias (e, opcionalmente, horas/minutos) antes da data de check-in. Por exemplo, um valor de P30D indica que a promoção só se aplica a reservas feitas pelo menos 30 dias antes da data de check-in. Um valor de P30DT6H exige reserva até as 18h do 30º dia antes da chegada.
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 ser feita para que a promoção seja aplicada. Se não for especificado ou se o valor for 0, não haverá valor máximo. Os tipos de valor válidos são: Número inteiro:o número de dias antes da data de check-in. Por exemplo, um valor de 30 indica que a promoção só se aplica a reservas feitas no máximo 30 dias antes da data de check-in. Duração ISO 8601 (dias, horas e minutos): o número de dias (e, opcionalmente, horas/minutos) antes da data de check-in. Por exemplo, um valor de P30D indica que a promoção só se aplica a reservas feitas no máximo 30 dias antes da data de check-in. Um valor de P30DT6H exige uma reserva a partir das 18h do 30º dia antes da chegada.
Promotions / HotelPromotions / Promotion / Ceiling	0..1	Ceiling	Define restrições no valor máximo que uma tarifa pode ter depois que as promoções são aplicadas. As promoções sempre precisam especificar um <Discount> ou um <BestDailyDiscount>. Portanto, para criar uma promoção que aplique apenas um <Ceiling>, uma opção é definir um <Discount> com um percentage de 0. Se o acúmulo estiver configurado, várias promoções com <Ceiling> poderão ser aplicadas a uma única estadia. Cada promoção aplicaria o desconto, seguido imediatamente pelo limite. O exemplo a seguir demonstra como cada teto contribui para o próximo cálculo de promoção na pilha. Exemplo: Preço de uma estadia de uma noite em que AmountBeforeTax é 100 e há uma pilha de duas promoções: Promoção com tipo de combinação base, um fixed_amount de 25 e um limite máximo amount_per_night de 60 Promoção com tipo de combinação second, fixed_amount de 25 e um limite máximo amount_per_night de 90 Esta é a ordem de cálculo: A promoção de base é aplicada primeiro e reduz o AmountBeforeTax para 75, mas depois o limite diminui para 60. A promoção second reduz o AmountBeforeTax de 60 para 35. Esse valor está abaixo do limite de 90, então o segundo limite não é aplicado. A taxa final é 35. O fato de 60 ser um limite máximo geral mais restrito é irrelevante, já que ele é válido apenas para a própria promoção, e não pode haver um limite máximo único que abranja toda a pilha de promoções.
Promotions / HotelPromotions / Promotion / Ceiling / @amount_per_night	1	float	O valor máximo que uma tarifa noturna pode ter depois da aplicação do desconto. Se um elemento <Floor> também for especificado, ele precisará ser definido como um valor maior ou igual ao atributo amount_per_night em <Floor>. amount_per_night é aplicado a tributos e taxas quando eles são incluídos na tarifa por noite usando AmountAfterTax, mas não aqueles especificados usando TaxFeeInfo.
Promotions / HotelPromotions / Promotion / Floor	0..1	Floor	Define restrições no valor mínimo que uma tarifa pode ser definida depois que as promoções são aplicadas. As promoções sempre precisam especificar um <Discount> ou um <BestDailyDiscount>. Portanto, para criar uma promoção que aplique apenas um <Floor>, uma opção é definir um <Discount> com um percentage de 0. A lógica de <Floor> ainda se aplica aos descontos de <FreeNights>, mesmo que a noite sem custo financeiro tenha um desconto de 100% aplicado a ela. Se o acúmulo estiver configurado, várias promoções com <Floor> poderão ser aplicadas a uma única estadia. Cada promoção aplicaria o desconto, seguido imediatamente pelo preço mínimo. O exemplo a seguir demonstra como cada valor mínimo contribui para o próximo cálculo de promoção na pilha. Exemplo: Preço de uma estadia de uma noite em que AmountBeforeTax é 100 e há uma pilha de duas promoções: Promoção com tipo de combinação base, um fixed_amount de 25 e um valor mínimo amount_per_night de 90 Promoção com tipo de combinação second, fixed_amount de 25 e um valor mínimo amount_per_night de 60 Esta é a ordem de cálculo: A promoção de base é aplicada primeiro e reduz o AmountBeforeTax para 75, mas depois o valor mínimo aumenta para 90. A promoção second reduz o AmountBeforeTax de 90 para 65. Esse valor está acima do mínimo de 60, então o segundo limite não é aplicado. A taxa final é 65. O fato de 90 ser um limite mínimo geral mais restrito é irrelevante, já que ele é válido apenas para a própria promoção, e não pode haver um único limite mínimo que abranja toda a pilha de promoções.
Promotions / HotelPromotions / Promotion / Floor / @amount_per_night	1	float	O valor mínimo que uma diária pode ter após a aplicação do desconto. Se um elemento <Ceiling> também for especificado, esse valor precisará ser menor ou igual ao atributo amount_per_night em <Ceiling>. amount_per_night é aplicado a tributos e taxas quando eles são incluídos na tarifa por noite usando AmountAfterTax, mas não aqueles especificados usando TaxFeeInfo.
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 é obrigatório se você estiver excluindo uma ou mais promoções. O formato YearlessDate também é compatível. Se um dos campos start ou end for uma data sem ano, os dois precisarão ser preenchidos como datas sem ano. Os períodos sem ano não podem envolver o ano-novo. Em vez disso, represente o intervalo como dois períodos adjacentes. Por exemplo, {"12-29", "01-05"} pode ser representado como {"12-29", "12-31"} e {"01-01", "01-05"}.
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á ilimitado em termos de data de início.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @end	0..1	Date or YearlessDate	A data de término (com base no fuso horário da propriedade), inclusive, do período. Essa data precisa ser igual ou posterior à data de 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 na 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: M para segunda-feira T para terça-feira W para quarta-feira H para quinta-feira F para sexta-feira S para sábado U para domingo 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 pagamento precisa ser feito para que a promoção seja aplicada.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange	1..20	DateRange	Um período especificando quando o check-out precisa ocorrer para que a promoção seja aplicada. Esse elemento não é obrigatório se você estiver excluindo uma ou mais promoções. O formato YearlessDate também é compatível. Se um dos campos start ou end for uma data sem ano, os dois precisam ser preenchidos como datas sem ano. Os períodos sem ano não podem envolver o ano-novo. Em vez disso, represente o intervalo como dois períodos adjacentes. Por exemplo, {"12-29", "01-05"} pode ser representado como {"12-29", "12-31"} e {"01-01", "01-05"}.
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á ilimitado em termos de data de início.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @end	0..1	Date or YearlessDate	A data de término (com base no fuso horário da propriedade), inclusive, do período. Essa data precisa ser igual ou posterior à data de 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 na 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: M para segunda-feira T para terça-feira W para quarta-feira H para quinta-feira F para sexta-feira S para sábado U para domingo Qualquer combinação de caracteres é válida.
Promotions / HotelPromotions / Promotion / Devices	0..1	Devices	Contêiner para listar os dispositivos do usuário qualificados para a promoção. Se especificado, somente os usuários qualificados nos dispositivos listados vão receber a tarifa com desconto. Se não for especificado, os usuários qualificados em qualquer dispositivo vão receber a taxa com desconto.
Promotions / HotelPromotions / Promotion / Devices / Device	1..3	Device	Define um tipo de dispositivo do usuário que está 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 um de Discount ou BestDailyDiscount. Especifica o desconto a ser aplicado a esta promoção.
Promotions / HotelPromotions / Promotion / Discount / @percentage	0..1	float	É necessário exatamente um dos seguintes campos: percentage, percentage_of_base, fixed_amount, fixed_amount_per_night, fixed_price ou fixed_price_per_night. Um valor decimal de 0 a 100 que especifica o desconto percentual. Ele é aplicado a AmountAfterTax (ou AmountBeforeTax se AmountAfterTax não for especificado). Exemplos: Se AmountAfterTax for 100 e percentage for 20, então taxa de promoção = AmountAfterTax * (1 - desconto percentual) 80,00 = 100 * (1 - 0,2) Se AmountBeforeTax for 100, percentage for 20 e TaxFeeInfo especificar um tributo de 10, então taxa promocional = AmountBeforeTax * (1 - desconto percentual) + tributos 90,00 = 100 * (1 - 0,2) + 10
Promotions / HotelPromotions / Promotion / Discount / @percentage_of_base	0..1	float	É necessário exatamente um dos seguintes campos: percentage, percentage_of_base, fixed_amount, fixed_amount_per_night, fixed_price ou fixed_price_per_night. Um valor decimal de 0 a 100 que especifica a porcentagem do desconto básico. Semelhante a percentage, ele é aplicado a AmountAfterTax (ou AmountBeforeTax se AmountAfterTax não for especificado). Ao contrário de percentage, esse desconto é sempre calculado como uma porcentagem das tarifas básicas, independentemente das promoções anteriores que foram aplicadas em sequência. Exemplo: Suponha que temos duas promoções aplicadas em sequência a uma estadia de uma noite com preço de 100. O primeiro é um desconto percentual normal de 10%, e o segundo é um desconto percentual de 10% do preço básico. Então, a taxa com desconto será 80, já que as duas promoções tiram 10. Se a segunda promoção também fosse um desconto percentual regular, a taxa com desconto seria 81, já que a segunda promoção desconta 10% de 90.
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount	0..1	float	É necessário exatamente um dos seguintes campos: percentage, percentage_of_base, fixed_amount, fixed_amount_per_night, fixed_price ou fixed_price_per_night. Um valor fixo a ser subtraído da soma das diárias de AmountAfterTax (ou da soma das diárias de AmountBeforeTax se AmountAfterTax não for especificado). Ela é considerada na mesma moeda das tarifas noturnas. Se esse valor for maior que a soma das tarifas noturnas, o valor resultante será zero. Exemplos: Se estivermos definindo o preço de uma estadia de uma noite em que AmountBeforeTax é 90, AmountAfterTax é 100 e fixed_amount é 20, então taxa promocional = AmountAfterTax - desconto fixo 80,00 = 100 - 20 Se estivermos precificando uma estadia de uma noite em que AmountBeforeTax é 100, fixed_amount é 20 e TaxFeeInfo especifica um tributo de 8%, então taxa promocional = (AmountBeforeTax - desconto fixo) * (1 + tributo percentual) 86,40 = (100 - 20) * 1,08 Se estivermos calculando o preço de uma estadia de uma noite em que AmountBeforeTax é 50, fixed_amount é 60 e TaxFeeInfo especifica um tributo de 10, então taxa promocional = (AmountBeforeTax - desconto fixo) * tributo 10,00 = 0 + 10 Se estivermos calculando o preço de uma estadia de três noites em que os valores de AmountAfterTax são 100, 110 e 120, e fixed_amount é 150, então taxa de promoção = sum(AmountAfterTax) - (desconto fixo) 180,00 = (100 + 110 + 120) - 150
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night	0..1	float	É necessário exatamente um dos seguintes campos: percentage, percentage_of_base, fixed_amount, fixed_amount_per_night, fixed_price ou fixed_price_per_night. Um desconto fixo aplicado a cada uma das AmountAfterTax diárias (ou as N mais baratas se applied_nights for especificado). Se AmountAfterTax não for especificado, ele será aplicado a AmountBeforeTax. Ela é considerada na mesma moeda das tarifas noturnas. Se fixed_amount_per_night for maior que uma tarifa por noite, essa tarifa será reduzida a zero. O desconto não pode fazer com que uma tarifa por noite fique negativa. Exemplos: Se estivermos calculando o preço de uma estadia de três noites em que os valores de AmountAfterTax são 100, 110 e 120, e o fixed_amount_per_night é 10, então taxa de promoção = soma(AmountBeforeTax - desconto de valor fixo) 300,00 = ((100 - 10) + (110 - 10) + (120 - 10)) Se estivermos precificando uma estadia de três noites em que os valores de AmountAfterTax são 10, 50 e 100, e o fixed_amount_per_night é 20, então taxa de promoção = soma(AmountAfterTax - desconto de valor fixo) 110,00 = (0 + (50 - 20) + (100 - 20))
Promotions / HotelPromotions / Promotion / Discount / @fixed_price	0..1	float	É necessário exatamente um dos seguintes campos: percentage, percentage_of_base, fixed_amount, fixed_amount_per_night, fixed_price ou fixed_price_per_night. Se as tarifas por noite de AmountAfterTax forem especificadas, isso definirá o preço da estadia, incluindo tributos e taxas, para o valor especificado. Se AmountBeforeTax for especificado, independente de AmountAfterTax ser especificado ou não, isso vai definir o preço sem tributos da estadia como o valor especificado. Ela é considerada na mesma moeda das tarifas noturnas. Se AmountAfterTax for uma porcentagem de tributo, definir um preço fixo para AmountBeforeTax poderá resultar em tributos e taxas incorretos. Em geral, é altamente recomendável usar TaxFeeInfo para especificar os tributos e taxas de uma propriedade. Exemplos: Se estivermos definindo o preço de uma estadia de uma noite em que AmountBeforeTax é 90, AmountAfterTax é 100 e fixed_price é 80, a taxa de promoção será 80. Se estivermos definindo o preço de uma estadia de uma noite em que AmountBeforeTax é 100, fixed_amount é 80 e TaxFeeInfo especifica um tributo de 8%, então taxa promocional = preço fixo * (1 + tributo percentual) 86,40 = 80 * 1,08 Se estivermos precificando uma estadia de três noites em que os valores de AmountAfterTax são 100, 110 e 120, e fixed_amount é 300, então promotion rate = 300
Promotions / HotelPromotions / Promotion / Discount / @fixed_price_per_night	0..1	float	É necessário exatamente um dos seguintes campos: percentage, percentage_of_base, fixed_amount, fixed_amount_per_night, fixed_price ou fixed_price_per_night. Se as tarifas por noite de AmountAfterTax forem especificadas, isso definirá o preço de cada noite de estadia, incluindo tributos e taxas, para o valor especificado. Se AmountBeforeTax for especificado, independente de AmountAfterTax ser especificado ou não, isso vai definir o preço sem tributos para cada noite de estadia com o valor especificado. Ela é considerada na mesma moeda das tarifas noturnas. Se AmountAfterTax for uma porcentagem de tributo, definir um preço fixo para AmountBeforeTax poderá resultar em tributos e taxas incorretos. Em geral, é altamente recomendável usar TaxFeeInfo para especificar os tributos e taxas de uma propriedade. Se applied_nights for especificado, o novo preço será aplicado às N noites mais baratas. Exemplos: Se estivermos calculando o preço de uma estadia de duas noites em que os valores de AmountBeforeTax são 90, 90; os valores de AmountAfterTax são 100, 100; e fixed_price é 80, a taxa de promoção será 80 + 80 = 160. Se estivermos definindo o preço de uma estadia de duas noites em que AmountBeforeTax é 100, 100; fixed_amount é 80 e TaxFeeInfo especifica um tributo de 8%, a taxa promocional será (80 + 80) * 1,08 = 172,8. Se estivermos precificando uma estadia de três noites em que os valores de AmountAfterTax são 100, 110 e 120, e fixed_amount é 110, a taxa promocional será 110 * 3 = 330.
Promotions / HotelPromotions / Promotion / Discount / @applied_nights	0..1	integer	Isso só deve ser usado com percentage ou fixed_amount_per_night. 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 uma duração mínima de estadia é atendida. Não é permitido usar atributos no elemento Discount pai se esse elemento for usado.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @stay_nights	1	integer	Número de noites necessárias para que o desconto seja aplicado. Cada desconto é aplicado a um segmento separado de noites de estadia. Por exemplo, para uma estadia de 10 noites em que stay_nights é 4 (e repeats é verdadeiro), há dois segmentos de noite de estadia: da 1ª à 4ª noite e da 5ª à 8ª noite. A 9ª e a 10ª noite não fazem parte de um segmento de noite de estadia.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_nights	1	integer	O número de noites com desconto em cada segmento de noites de estadia.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @discount_percentage	1	float	O desconto aplicado às noites com desconto. Se o valor for 50, cada noite selecionada terá 50% de desconto.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @night_selection	1	string	Precisa ser cheapest ou last. Se last, as noites no final do segmento de noites de estadia serão descontadas. Se cheapest, as noites mais baratas dentro do segmento de noites de estadia vão receber desconto.
Promotions / HotelPromotions / Promotion / Discount / FreeNights / @repeats	1	boolean	Se o desconto pode ser aplicado a vários segmentos de noites de estadia. Se false, apenas o segmento de pernoites no início do itinerário vai receber desconto. Se true, qualquer segmento de noites de estadia vai receber desconto. Por exemplo, se stay_nights for 4 e o itinerário for de 10 noites, se repeats for true, dois segmentos serão descontados (noites de 1 a 4 e de 5 a 8). No entanto, se repeats for false, apenas um segmento será descontado (noites de 1 a 4).
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 classificação mais baixa é selecionada para ser aplicada. Os valores precisam estar entre 1 e 99, inclusive. Se várias promoções tiverem a mesma classificação, uma delas será selecionada e aplicada arbitrariamente.
Promotions / HotelPromotions / Promotion / BestDailyDiscount	1	Discount	É preciso especificar exatamente um de Discount ou BestDailyDiscount. Especifica um desconto diário que pode ser aplicado a uma noite de estadia. Isso é diferente de Discount, que aplica descontos a estadias inteiras. Cada propriedade pode ter um único grupo de promoções consideradas "melhores do dia". Isso significa que, para cada noite de estadia, a melhor promoção diária única que se qualifica e oferece o maior desconto para essa noite é selecionada e pode ser aplicada. Stacking pode ser especificado com BestDailyDiscount. Ele precisa ser definido como base ou none. Os descontos "melhor diária" que oferecem o maior desconto para cada noite são combinados e tratados como um único desconto de estadia (ou seja, Discount), respeitando o tipo de combinação configurado. Esse desconto combinado é comparado e pode ser acumulado com outras promoções <Discount> qualificadas para encontrar a opção ou combinação que oferece o maior desconto. A combinação de BestDailyDiscount ou um único Discount, o que resultar no preço mais baixo, é selecionado e aplicado ao tipo de empilhamento base. StayDates pode ser especificado com esse tipo de desconto, mas application precisa ser definido como overlap .
Promotions / HotelPromotions / Promotion / BestDailyDiscount / @percentage	0..1	float	É necessário incluir exatamente um destes campos: percentage, fixed_amount ou fixed_price. Um valor decimal de 0 a 100 que especifica o desconto percentual. Ele é aplicado a AmountAfterTax (ou AmountBeforeTax se AmountAfterTax não for especificado). Exemplos: Se AmountAfterTax para uma noite de estadia for 100 e percentage for 20, então taxa de promoção = AmountAfterTax * (1 - desconto percentual) 80,00 = 100 * (1 - 0,2) Se AmountBeforeTax para uma noite de estadia for 100, percentage for 20 e TaxFeeInfo especificar um tributo de 10, então taxa promocional = AmountBeforeTax * (1 - desconto percentual) + tributos 90,00 = 100 * (1 - 0,2) + 10
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_amount	0..1	float	É necessário incluir exatamente um destes campos: percentage, fixed_amount ou fixed_price. Um valor fixo a ser subtraído de uma única diária de AmountAfterTax (ou de AmountBeforeTax se AmountAfterTax não for especificado). Ela é considerada na mesma moeda das tarifas noturnas. Se esse valor for maior que a soma das tarifas noturnas, o valor resultante será zero. Exemplos: Se AmountBeforeTax para uma única noite for 90, AmountAfterTax for 100 e fixed_amount for 20, então taxa promocional = AmountAfterTax - desconto fixo 80,00 = 100 - 20 Se AmountBeforeTax para uma única noite for 100, fixed_amount for 20 e TaxFeeInfo especificar um tributo de 8%, então taxa promocional = (AmountBeforeTax - desconto fixo) * (1 + tributo percentual) 86,40 = (100 - 20) * 1,08
Promotions / HotelPromotions / Promotion/ BestDailyDiscount / @fixed_price	0..1	float	É necessário incluir exatamente um destes campos: percentage, fixed_amount ou fixed_price. Se as tarifas por noite de AmountAfterTax forem especificadas, isso definirá o preço da noite de estadia, incluindo tributos e taxas, como o valor especificado. Se AmountBeforeTax for especificado, independente de AmountAfterTax ser especificado ou não, isso vai definir o preço sem tributos da estadia como o valor especificado. Ela é considerada na mesma moeda das tarifas noturnas. Exemplos: Se AmountBeforeTax para uma única noite for 90, AmountAfterTax for 100 e fixed_price for 80, a taxa de promoção será 80. Se AmountBeforeTax para uma única noite for 100, fixed_amount for 80 e TaxFeeInfo especificar um tributo de 8%, então taxa promocional = preço fixo * (1 + tributo percentual) 86,40 = 80 * 1,08
Promotions / HotelPromotions / Promotion / InventoryCount	0..1	InventoryCount	Define restrições no número de quartos que precisam estar disponíveis para que a promoção seja aplicada. O desconto é aplicado apenas às noites que atendem à restrição. Não é permitido com o desconto 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 não for especificado, não haverá valor 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 à tarifa por noite. Se não for especificado, não haverá valor máximo.
Promotions / HotelPromotions / Promotion / LengthOfStay	0..1	LengthOfStay	Define os limites de duração da estadia em que 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 não for especificado, não haverá 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 não for especificado, não haverá valor máximo.
Promotions / HotelPromotions / Promotion / MembershipRateRule	0..1	MembershipRateRule	Contêiner para uma regra de tarifa de assinatura que aciona um tratamento específico da interface para o desconto associado. Esse elemento não deve ser especificado, a menos que <Discount> também seja especificado.
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 tarifas diárias dos quartos (usando o maior valor de AmountBeforeTax ou AmountAfterTax) que precisa ser excedida 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 para as ocupações em que esta promoção é aplicada. A promoção não é aplicada quando a ocupação está fora dos limites mínimos e máximos. As promoções se aplicam à tarifa do itinerário. Não é possível definir um desconto máximo por ocupante.
Promotions / HotelPromotions / Promotion / Occupancy / @min	0..1	integer	A ocupação especificada pelo usuário precisa ser pelo menos esse 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 para uma lista de planos de taxas a que a promoção se aplica. Se <RatePlans> não for especificado, a promoção será aplicada a todos os planos de taxas.
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan	1..n	RatePlan	Especifica um plano de taxa. Um plano de tarifas é definido por uma combinação de pacote, tarifas e disponibilidade, conforme definido nas mensagens Transaction (Property Data), OTA_HotelRateAmountNotifRQ e OTA_HotelAvailNotifRQ, e identificado pelo PackageID.
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id	1	string	O identificador exclusivo do plano de tarifas. Esse valor é mapeado para o valor 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 permitidos é 50.
Promotions / HotelPromotions / Promotion / RoomTypes	0..1	RoomTypes	Contêiner para 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 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 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 permitidos é 50.
Promotions / HotelPromotions / Promotion / Stacking	0..1	Stacking	Especifica como as promoções podem ser combinadas. Se não for especificado, o "type" será considerado base.
Promotions / HotelPromotions / Promotion / Stacking / @type	1	enum	Várias promoções podem ser aplicadas a uma única tarifa, dependendo desta configuração: any: pode ser combinado com qualquer outra promoção (exceto none), mas não há garantia da ordem em que as promoções serão aplicadas. base: a melhor promoção base qualificada é selecionada e aplicada primeiro, antes de outras promoções. Antes, esse recurso era chamado de base_only. second: a melhor promoção second qualificada é selecionada e aplicada após uma promoção base (se aplicável) e antes das promoções any. none: Não pode ser combinado com outras promoções. 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, como para acomodar descontos sazonais.
Promotions / HotelPromotions / Promotion / StayDates / @application	1	enum	Descreve como a promoção deve ser aplicada. Os valores válidos são: all: aplica a promoção a cada noite do itinerário se todas as datas do itinerário coincidirem com as datas da estadia. any: aplica a promoção a todas as noites do roteiro se alguma data do roteiro se sobrepuser a uma data no período da estadia. overlap: aplica a promoção somente às noites do itinerário que se sobrepõem a uma data no período da estadia. Esse atributo precisa ser sempre especificado. Se <Discount> especificar percentage e application for definido como all ou any, o desconto será aplicado como uma porcentagem da estadia completa. Se <Discount> especificar percentage e application estiver definido como overlap, o desconto será aplicado como uma porcentagem das diárias para noites sobrepostas. <Discount> especificando fixed_amount e application definido como overlap é uma combinação inválida. <FreeNights> aceita todos os valores de application. Para overlap, apenas as noites de estadia que se sobrepõem são consideradas para os requisitos de desconto.
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 é compatível. Se um dos campos start ou end for uma data sem ano, os dois precisarão ser preenchidos como datas sem ano. Os períodos sem ano não podem envolver o ano-novo. Em vez disso, represente o intervalo como dois períodos adjacentes. Por exemplo, {"12-29", "01-05"} pode ser representado como {"12-29", "12-31"} e {"01-01", "01-05"}. Se você quiser definir o intervalo StayDates para permitir a promoção em dias específicos da semana, defina a data start como a data atual sem end para que a promoção não expire.
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á ilimitado em termos de data de início. Especifique o valor start se o valor end não for fornecido.
Promotions / HotelPromotions / Promotion / StayDates / DateRange / @end	0..1	Date or YearlessDate	A data de término (com base no fuso horário da propriedade), inclusive, do período. Essa data precisa ser igual ou posterior à data de start. Se end não for especificado, o período será ilimitado a partir da data start. Especifique o valor end se o valor start não for fornecido.
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 na 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: M para segunda-feira T para terça-feira W para quarta-feira H para quinta-feira F para sexta-feira S para sábado U para domingo Qualquer combinação de caracteres é válida.
Promotions / HotelPromotions / Promotion / UserCountries	0..1	UserCountries	Contêiner para listar os locais (países) dos usuários que se qualificam para a promoção. Se especificado, somente os usuários qualificados nos países listados vão receber a taxa com desconto. Se não for especificado, a taxa com desconto será oferecida aos usuários qualificados em qualquer país.
Promotions / HotelPromotions / Promotion / UserCountries / @type	0..1	enum	O tipo de especificação UserCountries. Os valores válidos são include e exclude. Se o UserCountries type estiver definido como include, a promoção será válida para usuários dos países listados. Se o UserCountries type for exclude, a promoção será válida para usuários de fora dos países listados. Se o UserCountries type não estiver definido, ele será tratado como include, e a promoção será aplicada aos usuários dos países listados.
Promotions / HotelPromotions / Promotion / UserCountries / Country	1..300	Country	Define um país em que os usuários se qualificam para a promoção.
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code	1	string	Um código de país CLDR, como DE ou FR. Em alguns países, o código CLDR não é o mesmo que o código ISO de duas letras. Além disso, os códigos de região CLDR não são aceitos.

Exemplos

Há um limite de 500 promoções por propriedade. Consulte o exemplo "Excluir uma promoção" para remover promoções de uma propriedade.

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 do inventário

O exemplo a seguir mostra como criar um desconto se houver excesso de inventário 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> para uma propriedade com uma ou mais novas promoções. 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). Observe que a promoção none não seria aplicada porque as outras oferecem um desconto melhor. Se o preço original fosse de R $100, o valor com desconto seria de R $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 era de US $100, o preço com desconto seria de US $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 de início e fim definidos como um tipo de duração ISO 8601. Essa restrição de janela de reserva exige que a reserva seja feita até as 18h do dia anterior à chegada e a partir das 12h do segundo 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 de reserva

O exemplo a seguir mostra um caso em que o elemento BookingDates é usado com atributos start e end como tipos DateTime. Essa restrição de data de reserva exige que a reserva seja feita entre 06:30 de 01/07/2020 e 18:45 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 com campos start e end sem anos. Neste exemplo, a promoção é válida para datas de check-in entre 29/12 e 2/1, independentemente do ano. Intervalos de datas sem ano que cruzam o limite do ano novo são inválidos. Portanto, o DateRange é expresso como dois intervalos de datas 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 FreeNights

O exemplo a seguir oferece um desconto de 50% em duas diárias a cada quatro diárias reservadas no período especificado. 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 oferece um desconto de 50% em uma noite a cada três noites de estadia nos intervalos de datas especificados. Apenas as noites de estadia que se sobrepõem contam para a qualificação do desconto. Para o itinerário a seguir, com check-in em 2022-01-01 e check-out em 2022-01-07, as diárias qualificadas e os descontos são aplicados da seguinte forma.

• 2022-01-01 (estadia)
• 2022-01-02 (estadia)
• 2022-01-03
• 2022-01-04 (com desconto)
• 2022-01-05 (estadia)
• 2022-01-06 (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 menor.

<?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

O exemplo a seguir oferece um desconto em uma estadia de duas noites aplicando BestDailyDiscount combinado 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 o cálculo, primeiro encontramos a combinação dos melhores descontos diários que gera o maior desconto.

Na primeira noite, a promoção "geral" é o único valor qualificado com um desconto fixo de 20.

Na segunda noite, a promoção "maio" oferece um desconto maior do que o desconto "geral". Portanto, quando "may" é selecionado, o valor do desconto fixo é 50.

Depois, para a estadia, a promoção "fiesta" dá um desconto de 5 por noite, ou 10 no total. Ele pode ser combinado com a combinação dos melhores descontos diários porque "fiesta" tem o tipo de combinação definido como any. Se ele fosse definido como base, apenas a combinação dos melhores descontos diários ou o desconto "fiesta" seria aplicado. Consulte 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 desta mensagem.
PromotionsResponse / @id	1	string	O identificador exclusivo da mensagem de promoções associada.
PromotionsResponse / @partner	1	string	A conta de parceiro desta mensagem.
PromotionsResponse / Success	0..1	Success	Indica que a mensagem de promoções foi processada sem alertas, erros ou falhas. <Success> ou <Issues> está presente em cada mensagem.
PromotionsResponse / Issues	0..1	Issues	Um contêiner para um ou mais problemas encontrados ao processar a mensagem de promoções. <Success> ou <Issues> está presente em cada mensagem.
PromotionsResponse / Issues / Issue	1..n	Issue	A descrição de um aviso, erro ou falha encontrada ao processar a mensagem de promoções. Confira os detalhes desses problemas em Mensagens de erro do 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 warning, error e failure.

Exemplos

Sucesso

Confira a seguir uma resposta a uma mensagem de promoções processada com sucesso.

<?xml version="1.0" encoding="UTF-8"?>
<PromotionsResponse timestamp="2020-05-18T16:20:00-04:00"
                    id="12345678"
                    partner="partner_key">
  <Success/>
</PromotionsResponse>

Problemas

A seguir, há uma resposta a uma mensagem de promoções que não foi 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>