4.1. FreeRooms: room availability notifications¶
When the value of the action parameter is OTA_HotelInvCountNotif:FreeRooms the client intends to send room availability notifications to the server.
A server that supports this action must support at least one of two capabilities: OTA_HotelInvCountNotif_accept_rooms or OTA_HotelInvCountNotif_accept_categories. This way the server indicates whether it can handle the availability of rooms at the level of distinct rooms, at the level of categories of rooms or both (a better explanation will follow).
4.1.1. Client request¶
The parameter request must contain an OTA_HotelInvCountNotifRQ document.
Consider the outer part of the example document:
|
|
An OTA_HotelInvCountNotifRQ may contain just one Inventories (note the plural) element, hence at most one hotel can be dealt with in a single request.
AlpineBits® requires the attributes HotelCode or HotelName to be present (and match information in the server’s database). The fictitious hotel in the example is the "Frangart Inn" with code "123". When specifying both — code and name — only the code is required to be consistent.
AlpineBits® requires a match of HotelCode or HotelName to be case sensitive.
Second, consider the inner part of the example that contains Inventory elements (note the singular) for three different time periods.
|
|
The absence of the InvCode attribute tells us we’re dealing with a room category (DOUBLE) given by the InvTypeCode.
Alternatively, using a InvCode together with a InvTypeCode attribute would indicate that the availability refers to a specific room, not a room category.
AlpineBits® requires a match of InvCode or InvTypeCode to be case sensitive.
An AlpineBits® server must be able to treat at least one out of two cases (specific rooms or categories). A client should perform the OTA_Ping:Handshaking action to find out whether the server treats the room case (token OTA_HotelInvCountNotif_accept_rooms), the category case (token OTA_HotelInvCountNotif_accept_categories) or both.
Mixing rooms and categories in a single request is not allowed. An AlpineBits® server must return an error if it receives such a mixed request.
The Inventory element for a given room/room category can contain an InvCounts (plural) element. Based on the supported capabilities, the InvCounts element contains from 1 to 3 InvCount (singular) elements, one for each of the allowed CountType attributes:
-
CountType =
2indicates rooms that are bookable (this CountType must be supported). -
CountType =
6indicates rooms that are out of order (i.e. rooms that are not booked nor bookable, maybe due to renovations), requires theOTA_HotelInvCountNotif_accept_out_of_ordercapability. -
CountType =
9indicates rooms that are available but not bookable (see section GuestRequests for the description of bookings), requires theOTA_HotelInvCountNotif_accept_out_of_marketcapability.
If the server does not have the corresponding capability set, a client must not send the CountType = 6 or the CountType = 9 elements, and all the rooms not specified in the CountType = 2 element are to be considered as already booked.
The integer value of the attribute Count indicates the room count for the given CountType and must be a non negative number (≥ 0).
If an InvCount element for a specific CountType is missing it must be considered as if its Count attribute is 0. Likewise, if the whole InvCounts container is missing it is considered as if the whole room/room category is fully booked in the given time period (same as CountType = 2 with Count = 0).
Count numbers are always interpreted to be absolute numbers. Differential updates are not allowed.
Since in the example we’re dealing with a room category (InvCode is missing), the value of Count can be > 1. In the case of a specific room (InvCode is specified), the only meaningful value would be 1 (the same room can not be "counted" more than once).
Since overbooking is not allowed and the number of counted rooms (bookable or not) cannot exceed the total number of rooms, the inequality 0 ≤ 'sum of Count values' ≤ 'total number of rooms' holds.
Considering the example, the attributes Start and End and the corresponding InvCount element indicate that room cateogry DOUBLE has 3 rooms available from 2020-08-01 to 2020-08-10 and 1 room available from 2020-08-21 to 2020-08-30; from 2020-08-11 to 2020-08-20 there are no DOUBLE rooms available.
Regarding the first interval, this means the earliest possible check-in is 2020-08-01 afternoon and latest possible check-out is 2020-08-11 morning (maximum stay is 10 nights).
Check-ins after 2020-08-01 and stays of less than 10 nights are allowed as well, provided the check-out is not later than the morning of 2020-08-11.
Same applies for the third block of 10 nights from 2020-08-21 to 2020-08-30 (latest check-out is 2020-08-31 morning).
During the second time period, from 2020-08-11 to 2020-08-20, no check-in is possible.
Note that AlpineBits® does not allow Inventory elements with overlapping periods regarding the same room or room category. This implies that the order of the Inventory elements doesn’t matter. It is a client’s responsibility to avoid overlapping. An AlpineBits® server’s business logic may identify overlapping and return an error or may proceed in an implementation-specific way.
CompleteSet¶
Clients and servers typically wish to exchange only delta information about room availabilities in order to keep the total amount of data to be processed in check.
However, AlpineBits® considered several use-cases in which it is important to transmit the complete availability information, as might be the case for a first synchronization or for aligning two systems after a communication issue. For this reason it defines a request that has the purpose of resetting the server information with that contained in the message. Such request is called a CompleteSet.
If a server provides the capability OTA_HotelInvCountNotif_accept_complete_set, then a client may send a CompleteSet message as explained below.
In the example, the UniqueID element with attribute Instance = CompleteSet and Type = 16 indicates that this message contains the complete information (as entered by the user). When receiving such a request, a server must remove all information about any availability it might have on record regarding the given hotel.
The attribute ID is needed for compatibility with OTA, the value is ignored by AlpineBits®.
In a CompleteSet message all the rooms/room categories managed by the client must be specified for any time period for which the client has data on records. This means that also in cases where a room/room category is fully booked (with no availability), it must have a corresponding Inventory element with its own StatusApplicationControl sub element and a coherent set of InvCount elements contained in it (or no InvCounts container at all, as stated above). This states unambiguously that the room/room category has no availability for the specified period.
A client must not include in a CompleteSet message a period for which it has no data on record (for instance a client that is forwarding data received from a source, must not forward any information besides what was originally received from the source).
Normally the FreeRooms message requires exactly one StatusApplicationControl element with attributes Start, End, InvTypeCode (and optional InvCode) for each Inventory element. The server must return an error if any of these are missing. There is however one exception: to completely reset all room availability information for a given hotel a client might send a CompleteSet request with just one empty Inventory element without any attributes. The presence of the empty Inventory element is required for OTA validation.
In addition, a client might want to let a server know its availability data, should be purged based on internal business rules. An example might be availability data that is considered stale, because it hasn’t been updated by the user for some time. The client should then send a request using an UniqueID element with attribute Instance = CompleteSet and Type = 35. A server must accept this value (without returning an error or warning) and could make use of this hint and keep the availability data it has on record flagging it as purged. Otherwise such a message should be considered equivalent to the one with Type = 16.
Deltas¶
If the UniqueID element is missing, the message contains delta information. In that case the server updates only the information that is contained in the message without touching the other information that it has on record.
A server that supports delta requests must indicate so via the OTA_HotelInvCountNotif_accept_deltas capability. As always, it is the client’s responsibility to check whether the server supports deltas before trying to send them.
AlpineBits® recommends that implementers that use delta requests should send the full set of information periodically if both client and server support it.
If the entire period is explicitly transmitted and processsed in a delta message, this leads to the complete overwriting of the previous situation.
If a server does not support CompleteSet messages, it might lead to cases where the hotel would have to intervene and delete obsolete data from the server manually in its backend.
A server should provide at least one of OTA_HotelInvCountNotif_accept_deltas and OTA_HotelInvCountNotif_accept_complete_set capabilities in order to accept FreeRooms messages.
Closing seasons¶
A special Inventory element can be used to send information about closing seasons, i.e. time periods in which the hotel is completely closed. It is in fact important to distinguish the cases in which a hotel is fully booked (where one could still hope for a last minute cancellation) from those in which a hotel is closed (where it could not even answer the phone).
Closing seasons elements require both parties to expose the OTA_HotelInvCountNotif_accept_closing_seasons capability during handshaking and can only be sent as first Inventory elements in a CompleteSet message. The content of the closing seasons Inventory element is defined as follows:
-
One StatusApplicationControl sub element indicating a time period with the mandatory Start and End attributes and with the mandatory attribute AllInvCode set to
true. -
No InvCounts sub elements are allowed.
Multiple Inventory elements can be specified this way to indicate multiple closing periods.
Each of the closing time periods must not overlap with other closed periods nor with any time period that states a room/room category is available (it is therefore possible for a closed period to overlap with a period where all the rooms/room categories are unavailable). A server must return an error if it detects such inconsistencies.
Delta messages are still to be considered as the most up to date, so in case a delta message would set a room/room category as available in a period previously set as closed, it must be considered as if the hotel revoked the closed period for the overlapping days.
As a best practice, the client should avoid such overwriting or at least send a complete set afterwards in order to explicitly set the correct closed periods. If the server deems it appropriate to force a full synchronization, it might request a CompleteSet in one of its next responses (see Appendix A).
4.1.2. Server response¶
The server will send a response indicating the outcome of the request. The response is a OTA_HotelInvCountNotifRS document. Any of the four possible AlpineBits® server response outcomes (success, advisory, warning or error) are allowed.
See Appendix A for details.
4.1.3. Implementation tips and best practice¶
-
Note that in the 2011-11 version of AlpineBits® the support of this action was mandatory for the server. This is no longer the case.
-
Note that sending partial information (deltas) was added with AlpineBits® 2013-04.
-
Note that this action has been completely re-written in the 2020-10 version of AlpineBits®.
-
It is important that applications that forward data received from other sources (e.g. channel managers and alike) do not forward any information not present in the original data. For example, if such an application manages on its system a wider time frame than the one received from the source, it should not forward any information beyond the most future date it has received. This is necessary to keep the information clean through the forwarding without complementary (and arbitrary) data to be added by third party applications.
-
For
CompleteSetrequests, since no time frame is explicitly transmitted by the client, a server is encouraged to delete and insert all information stored in its backend, rather than updating it. -
Please note that the End date of an interval identifies the last day and night of the stay. Departure is the morning of the day after the End date.
-
Please note that previous versions of AlpineBits® allowed some booking restrictions to be used in FreeRooms (length of stay and day of arrival). This possibility has been removed with version 2014-04 as these restrictions are better handled by RatePlans.