Тарифы, отправленные через <OTA_HotelRateAmountNotifRQ> , могут быть изменены с учетом взрослых и детей в дополнение к первоначальному количеству гостей. Сообщение ExtraGuestCharges позволяет указать, как следует рассчитывать тарифы для этих дополнительных гостей, а также для каких номеров, тарифных планов и дат проживания должны применяться соответствующие сборы.
Требования к мощности
Цены, рассчитанные на основе сообщения ExtraGuestCharges действительны только при соблюдении всех требований к вместимости. Дополнительную информацию см. в разделе «Транзакция (данные об объекте недвижимости)» .
Запросы
Синтаксис
В сообщении ExtraGuestCharges используется следующий синтаксис:
<?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>
Элементы и атрибуты
Сообщение ExtraGuestCharges содержит следующие элементы и атрибуты:
| Элемент / @Атрибут | События | Тип | Описание |
|---|---|---|---|
| ExtraGuestCharges | 1 | Complex element | Корневой элемент этого сообщения. |
| ExtraGuestCharges / @partner | 1 | string | Партнерский аккаунт для этого сообщения. Это строковое значение представляет собой значение Partner key , указанное на странице «Настройки учетной записи» в Hotel Center. Примечание: Если у вас есть бэкэнд, предоставляющий данные для нескольких учетных записей, это значение должно совпадать со значением атрибута |
| ExtraGuestCharges / @id | 1 | string | Уникальный идентификатор для данного запроса. Это значение возвращается в ответном сообщении. Допустимые символы: az , AZ , 0-9 , _ (подчеркивание) и - (тире). |
| ExtraGuestCharges / @timestamp | 1 | DateTime | Дата и время создания этого сообщения. |
| ExtraGuestCharges / HotelExtraGuestCharges | 0..n | HotelExtraGuestCharges | Контейнер для оплаты услуг отдельного объекта недвижимости. |
| ExtraGuestCharges / HotelExtraGuestCharges / @hotel_id | 1 | string | Уникальный идентификатор объекта недвижимости. Это значение должно совпадать с идентификатором отеля, указанным с помощью <id> в элементе <listing> в ленте списка отелей. Идентификатор отеля также указан в Hotel Center . |
| ExtraGuestCharges / HotelExtraGuestCharges / @action | 0..1 | enum | Указывает способ применения обновления. Поддерживается только overlay , по умолчанию используется наложение. Все предыдущие платежи по этому объекту списываются до применения обновления. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge | 0..99 | ExtraGuestCharge | Единый набор платежей за объект недвижимости. Он может содержать ограничения на порядок применения платежей и на то, как они рассчитываются в зависимости от возраста или категории гостей. Каждый |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets | 1 | AgeBrackets | Контейнер с возрастными категориями, используемый для расчета платы в зависимости от возраста или категории гостя. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / AdultCharge | 0..1 | AdultCharge | Контейнер для оплаты проезда дополнительного взрослого. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / AdultCharge / @amount | 0..1 | float | Положительное десятичное значение, указывающее фиксированную сумму, взимаемую за дополнительного взрослого. Эта сумма взимается в той же валюте, что и плата за ночь. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets | 0..1 | ChildAgeBrackets | Контейнер для дополнительной оплаты за ребенка. Указанные возрастные категории могут охватывать только возраст от 0 до 17 лет включительно. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket | 1..99 | ChildAgeBracket | Плата, взимаемая с детей определенного возраста. Возрастные категории должны быть упорядочены от наименьшего max_age до max_age . Сумма к оплате может быть указана с помощью атрибутов amount , percentage или discount_amount . Для каждой категории <ChildAgeBracket> необходимо указать ровно один из этих атрибутов. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @max_age | 1 | integer | Максимальный возраст, для которого могут применяться сборы, указанные в <ChildAgeBracket> . Минимальный возраст равен нулю, если перед этим не указан другой <ChildAgeBracket> . В противном случае он на единицу больше максимального возраста в предыдущем диапазоне. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @exclude_from_capacity | 1 | boolean | Логическое значение, указывающее, следует ли учитывать ребенка данной возрастной группы при расчете общей вместимости номера и детской вместимости. Эти значения можно установить с помощью транзакции (Данные свойства) . Например, младенцы младше определенного возраста могут не учитываться при расчете детской вместимости. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @amount | 0..1 | float | Неотрицательное десятичное значение, указывающее фиксированную сумму, взимаемую за каждого дополнительного ребенка в данной ценовой категории. Эта сумма взимается в той же валюте, что и плата за ночь. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @percentage | 0..1 | float | Десятичное значение от 1 до 99, указывающее процент от стоимости взрослого номера, который должен взиматься за каждого дополнительного ребенка в этой ценовой категории. Эта плата взимается в той же валюте, что и плата за ночь. Подробности о том, как рассчитывается цена для взрослых, см. в обсуждении в разделе |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @discount_amount | 0..1 | float | Положительное десятичное значение, указывающее на фиксированную скидку от стоимости взрослого номера за каждого дополнительного ребенка в этой ценовой категории. Эта сумма взимается в той же валюте, что и указанная для посуточных тарифов. Как правило, плата за ребенка в этой возрастной категории рассчитывается путем вычитания фиксированной суммы из «стоимости за единицу». Более подробно о стоимости за единицу говорится в разделе атрибута |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @counts_as_base_occupant | 0..1 | string | Если указан атрибут Цель здесь состоит в том, чтобы получить «единичную цену», на основе которой можно рассчитать фактическую стоимость. Значение этого атрибута должно быть одним из следующих:
|
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes | 0..1 | RoomTypes | Контейнер для списка типов номеров, к которым применяется плата. Плата применяется к каждому указанному <RoomType> . Если <RoomTypes> не указан, плата применяется ко всем номерам в указанном объекте размещения. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes / RoomType | 1..n | RoomType | Указывает тип номера. Тип номера определяется в элементе <RoomData> в сообщении транзакции (данные объекта недвижимости) и указывается с помощью значения <RoomID> . (Значение <RoomID> также указывается атрибутом InvTypeCode в сообщениях OTA_HotelRateAmountNotifRQ.) |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes / RoomType / @id | 1 | string | Уникальный идентификатор инвентаря (типа номера). Это значение сопоставляется с <RoomID> в сообщении транзакции (данные об объекте недвижимости). Максимально допустимое количество символов — 50. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans | 0..1 | RatePlans | Контейнер для списка тарифных планов, к которым применяются сборы. Если <RatePlans> не указан, сборы применяются ко всем тарифным планам. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans / RatePlan | 1..n | RatePlan | Указывает тарифный план. Тарифный план определяется комбинацией пакета услуг, тарифов и доступности, как это определено в сообщениях Transaction (Property Data), OTA_HotelRateAmountNotifRQ и OTA_HotelAvailNotifRQ, а также идентифицируется по PackageID. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans / RatePlan / @id | 1 | string | Уникальный идентификатор тарифного плана. Это значение сопоставляется со значением PackageID в <PackageData> в сообщении транзакции (данные объекта) и с атрибутом RatePlanCode в <StatusApplicationControl> в сообщениях <OTA_HotelRateAmountNotifRQ> и <OTA_HotelAvailNotifRQ> . Максимальное допустимое количество символов — 50. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates | 0..1 | StayDates | Контейнер для одного или нескольких диапазонов дат, определяющих порядок начисления сборов. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange | 1..99 | DateRange | Диапазон дат, указывающий периоды, когда должна быть применена акция. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @start | 0..1 | Date | Начальная дата (с учетом часового пояса объекта недвижимости), включая дату начала диапазона дат. Эта дата должна быть раньше или совпадать с end датой. Если start не указана, диапазон дат фактически неограничен с точки зрения начальной даты. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @end | 0..1 | Date | Конечная дата (с учетом часового пояса объекта недвижимости), включая дату начала, указанную в диапазоне дат. Эта дата должна совпадать с start датой или быть позже нее. Если end не указана, диапазон дат фактически не ограничен в отношении конечной даты. |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @days_of_week | 0..1 | string | Дни недели, разрешенные в указанном диапазоне дат. Если не указано иное, разрешены все дни недели. Каждый символ в строке обозначает день недели. Например, "MTWHF" указывает, что в указанном диапазоне дат разрешены будние дни. Допустимые символы:
Допустима любая комбинация символов. |
Примеры
Плата за взрослых
Плата за каждого дополнительного взрослого может быть выражена только в виде фиксированной суммы. В следующем примере показано сообщение ExtraGuestCharges , в котором указана плата за каждого взрослого:
<?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>
Вот соответствующие тарифы:
<?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>
Когда пользователь ищет в Google четырех взрослых, общая сумма составит 170 = 120 + 50.
120 берется из ставки <BaseByGuestAmt> с NumberOfGuests="3" , а 50 — из AdultCharge amount="50" .
Обвинения в отношении детей
Стоимость услуг для детей указывается в возрастных категориях до 17 лет и может быть выражена в виде фиксированных сумм, процентов или скидок.
В следующем примере показано сообщение ExtraGuestCharges , в котором указаны дочерние платежи:
<?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>
Вот соответствующие тарифы:
<?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
Ограничения на взимание платы
Все виды ограничений являются необязательными, и можно использовать любую их комбинацию.
В следующем примере показано сообщение ExtraGuestCharges , в котором указаны ограничения:
<?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>
В приведенном выше сообщении указано, что с взрослых следует взимать плату за любой номер типа «queen» или «king-size» с тарифным планом «бесплатный Wi-Fi» или «горячий завтрак» в период с 1 сентября 2020 года по 14 сентября 2020 года.
Пересекающиеся обвинения
В этом разделе приведен пример некорректного сообщения, в котором указаны разные суммы оплаты за одни и те же комбинации дат и товаров.
<?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>
Приведенное выше сообщение недействительно, поскольку первый параметр <ExtraGuestCharge> указывает, что за номера "queen-size" и "free-wifi" с 1 по 14 сентября следует взимать плату в размере 50 долларов за каждого дополнительного взрослого. Второй <ExtraGuestCharge> указывает, что за любые номера "queen-size" или "king-size" с любым из вариантов "free-wifi" или "hot-breakfast" с 1 по 5 сентября следует взимать плату в размере 20 долларов за каждого дополнительного взрослого. Имеется дублирование платежей за номера "queen-size" и "free-wifi" с 1 по 5 сентября, а также конфликт в вопросе о том, следует ли взимать 20 или 50 долларов за каждого дополнительного взрослого.
Ответы
Синтаксис
В сообщении ExtraGuestChargesResponse используется следующий синтаксис:
<?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>
Элементы и атрибуты
Сообщение ExtraGuestChargesResponse содержит следующие элементы и атрибуты:
| Элемент / @Атрибут | События | Тип | Описание |
|---|---|---|---|
| ExtraGuestChargesResponse | 1 | Complex element | Корневой элемент, указывающий на успешность или проблемы, возникшие при получении запроса ExtraGuestCharges . |
| ExtraGuestChargesResponse / @timestamp | 1 | DateTime | Дата и время создания этого сообщения. |
| ExtraGuestChargesResponse / @id | 1 | string | Уникальный идентификатор из соответствующего сообщения ExtraGuestCharges . |
| ExtraGuestChargesResponse / @partner | 1 | string | Это сообщение отправлено на учетную запись партнера. |
| ExtraGuestChargesResponse / Success | 0..1 | Success | Указывает на то, что сообщение ExtraGuestCharges было успешно обработано без предупреждений, ошибок или сбоев. В каждом сообщении присутствует либо |
| ExtraGuestChargesResponse / Issues | 0..1 | Issues | Контейнер для одной или нескольких проблем, возникших при обработке сообщения ExtraGuestCharges . В каждом сообщении присутствует либо |
| ExtraGuestChargesResponse / Issues / Issue | 1..n | Issue | Описание предупреждения, ошибки или сбоя, возникшего при обработке сообщения ExtraGuestCharges . Подробную информацию об этих проблемах можно найти в разделе «Сообщения об ошибках состояния ленты» . |
| ExtraGuestChargesResponse / Issues / Issue / @code | 1 | integer | Идентификатор проблемы. |
| ExtraGuestChargesResponse / Issues / Issue / @status | 1 | enum | Тип возникшей проблемы. Допустимые значения: |
Примеры
Успех
Ниже приведён ответ на успешно обработанное сообщение ExtraGuestCharges .
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestChargesResponse timestamp="2020-05-18T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Success/>
</ExtraGuestChargesResponse>
Проблемы
Ниже приведён ответ на сообщение ExtraGuestCharges , не обработанное из-за ошибок.
<?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>