Les tarifs envoyés via <OTA_HotelRateAmountNotifRQ> peuvent être modifiés pour tenir compte des adultes et des enfants en plus du nombre de personnes initialement prévu. Le message ExtraGuestCharges permet de spécifier comment les tarifs doivent être calculés pour ces clients supplémentaires, et pour quelles chambres, quels plans tarifaires et quelles dates de séjour leurs frais doivent s'appliquer.
Exigences de capacité
Les prix calculés à partir du message ExtraGuestCharges ne sont valides que si toutes les exigences de capacité sont respectées. Pour en savoir plus, consultez Transaction (données sur un établissement).
Requêtes
Syntaxe
Le message ExtraGuestCharges utilise la syntaxe suivante :
<?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>
Éléments et attributs
Le message ExtraGuestCharges inclut les éléments et les attributs suivants :
| Élément / @Attribut | Occurrences | Type | Description |
|---|---|---|---|
| ExtraGuestCharges | 1 | Complex element | Élément racine de ce message. |
| ExtraGuestCharges / @partner | 1 | string | Compte partenaire pour ce message. Cette valeur de chaîne correspond à la valeur Partner key indiquée sur la page
Paramètres du compte dans Hotel Center.
Remarque : Si vous avez un backend qui fournit des flux pour plusieurs comptes, cette valeur doit correspondre à la valeur de l'attribut |
| ExtraGuestCharges / @id | 1 | string | Identifiant unique pour ce message de demande. Cette valeur est renvoyée dans le message de réponse. Les caractères autorisés sont a-z, A-Z, 0-9, _ (trait de soulignement) et - (tiret). |
| ExtraGuestCharges / @timestamp | 1 | DateTime | Date et heure de création de ce message. |
| ExtraGuestCharges / HotelExtraGuestCharges | 0..n | HotelExtraGuestCharges | Conteneur pour les frais d'un même établissement. |
| ExtraGuestCharges / HotelExtraGuestCharges / @hotel_id | 1 | string | Identifiant unique de l'établissement. Cette valeur doit correspondre à l'identifiant de l'hôtel spécifié à l'aide de
<id> dans l'élément <listing> du flux Hotel List Feed. L'ID de l'hôtel est également indiqué dans Hotel Center. |
| ExtraGuestCharges / HotelExtraGuestCharges / @action | 0..1 | enum | Spécifie comment la mise à jour est appliquée. Seule la valeur overlay est acceptée. La valeur par défaut est "overlay" (superposition). Tous les frais précédents pour cette propriété sont supprimés avant l'application de la mise à jour. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge | 0..99 | ExtraGuestCharge | Ensemble unique de frais pour un établissement. Il peut contenir des restrictions sur la façon dont un supplément peut être appliqué et sur la façon dont les suppléments sont calculés par âge ou par catégorie d'invité. Chaque |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets | 1 | AgeBrackets | Conteneur de tranches d'âge permettant de calculer les frais par âge ou par catégorie d'invité. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / AdultCharge | 0..1 | AdultCharge | Conteneur pour les frais liés à un adulte supplémentaire. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / AdultCharge / @amount | 0..1 | float | Valeur décimale positive indiquant le montant forfaitaire à facturer pour un adulte supplémentaire. Ces frais sont facturés dans la même devise que celle spécifiée pour les tarifs par nuit. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets | 0..1 | ChildAgeBrackets | Conteneur pour les frais supplémentaires liés aux enfants. Ces tranches d'âge ne peuvent couvrir que la tranche d'âge de 0 à 17 ans inclus. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket | 1..99 | ChildAgeBracket | Frais qui s'appliquent aux enfants d'une tranche d'âge spécifique. Elles doivent être classées de la valeur max_age la plus basse à la valeur max_age la plus élevée. Le montant à facturer peut être spécifié à l'aide de amount, percentage ou discount_amount. Un seul de ces attributs doit être spécifié pour chaque <ChildAgeBracket>.
|
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @max_age | 1 | integer | Âge maximal auquel les frais spécifiés dans <ChildAgeBracket> peuvent s'appliquer. L'âge minimal est de zéro si aucun autre <ChildAgeBracket> n'est spécifié avant celui-ci. Sinon, il s'agit de l'âge maximal de la tranche précédente plus un. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @exclude_from_capacity | 1 | boolean | Valeur booléenne indiquant si un enfant de cette tranche d'âge doit être comptabilisé dans la capacité totale et la capacité pour les enfants d'une chambre. Ces capacités peuvent être définies avec Transaction(Données sur un établissement). Par exemple, les bébés de moins d'un certain âge ne sont pas forcément pris en compte dans la capacité d'accueil des enfants. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @amount | 0..1 | float | Valeur décimale non négative qui spécifie le montant forfaitaire à facturer pour un enfant supplémentaire dans cette tranche. Ces frais sont facturés dans la même devise que celle spécifiée pour les tarifs par nuit. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @percentage | 0..1 | float | Valeur décimale comprise entre 1 et 99 indiquant le pourcentage du prix adulte à facturer pour un enfant supplémentaire dans cette tranche. Ces frais sont facturés dans la même devise que celle spécifiée pour les tarifs par nuit. Pour en savoir plus sur le calcul du prix pour adultes, consultez la discussion sous |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @discount_amount | 0..1 | float | Valeur décimale positive indiquant le montant de la remise forfaitaire sur le prix adulte pour un enfant supplémentaire dans cette tranche d'âge. Ces frais sont facturés dans la même devise que celle spécifiée pour les tarifs par nuit. En général, les frais pour un enfant de cette tranche d'âge sont calculés en déduisant le montant forfaitaire du "prix unitaire". Le prix unitaire est abordé plus en détail dans la section sur l'attribut |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @counts_as_base_occupant | 0..1 | string | Si l'attribut L'objectif est d'obtenir un "prix unitaire" à partir duquel le montant réel peut être calculé.
La valeur de cet attribut doit être
|
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes | 0..1 | RoomTypes | Conteneur pour la liste des types de chambres auxquels les frais s'appliquent.
Les frais sont appliqués à chaque <RoomType> spécifié. Si <RoomTypes> n'est pas spécifié, les frais s'appliquent à toutes les chambres de l'établissement spécifié. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes / RoomType | 1..n | RoomType | Spécifie un type de chambre. Un type de chambre est défini dans un élément <RoomData> d'un message Transaction (Données sur un établissement) et est référencé à l'aide de sa valeur <RoomID>. (Sa valeur <RoomID> est également référencée par l'attribut InvTypeCode dans les messages OTA_HotelRateAmountNotifRQ.) |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes / RoomType / @id | 1 | string | Identifiant unique de l'inventaire (type de chambre). Cette valeur correspond à <RoomID> dans un message Transaction (Données sur un établissement).
Le nombre maximal de caractères autorisés est de 50. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans | 0..1 | RatePlans | Conteneur pour la liste des plans tarifaires auxquels les frais s'appliquent.
Si <RatePlans> n'est pas spécifié, les frais s'appliquent à tous les plans tarifaires. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans / RatePlan | 1..n | RatePlan | Spécifie un plan tarifaire. Un plan tarifaire est défini par la combinaison d'une formule, de tarifs et d'une disponibilité, telle que définie dans les messages Transaction (Données sur un établissement), OTA_HotelRateAmountNotifRQ et OTA_HotelAvailNotifRQ, et telle qu'identifiée par la valeur PackageID. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans / RatePlan / @id | 1 | string | Identifiant unique du plan tarifaire. Cette valeur correspond à la valeur PackageID dans l'élément <PackageData> d'un message Transaction (Données sur un établissement), ainsi que dans l'attribut RatePlanCode de l'élément <StatusApplicationControl> dans les messages <OTA_HotelRateAmountNotifRQ> et <OTA_HotelAvailNotifRQ>.
Le nombre maximal de caractères autorisés est de 50. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates | 0..1 | StayDates | Conteneur pour une ou plusieurs plages de dates qui déterminent comment les frais sont appliqués. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange | 1..99 | DateRange | Plage de dates indiquant les dates auxquelles la promotion doit être appliquée. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @start | 0..1 | Date | Date de début (en fonction du fuseau horaire de l'établissement), incluse, de la plage de dates. Cette date doit être antérieure ou identique à la date end. Si start n'est pas spécifié, la plage de dates est en fait illimitée en ce qui concerne la date de début. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @end | 0..1 | Date | Date de fin (en fonction du fuseau horaire de l'établissement), incluse, de la plage de dates. Cette date doit être identique ou postérieure à la date start. Si end n'est pas spécifié, la plage de dates est en fait illimitée en ce qui concerne la date de fin. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @days_of_week | 0..1 | string | Jours de la semaine autorisés dans la plage de dates. Si cet attribut n'est pas spécifié, tous les jours sont autorisés dans la plage de dates. Chaque caractère de la chaîne spécifie un jour. Par exemple, "MTWHF" indique que les jours de la semaine sont autorisés dans la plage de dates. Les caractères valides sont les suivants :
Toute combinaison de caractères est valide. |
Exemples
Frais pour adultes
Les frais pour les adultes supplémentaires ne peuvent être exprimés que sous forme de montants fixes. L'exemple suivant montre un message ExtraGuestCharges qui spécifie les frais pour adultes :
<?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>
Voici les taux correspondants :
<?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>
Lorsqu'un utilisateur recherche un tarif pour quatre adultes sur Google, le tarif total est de 170 € (120 € + 50 €).
120 provient du taux <BaseByGuestAmt> avec NumberOfGuests="3" et 50 provient de AdultCharge amount="50".
Frais pour les enfants
Les frais pour les enfants sont exprimés par tranches d'âge jusqu'à 17 ans et peuvent être exprimés en montants fixes, en pourcentages ou en remises.
L'exemple suivant montre un message ExtraGuestCharges qui spécifie les frais pour enfants :
<?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>
Voici les taux correspondants :
<?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
Restrictions de facturation
Tous les types de restrictions sont facultatifs et peuvent être combinés.
L'exemple suivant montre un message ExtraGuestCharges qui spécifie des restrictions :
<?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>
Le message ci-dessus précise que les adultes doivent payer pour tout produit dont le type de chambre est "queen" ou "king" avec le forfait "free-wifi" ou "hot-breakfast" pour les dates du 1er septembre 2020 au 14 septembre 2020.
Frais qui se chevauchent
Cette section présente un exemple de message non valide qui spécifie des frais différents pour les mêmes combinaisons de dates et de produits.
<?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>
Le message ci-dessus n'est pas valide, car le premier <ExtraGuestCharge> indique que les adultes supplémentaires doivent payer 50 € pour les séjours du 1er au 14 septembre avec les mots clés "queen" et "free-wifi". Le deuxième <ExtraGuestCharge> spécifie que pour toute chambre "queen" ou "king" avec "free-wifi" ou "hot-breakfast" du 1er au 5 septembre, les adultes supplémentaires doivent payer 20.
Des frais se chevauchent pour les services "queen" et "free-wifi" du 1er au 5 septembre, et il existe un conflit entre les frais de 20 € et 50 € pour un adulte supplémentaire.
Réponses
Syntaxe
Le message ExtraGuestChargesResponse utilise la syntaxe suivante :
<?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>
Éléments et attributs
Le message ExtraGuestChargesResponse inclut les éléments et les attributs suivants :
| Élément / @Attribut | Occurrences | Type | Description |
|---|---|---|---|
| ExtraGuestChargesResponse | 1 | Complex element | Élément racine indiquant le succès ou les problèmes liés à un message de requête ExtraGuestCharges reçu. |
| ExtraGuestChargesResponse / @timestamp | 1 | DateTime | Date et heure de création de ce message. |
| ExtraGuestChargesResponse / @id | 1 | string | Identifiant unique du message ExtraGuestCharges associé. |
| ExtraGuestChargesResponse / @partner | 1 | string | Compte partenaire pour ce message. |
| ExtraGuestChargesResponse / Success | 0..1 | Success | Indique que le message ExtraGuestCharges a été traité avec succès, sans avertissement, erreur ni échec.
Chaque message contient soit |
| ExtraGuestChargesResponse / Issues | 0..1 | Issues | Conteneur pour un ou plusieurs problèmes rencontrés lors du traitement du message ExtraGuestCharges.
Chaque message contient soit |
| ExtraGuestChargesResponse / Issues / Issue | 1..n | Issue | Description d'un avertissement, d'une erreur ou d'un échec survenu lors du traitement du message ExtraGuestCharges. Pour en savoir plus sur ces problèmes, consultez Messages d'erreur concernant l'état du flux. |
| ExtraGuestChargesResponse / Issues / Issue / @code | 1 | integer | Identifiant du problème. |
| ExtraGuestChargesResponse / Issues / Issue / @status | 1 | enum | Type de problème rencontré. Les valeurs valides sont |
Exemples
Opération réussie
Voici une réponse à un message ExtraGuestCharges traité avec succès :
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestChargesResponse timestamp="2020-05-18T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Success/>
</ExtraGuestChargesResponse>
Problèmes
La réponse ci-dessous est une réponse à un message ExtraGuestCharges non traité en raison d'erreurs.
<?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>