As tarifas enviadas pelo <OTA_HotelRateAmountNotifRQ> podem ser modificadas para incluir adultos e crianças, além do número original de hóspedes. A mensagem ExtraGuestCharges permite especificar como as tarifas precisam ser calculadas para esses hóspedes adicionais e a quais quartos, planos de tarifas e datas de estadia as cobranças serão aplicadas.
Requisitos de capacidade
Os preços calculados da mensagem ExtraGuestCharges só serão válidos se todos
os requisitos de capacidade forem atendidos. Consulte Transação (dados da propriedade) para mais informações.
Solicitações
Sintaxe
A mensagem ExtraGuestCharges usa a seguinte sintaxe:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges partner="partner_account_name"
id="message_ID"
timestamp="timestamp">
<HotelExtraGuestCharges hotel_id="HotelID" action="[overlay]">
<ExtraGuestCharge>
<RatePlans>
<RatePlan id="PackageID_1"/>
<RatePlan id="PackageID_2"/>
</RatePlans>
<RoomTypes>
<RoomType id="RoomID_1"/>
<RoomType id="RoomID_2"/>
</RoomTypes>
<StayDates>
<DateRange start="YYYY-MM-DD" end="YYYY-MM-DD"
days_of_week="MTWHFSU_or_subset"/>
</StayDates>
<AgeBrackets>
<AdultCharge amount="float"/>
<ChildAgeBrackets>
<!-- The following are different ways child charges can be specified.
Use the option that matches your system. -->
<ChildAgeBracket max_age="integer" amount="float"
exclude_from_capacity="[true|false]"/>
<ChildAgeBracket max_age="integer" percentage="float"
exclude_from_capacity="[true|false]"
counts_as_base_occupant="[never|preferred|always]"/>
<ChildAgeBracket max_age="integer" discount_amount="float"
exclude_from_capacity="[true|false]"
counts_as_base_occupant="[never|preferred|always]"/>
</ChildAgeBrackets>
</AgeBrackets>
</ExtraGuestCharge>
</HotelExtraGuestCharges>
</ExtraGuestCharges>
Elementos e atributos
A mensagem ExtraGuestCharges tem os seguintes elementos e
atributos:
| Elemento / @Attribute | Ocorrências | Tipo | Descrição |
|---|---|---|---|
| ExtraGuestCharges | 1 | Complex element | O elemento raiz da mensagem. |
| ExtraGuestCharges / @partner | 1 | string | A conta do parceiro para esta mensagem. O valor da string é o valor Partner key listado na
página de configurações da conta na Central para Hotéis.
Observação:se você tem um back-end que fornece feeds para
várias contas, esse valor precisa corresponder ao valor do atributo |
| ExtraGuestCharges / @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
- (traço). |
| ExtraGuestCharges / @timestamp | 1 | DateTime | A data e a hora de criação da mensagem. |
| ExtraGuestCharges / HotelExtraGuestCharges | 0..n | HotelExtraGuestCharges | Contêiner para cobranças de uma única propriedade. |
| ExtraGuestCharges / HotelExtraGuestCharges / @hotel_id | 1 | string | O identificador exclusivo da propriedade. Esse valor precisa corresponder ao ID de hotel especificado com
<id> no elemento <listing> no feed de lista de hotéis. O ID do hotel também aparece na Central para Hotéis. |
| ExtraGuestCharges / HotelExtraGuestCharges / @action | 0..1 | enum | Especifica como a atualização é aplicada. Apenas overlay é aceito, e o padrão é sobreposição. As cobranças anteriores dessa propriedade serão apagadas antes que a atualização seja aplicada. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge | 0..99 | ExtraGuestCharge | Um único conjunto de cobranças para uma propriedade. Isso pode conter restrições sobre como uma cobrança pode ser aplicada e como as cobranças são calculadas por idade ou categoria do hóspede. Cada |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets | 1 | AgeBrackets | Um contêiner de faixas etárias para calcular cobranças por idade ou categoria de hóspedes. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / AdultCharge | 0..1 | AdultCharge | Recipiente para a cobrança de um adulto adicional. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / AdultCharge / @amount | 0..1 | float | Um valor decimal positivo que especifica o valor fixo a ser cobrado por mais um adulto. Essa cobrança usa a mesma moeda que a especificada para as tarifas noturnas. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets | 0..1 | ChildAgeBrackets | Contêiner com cobranças adicionais para filhos. Essas faixas etárias podem abranger apenas a faixa etária de 0 a 17 anos. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket | 1..99 | ChildAgeBracket | Uma cobrança que se aplica a crianças de uma faixa etária específica. Eles
devem ser ordenados do max_age mais baixo para o
max_age mais alto. O valor a ser cobrado pode ser especificado usando amount, percentage ou discount_amount. Exatamente um desses atributos precisa ser
especificado para cada <ChildAgeBracket>.
|
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @max_age | 1 | integer | A idade máxima a que as cobranças especificadas em
<ChildAgeBracket> podem ser aplicadas. A idade mínima será zero
se não houver outro <ChildAgeBracket> especificado
antes desse. Caso contrário, é um maior que a idade máxima da faixa anterior. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @exclude_from_capacity | 1 | boolean | Um booleano que indica se uma criança nessa faixa etária é considerada na capacidade total e infantil de um quarto. Essas capacidades podem ser definidas com Transação(dados da propriedade). Por exemplo, crianças abaixo de uma determinada idade podem não precisar ser contabilizadas na capacidade das crianças. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @amount | 0..1 | float | Um valor decimal não negativo que especifica o valor fixo a ser cobrado por um filho adicional neste colchete. Essa cobrança usa a mesma moeda que a especificada para as tarifas noturnas. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @percentage | 0..1 | float | Um valor decimal de 1 a 99 que especifica a porcentagem de um preço para adultos que deve ser cobrada por um filho adicional nesta faixa. Essa cobrança usa a mesma moeda que a especificada para as tarifas por noite. Consulte a discussão em |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @discount_amount | 0..1 | float | Um valor decimal positivo que especifica um valor de desconto fixo sobre o preço adulto para um filho adicional nesta faixa. Essa cobrança usa a mesma moeda que a especificada para as tarifas noturnas. Em geral, a cobrança para uma criança nessa faixa é calculada
deduzindo o valor fixo do "preço unitário". O preço unitário é
discutido em mais detalhes na seção de atributos
|
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @counts_as_base_occupant | 0..1 | string | Se o atributo O objetivo é conseguir um "preço unitário" a partir do qual a cobrança real possa ser calculada.
O valor desse atributo precisa ser
|
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes | 0..1 | RoomTypes | Contêiner para uma lista de tipos de quarto aos quais as cobranças se aplicam.
As cobranças são aplicadas a cada <RoomType>
especificado. Se <RoomTypes> não for especificado, as cobranças serão aplicadas a todos os quartos dentro da propriedade especificada. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / 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. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / 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. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans | 0..1 | RatePlans | Contêiner para uma lista de planos de tarifas aos quais as cobranças se aplicam.
Se <RatePlans> não for especificado, as cobranças
serão aplicadas a todos os planos de tarifas. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans / RatePlan | 1..n | RatePlan | Especifica um plano de tarifação. Um plano de tarifas é definido por uma combinação de pacotes, taxas e disponibilidade, conforme definido nas mensagens de transação (dados de propriedade), OTA_HotelRateAmountNotifRQ e OTA_HotelAvailNotifRQ, conforme identificado pelo PackageID. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / 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. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates | 0..1 | StayDates | Um contêiner para um ou mais períodos que determinam como as cobranças são aplicadas. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange | 1..99 | DateRange | Um período que especifica as datas em que a promoção será aplicada. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @start | 0..1 | Date | A data de início (com base no fuso horário da propriedade), inclusive, do período. Essa data precisa ser igual ou anterior à
data de end. Se start não for especificado, o período será efetivamente ilimitado em termos de data de início. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @end | 0..1 | Date | 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 start. Se end não for especificado, o período será efetivamente ilimitado em termos de data de término. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / 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 dias da semana são permitidos no período. Os caracteres válidos são:
Qualquer combinação de caracteres é válida. |
Exemplos
Cobranças para adultos
Os custos para adultos adicionais só podem ser expressos em valores fixos. No exemplo a seguir, mostramos uma mensagem ExtraGuestCharges que especifica cobranças de adultos:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
<HotelExtraGuestCharges hotel_id="ABC" action="overlay">
<ExtraGuestCharge>
<StayDates />
<AgeBrackets>
<AdultCharge amount="50" />
</AgeBrackets>
</ExtraGuestCharge>
</HotelExtraGuestCharges>
</ExtraGuestCharges>
Estas são as taxas correspondentes:
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="12345678"
TimeStamp="2020-05-19T20:50:37-05:00"
Version="3.0">
<RateAmountMessages HotelCode="ABC">
<RateAmountMessage>
<StatusApplicationControl Start="2020-05-18"
End="2020-05-23"
InvTypeCode="RoomID_1"
RatePlanCode="PackageID_1"/>
<Rates>
<Rate>
<BaseByGuestAmts>
<BaseByGuestAmt AmountAfterTax="100.00"
CurrencyCode="USD"
NumberOfGuests="1"/>
<BaseByGuestAmt AmountAfterTax="110.00"
CurrencyCode="USD"
NumberOfGuests="2"/>
<BaseByGuestAmt AmountAfterTax="120.00"
CurrencyCode="USD"
NumberOfGuests="3"/>
</BaseByGuestAmts>
</Rate>
</Rates>
</RateAmountMessage>
</RateAmountMessages>
</OTA_HotelRateAmountNotifRQ>
Quando um usuário pesquisar quatro adultos no Google, a taxa total será 170 = 120 + 50.
120 vem da taxa <BaseByGuestAmt> com NumberOfGuests="3" e 50
vem do AdultCharge amount="50".
Cobranças para crianças
As cobranças para crianças são expressas em faixas etárias de até 17 anos e podem ser expressas em valores fixos, porcentagens ou descontos.
O exemplo a seguir mostra uma mensagem ExtraGuestCharges que especifica
cobranças filhas:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
<HotelExtraGuestCharges hotel_id="ABC" action="overlay">
<ExtraGuestCharge>
<AgeBrackets>
<ChildAgeBrackets>
<ChildAgeBracket max_age="3" percentage="10"
counts_as_base_occupant="never" />
<ChildAgeBracket max_age="10" percentage="30"
counts_as_base_occupant="preferred"/>
<ChildAgeBracket max_age="17" discount_amount="10"
counts_as_base_occupant="always" />
</ChildAgeBrackets>
</AgeBrackets>
</ExtraGuestCharge>
</HotelExtraGuestCharges>
</ExtraGuestCharges>
Estas são as taxas correspondentes:
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="12345678"
TimeStamp="2020-05-19T20:50:37-05:00"
Version="3.0">
<RateAmountMessages HotelCode="ABC">
<RateAmountMessage>
<StatusApplicationControl Start="2020-05-18"
End="2020-05-23"
InvTypeCode="RoomID_1"
RatePlanCode="PackageID_1"/>
<Rates>
<Rate>
<BaseByGuestAmts>
<BaseByGuestAmt AmountAfterTax="100.00"
CurrencyCode="USD"
NumberOfGuests="1"/>
<BaseByGuestAmt AmountAfterTax="110.00"
CurrencyCode="USD"
NumberOfGuests="2"/>
</BaseByGuestAmts>
</Rate>
</Rates>
</RateAmountMessage>
</RateAmountMessages>
</OTA_HotelRateAmountNotifRQ>
```
1. Suppose you want the total price for 2 adults and 1 child of 2 years
of age.
Children aged 0-3 are never included in the rate's occupancy,
so here you should take the double occupancy rate and divide by 2 to
get the unit price. Then, multiply by the percentage rate and sum
with the rate to get the total price.
`unit price ` = 110 / 2 = 55
`total price` = 110 + 55 * 0.1 = 115.5
1. Suppose you want the total price for 1 adult and 2 children, both of 5
years of age.
Children aged 4-10 are preferably included in the rate's
occupancy. you should start by looking for a 3 adult rate since both
children are preferably included in the rate's occupancy. Since
that doesn't exist you should fall back to the 2 adult rate and then,
take this rate and divide by two to get the unit price. Finally,
multiply by the percentage rate and sum with the scaled rate to
get the total price.
`unit price` = 110 / 2 = 55
`total price` = 55 + 55 * 0.3 + 55 * 0.3 = 88
1. Suppose you want the total price for 1 adult and 1 child of 17
years of age.
Children aged 11-17 are always included in the rate's occupancy, so,
in this case, take the double occupancy rate and divide by 2 to get
the unit price. Then, deduct it by the discount amount and sum with
the scaled rate to get the total price.
`unit price` = 110 / 2 = 55
`total price` = 55 + (55 - 10) = 100
Restrições de cobrança
Todos os tipos de restrições são opcionais, e qualquer combinação deles pode ser usada.
O exemplo a seguir mostra uma mensagem ExtraGuestCharges que especifica
restrições:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
<HotelExtraGuestCharges hotel_id="ABC" action="overlay">
<ExtraGuestCharge>
<RoomTypes>
<RoomType id="queen" />
<RoomType id="king" />
</RoomTypes>
<RatePlans>
<RatePlan id="free-wifi" />
<RatePlan id="hot-breakfast" />
</RatePlans>
<StayDates>
<DateRange start="2020-09-01" end="2020-09-14"/>
</StayDates>
<AgeBrackets>
<AdultCharge amount="50" />
</AgeBrackets>
</ExtraGuestCharge>
</HotelExtraGuestCharges>
</ExtraGuestCharges>
A mensagem acima especifica que os adultos vão ser cobrados por qualquer produto que tenha o tipo de quarto "queen" ou "king" com o plano de tarifa "Wi-Fi gratuito" ou "café com pratos quentes" entre 1o e 14 de setembro de 2020.
Cobranças conflitantes
Nesta seção, mostramos um exemplo de uma mensagem inválida que especifica cobranças diferentes para as mesmas combinações de datas e produtos.
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
<HotelExtraGuestCharges hotel_id="ABC" action="overlay">
<ExtraGuestCharge>
<RoomTypes>
<RoomType id="queen" />
</RoomTypes>
<RatePlans>
<RatePlan id="free-wifi" />
</RatePlans>
<StayDates>
<DateRange start="2020-09-01" end="2020-09-14"/>
</StayDates>
<AgeBrackets>
<AdultCharge amount="50" />
</AgeBrackets>
</ExtraGuestCharge>
<ExtraGuestCharge>
<RoomTypes>
<RoomType id="queen" />
<RoomType id="king" />
</RoomTypes>
<RatePlans>
<RatePlan id="free-wifi" />
<RatePlan id="hot-breakfast" />
</RatePlans>
<StayDates>
<DateRange start="2020-09-01" end="2020-09-05"/>
</StayDates>
<AgeBrackets>
<AdultCharge amount="20" />
</AgeBrackets>
</ExtraGuestCharge>
</HotelExtraGuestCharges>
</ExtraGuestCharges>
A mensagem acima é inválida porque a primeira <ExtraGuestCharge>
especifica que "rainha" e "Wi-Fi gratuito" de 1o a 14 de setembro devem cobrar
50 adultos adicionais. O segundo <ExtraGuestCharge>
especifica que os valores "rainha" ou "rei" com "Wi-Fi gratuito" ou
"café com pratos quentes" para os dias 1o a 5 de setembro precisam cobrar 20 adultos adicionais.
Há cobranças sobrepostas para "queen" e "Wi-Fi gratuito" entre 1o e 5 de setembro, e há um conflito entre cobrar 20 ou 50 por um adulto adicional.
Respostas
Sintaxe
A mensagem ExtraGuestChargesResponse usa a seguinte
sintaxe:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestChargesResponse timestamp="timestamp"
id="message_ID"
partner="partner_key">
<!-- Either Success or Issues will be populated. -->
<Success/>
<Issues>
<Issue code="issue_code" status="issue_type">issue_description</Issue>
</Issues>
</ExtraGuestChargesResponse>
Elementos e atributos
A mensagem ExtraGuestChargesResponse tem os seguintes elementos
e atributos:
| Elemento / @Attribute | Ocorrências | Tipo | Descrição |
|---|---|---|---|
| ExtraGuestChargesResponse | 1 | Complex element | O elemento raiz que indica o sucesso ou os problemas de uma mensagem de solicitação ExtraGuestCharges recebida. |
| ExtraGuestChargesResponse / @timestamp | 1 | DateTime | A data e a hora de criação da mensagem. |
| ExtraGuestChargesResponse / @id | 1 | string | O identificador exclusivo da mensagem ExtraGuestCharges associada. |
| ExtraGuestChargesResponse / @partner | 1 | string | A conta do parceiro para esta mensagem. |
| ExtraGuestChargesResponse / Success | 0..1 | Success | Indica que a mensagem ExtraGuestCharges foi processada com êxito
sem avisos, erros ou falhas.
Cada mensagem tem |
| ExtraGuestChargesResponse / Issues | 0..1 | Issues | Um contêiner para um ou mais problemas encontrados durante o processamento da
mensagem ExtraGuestCharges.
Cada mensagem tem |
| ExtraGuestChargesResponse / Issues / Issue | 1..n | Issue | A descrição de um aviso, erro ou falha encontrada ao
processar a mensagem ExtraGuestCharges. Os detalhes sobre esses problemas podem ser encontrados nas Mensagens de erro de status do feed. |
| ExtraGuestChargesResponse / Issues / Issue / @code | 1 | integer | O identificador do problema. |
| ExtraGuestChargesResponse / Issues / Issue / @status | 1 | enum | O tipo de problema encontrado. Os valores válidos são |
Exemplos
Concluído
Veja a seguir uma resposta a uma mensagem ExtraGuestCharges processada com sucesso.
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestChargesResponse timestamp="2020-05-18T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Success/>
</ExtraGuestChargesResponse>
Problemas
Veja a seguir uma resposta a uma mensagem ExtraGuestCharges não processada devido a erros.
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestChargesResponse timestamp="2020-05-18T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Issues>
<Issue code="1001" status="error">Example</Issue>
</Issues>
</ExtraGuestChargesResponse>