Тарифы, отправленные через <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 | Уникальный идентификатор этого сообщения запроса. Это значение возвращается в ответном сообщении. Допустимые символы: a-z, A-Z, 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 | Логическое значение, указывающее, должен ли ребенок в этой возрастной группе учитываться при расчете общей вместимости номера и вместимости для детей. Эти значения можно задать с помощью свойства Transaction(Property Data). Например, младенцы младше определенного возраста могут не учитываться при подсчете количества детей. |
| 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> сообщения Transaction (Property Data), а ссылка на него указывается с помощью значения <RoomID>. (На его значение <RoomID> также ссылается атрибут InvTypeCode в сообщениях OTA_HotelRateAmountNotifRQ.) |
| ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes / RoomType / @id | 1 | string | Уникальный идентификатор инвентаря (типа номера). Это значение сопоставляется с элементом <RoomID> в сообщении Transaction (Property Data).
Максимальное количество символов: 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>
Если пользователь ищет номер на четырех взрослых, общая цена составит 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 и тарифным планом free-wifi или hot-breakfast в период с 1 по 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 и free-wifi с 1 по 14 сентября взимается плата в размере 50. Второй элемент <ExtraGuestCharge> указывает, что за каждого дополнительного взрослого гостя, который забронирует номер с большой двуспальной кроватью или кроватью размера "king-size" и бесплатным Wi-Fi или горячим завтраком на период с 1 по 5 сентября, взимается дополнительная плата в размере 20.
В период с 1 по 5 сентября пересекаются цены за номер с двуспальной кроватью и бесплатный Wi-Fi, а также возникает конфликт между ценами за дополнительного взрослого (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>