4.2. GuestRequests: quote requests, booking reservations and cancellations¶
The typical use case for GuestRequests is a portal that collects quote requests, booking reservations or booking cancellations from potential customers and stores them until a client (typically the software used by a hotel) retrieves them.
In this case, the client sends a first request to obtain the information from the server about any requests, reservations or cancellations with the parameter action set to the value OTA_Read:GuestRequests.
The server then responds with the requested information.
Successively, the client sends a follow-up request to acknowledge having received the information, with the parameter action set to the value OTA_NotifReport:GuestRequests.
Please note that a server that has announced support for OTA_Read:GuestRequests MUST also support the action OTA_NotifReport:GuestRequests so that the client can execute follow-up acknowledgement requests. See section 4.2.3 and section 4.2.4 for more details.
Push Support¶
Starting with AlpineBits version 2018-10 it is possible to push the GuestRequest instead of polling them. Please note that this functionality relies on a few arrangements between the two parties that are not negotiated through AlpineBits, namely the endpoint (URL) where the client can receive the pushed GuestRequests, its credentials, etc. This behavior is described in section 4.2.6 and 4.2.7, but the XML structure of the HotelReservation is the same as in the rest of this chapter.
4.2.1. First client request¶
The action paramater is set to the value OTA_Read:GuestRequests and the request parameter must contain a OTA_ReadRQ document.
For the attributes HotelCode and HotelName the rules are the same as for room availability notifications (section 4.1.1).
The element SelectionCriteria with the Start attribute is optional.
When given, the server will send only inquiries generated after the Start timestamp, regardless whether the client has retrieved them before or not.
When omitted, the server will send all inquiries it has on record and that the client has not yet retrieved.
|
|
4.2.2 Server response¶
The server will send a response indicating the outcome of the request. The response is a OTA_ResRetrieveRS document. Any of the four possible AlpineBits® server response outcomes (success, advisory, warning or error) are allowed.
See Appendix A for details.
In case of success, the OTA_ResRetrieveRS response will contain a single, empty Success element followed by a ReservationsList element with zero or more HotelReservation elements containing the requested information (zero elements indicate the server has no information for the client at this point).
Each HotelReservation must have the attributes CreateDateTime (the timestamp the information was collected by the portal). Furthermore the ResStatus attribute must be set. AlpineBits® expects it to be one of the following four:
-
Requested- this is a request for a quote, newsletter or catalog. -
Reserved- this is a booking reservation. -
Modify- this is a booking modification. -
Cancelled- this is a booking cancellation.
For a newsletter- or catalog request the optional attribute RoomStayReservation must be explicitly set to false.
The following example is a reservation (thus, ResStatus is Reserved). The documentation kit also has an example of a quote request. A cancellation is discussed later.
First, consider the outer part of the OTA_ResRetrieveRS document:
|
|
Each HotelReservation contains a mandatory UniqueID element that the client can use to recognize information it has already processed.
The UniqueID element must have the Type attribute set according the OTA Unique Id Type list (UIT). The value must be consistent with the ResStatus attribute of the surrounding HotelReservation element:
-
For ResStatus =
Requested, the Type must be 14 (Reservation). -
For ResStatus =
Reserved, the Type must be 14 (Reservation). -
For ResStatus =
Modify, the Type must be 14 (Reservation). -
For ResStatus =
Cancelled, the Type must be 15 (Cancellation).
The attribute ID is a free text field suitable for uniquely identifying the HotelReservation.
The actual data is then split into three parts: each HotelReservation contains the elements: RoomStays, ResGuests and ResGlobalInfo discussed in the following paragraphs.
Part I: RoomStays (mandatory for reservations, optional for quote requests, disallowed for newsletter- or catalog requests).
The RoomStays element contains one or more RoomStay elements, each indicating a desired stay.
|
|
Each RoomStay element contains:
-
One RoomType element (mandatory for reservations, optional for quote requests): see below for an explanation;
-
One RatePlan element with:
-
A RatePlanCode attribute (mandatory for reservations, optional for quote requests).
-
Zero or one Commission elements with either a Percent attribute (the commission in percent) or a CommissionPayableAmount sub-element with attributes Amount and CurrencyCode; the Amount must follow the currency decimal format.
-
One MealsIncluded element (mandatory for reservations, optional for quote requests): the MealsIncluded element must contain the MealPlanCodes attribute (values see below) and must have the MealPlanIndicator attribute set to true;
-
-
One GuestCounts element (mandatory) indicating the number of all adults (identified by zero or one GuestCount element with no Age attribute given) and the number of all children (identified by zero or more GuestCount element with Age attribute given); of course all guests must be listed and their total (adults + children) must not be zero.
-
One TimeSpan element (mandatory): see below for an explanation.
-
One PaymentCard element (only for reservations, optional) with:
-
The mandatory attributes CardCode (the card issuer, two uppercase letters, such as "VI" for Visa) and ExpireDate (four digits).
-
The optional sub-element CardHolderName.
-
The mandatory sub-element CardNumber (see below).
-
-
One Total element (mandatory for reservations, optional for quote requests) containing the cost after taxes the portal has displayed to the customer, both attributes AmountAfterTax and CurrencyCode are required; the AmountAfterTax must follow the currency decimal format.
The CardNumber element is used to send a credit card number. The number can be sent either as plain text (but note the message transport is encrypted using HTTPS) or encrypted.
For the plain text case, the CardNumber element has no attributes and must contain a PlainText sub-element holding the complete credit card number or its last four digits as in the example above.
For the encrypted case, the CardNumber element must not have any sub-elements and must have attributes EncryptedValue (a string representation of the encrypted card number) and EncryptionMethod (a string identifying the encryption method, e.g. "RSA-PKCSV2.2").
For reservations, the RoomType element is mandatory. Reservations must refer to a specific room category (specified by RoomTypeCode). Quote requests should refer a specific room category whenever possible (specified by the optional attribute RoomTypeCode) but may refer to a generic GRI (specified by the optional attribute RoomClassificationCode) or may be completely open if the RoomType element is present without attributes.
The RoomTypeCode must be identical to the InvTypeCode attribute used for room categories (see section 4.1.1).
The RoomClassificationCode follows the OTA list "Guest Room Info" (GRI). It is used to loosely classify the kind of guest room (42 means just "Room", 13 means "Apartments", 5 means "Pitches", etc.) wished by the guest.
The optional RoomType attribute may be specified, see the definition of the RoomType attribute used for the Inventory (see section 4.4.1) for the list of values defined by AlpineBits®. If the RoomType attribute is specified, then also RoomClassificationCode must be present.
Regarding the MealPlanCodes attribute, AlpineBits® does not use the single Breakfast/Lunch/Dinner booleans, but relies on the MealPlanCodes attribute only. The following codes (a subset of the full OTA list) are allowed:
-
1 - All inclusive
-
3 - Bed and breakfast
-
10 - Full board
-
12 - Half board
-
14 - Room only
The TimeSpan element deserves a more detailed explanation.
For reservations (ResStatus is Reserved or Modify), the arrival and departure date must be given with the Start and End attributes of the TimeSpan element. No other attributes and no sub elements must be present in TimeSpan.
For quote requests (ResStatus is Requested) the timespan can be given in the same way (i.e. using the Start and End attributes) or it may be given as a window. In this case the TimeSpan element must have the Duration attribute (encoded in ISO 8601) and the StartDateWindow sub element with attributes EarliestDate and LatestDate which must be greater than EarliestDate indicating a range of possible start dates.
Duration are given in nights, the form is thus always PxN where x is a number.
A reservation can contain multiple RoomStay elements. Thus, different rooms with different RatePlans can be managed in one reservation. In addition, it is possible to book a stay of, for example, 10 days with a weekly flat rate and a standard offer for the remaining days.
The optional RoomStayGroupID attribute comes into play when alternative room stays or periods need to be transmitted. Note that this is valid for quote requests only (ResStatus is Requested) and they cannot be used together. Each room type with the same RoomStayGroupID indicates a group of room types which must be requested together, meaning that RoomStayGroupID set to "1" is the first alternative, RoomStayGroupID set to "2" the second alternative and so on. One or more alternatives can be specified by using a different identifier.
Part II: ResGuests (mandatory).
Nested inside the ResGuests element is exactly one Customer element, providing the data of the primary guest.
The Gender attribute can be Male, Female or Unknown. The BirthDate attribute follows ISO 8601. The Language follows ISO 639-1 (two-letter lowercase language abbreviation). It identifies the language to be used when contacting the customer.
These three attributes are all optional. However, it is recommended that at least gender and language be specified (so the customer can be addressed properly).
|
|
The Customer element contains:
-
One PersonName element with NamePrefix, GivenName (mandatory), Surname (mandatory) and NameTitle.
-
Zero or more Telephone elements with the optional PhoneTechType attribute: it indicates the phone technology (1 → voice, 3 → fax, 5 → mobile per OTA).
-
One optional Email element.
-
One optional Address element with the (all optional) elements AddressLine , CityName , PostalCode and CountryName with Code attribute; the Code attribute follows ISO 3166-1 alpha-2 (two-letter uppercase country codes)
Note that most elements and attributes under the ResGuests element are optional in the AlpineBits® schema. It is, however, expected that as much contact information as possible is given.
The Email element may contain the attribute Remark having either values newsletter:yes or newsletter:no indicating whether the customer does or does not wish to receive an email newsletter. A missing Remark indicates the information is not known - for new customers this should be treated the same way as if a newsletter:no was given (do not send a newsletter), while existing customer records should not be updated.
Analogously, the Address element may contain the attribute Remark having either values catalog:yes or catalog:no indicating whether the customer does or does not wish to receive print ads by mail. A missing Remark indicates the information is not known - for new customers this should be treated the same way as if a catalog:no was given (do not send a mail), while existing customer records should not be updated.
Part III: ResGlobalInfo (mandatory).
|
|
The ResGlobalInfo element contains:
-
One Comment element (optional) with attribute Name set to
included servicescontaining the included services given as free text fields using ListItem elements (see below). In most cases the AlpineBits® client software will just display this to a human hotel employee with no further processing. -
One Comment element (optional) with attribute Name set to
customer commentcontaining a single Text element freely filled out by the customer and fed through unchecked by the portal. -
One or more SpecialRequest elements (optional) with the following mandatory attributes:
-
CodeContext set to
ALPINEBITSorHOTEL. -
RequestCode set to a distinct value inside of the provided CodeContext.
-
SpecialRequests within CodeContext ALPINEBITS must contain a predefined RequestCode value from the following list:
PETSproviding details regarding pets
SpecialRequests within CodeContext HOTEL contain hotel-specific requests, in which the RequestCode value can be freely defined.
An SpecialRequest element can contain a single Text element (optional) with attribute TextFormat set to PlainText, stating details regarding the specific request. To express that a SpecialRequest element is explictly not wanted by the customer, the Text element must be omitted. On the other hand it is not allowed to express absence inside of the Text element (e.g. “no pets“ or “none” should not be used). An empty Text element means that the request is wanted but provides no further details.
The absence of the whole SpecialRequest element means that the information about a potential presence of a SpecialRequest is not available (i.e. can not be guaranteed their presence nor absence).
Example A: the customer will surely bring pets described as “two dogs”.
|
|
Example B: the customer will surely bring pets but no further information is given.
|
|
Example C: the customer will surely not have any pet with him.
|
|
-
Only allowed for reservations, one PenaltyDescription element (optional) containing a single Text element with no attributes that clearly states the cancellation policy the portal and the hotel have previously agreed upon and the portal has communicated to the customer - the language or languages of this text is chosen by the portal.
-
One or more HotelReservationID elements (optional) that can be used to transmit miscellaneous IDs associated with the reservation the trading partners have agreed upon; ResID_Type must be specified with a value from the OTA "Unique Id Type" list (UIT); the other attributes, ResID_Value, ResID_Source and ResID_SourceContext are all optional; historically, AlpineBits® has used these fields to handle internet campaign management: in this case the agreement is to use a ResID_Type value of "13" (internet broker) and the three attributes ResID_Value, ResID_Source and ResID_SourceContext identify, respectively, the campaign name (Slogan in our example), the campaign source (www.example.com) and the campaign marketing medium (top banner) following the scheme used by Google Analytics.
-
One optional Profile element with attribute ProfileType set to "4" with information about the booking channel; nested under Profile, a CompanyName element with attributes Code and CodeContext must be present, while the AddressInfo, TelephoneInfo and Email elements are optional: these contain the same data as the equivalent fields in the customer part (note the element names: AddressInfo and TelephoneInfo vs Address and Telephone in the customer part - also different ordering - dictated by OTA)
-
One mandatory BasicPropertyInfo element with the HotelCode and HotelName attributes following the same rules of that used in the corresponding attributes in the request (see section 4.2.1).
Each ListItem element must have Language and ListItem attributes. At most one ListItem element is allowed for each combination of Language and ListItem.
Modifications and Cancellations.
A booking modification (ResStatus is Modify) is identical to a booking reservation (ResStatus is Reserved). However, for a booking modification the client will recognize the UniqueId attribute and act accordingly, updating the reservation instead of adding a new one.
Besides quote requests and booking reservations, also cancellations can be handled. For cancellations the ResStatus is Cancelled as shown in the following example:
|
|
Each HotelReservation must of course have the attributes CreateDateTime and ResStatus set to Cancelled.
Of course, the element UniqueID is mandatory, again with mandatory attribute Type 15 and attribute ID referring to the reservation that is being cancelled! Other reservation elements may be also sent.
4.2.3. Follow-up client request (acknowledgement)¶
A client, upon receiving a non-empty response to its first request (OTA_Read:GuestRequests), should initiate another request, acknowledging or refusing the UniqueID values it got (referring to quotes, reservations or cancellations).
For this follow-up request, the action paramter is set to the value OTA_NotifReport:GuestRequests and the parameter request must contain a OTA_NotifReportRQ document.
For the refusal, a standard Warning element is used. The value of the attribute Type can be set to any value of the OTA list "Error Warning Type" (EWT). The value 3 stands for "Biz rule". The attribute Code can be set to any value present in the OTA list "Error Codes" (ERR). The value 450 stands for "Unable to process". For the acknowledgments, the client again uses the HotelReservation element, one for each ID it wishes to acknowledge.
Here is an example where a client refuses one reservation request and acknowledges three other requests.
|
|
The following rules apply to acknowledgements:
-
For every UniqueID, the server must remember whether or not the client has acknowledged it yet.
-
It is a client’s responsibility to send the acknowledgments - if it doesn’t, it must be prepared to deal with duplicates the next time it queries the server.
Here is a sample sequence of messages exchanged between a client and a server:
| time | client request | server response | comment [small] |
|---|---|---|---|
08:00 [small] |
action = OTA_Read:GuestRequests; |
OTA_ResRetrieveRS with UniqueID=1 (Reservation) and UniqueID=2 (Request) [small] |
the server answers with today’s two requests (1 and 2) [small] |
08:01 [small] |
action = OTA_NotifReport:GuestRequests; |
OTA_NotifReportRS Success [small] |
server knows the client got 1, it will not be sent again [small] |
09:00 [small] |
action = OTA_Read:GuestRequests; |
OTA_ResRetrieveRS with UniqueIDs 2 and 3 (Request) [small] |
the client wishes to read all new requests, 1 is not sent (since it was ack’ed), 2 is sent again and 3 is sent because it’s new [small] |
10:00 [small] |
action = OTA_Read:GuestRequests; |
OTA_ResRetrieveRS with UniqueIDs 2 and 3 (Request) [small] |
same server response as at 09:00 because 2 and 3 were not ack’ed [small] |
10:01 [small] |
action = OTA_NotifReport:GuestRequests; |
OTA_NotifReportRS Success [small] |
server now knows the client got all three [small] |
11:00 [small] |
action = OTA_Read:GuestRequests; |
OTA_ResRetrieveRS with UniqueIDs 1, 2 and 3 (Request) [small] |
the SelectionCriteria Start overrides the fact that all three guest requests had already been ack’ed, so the server sends all three again |
4.2.4. Follow-up server response¶
The server will send a response indicating the outcome of the request. The response is a OTA_NotifReportRS document. Any of the four possible AlpineBits® server response outcomes (success, advisory, warning or error) are allowed.
See Appendix A for details.
4.2.5. Implementation tips and best practice¶
The attribute RatePlanCode is mandatory for reservations and is meant to refer a reservation to the originating RatePlan. If reservations are not originated from an AlpineBits® Rateplan this information may be unavailable. In this case it is recommended to set the value of the RatePlanCode attribute to the string "Unknown" (with a capital "U", please note that OTA schemas do not allow an empty value for this attribute).
Every CurrencyCode attribute must be consistent with the originating RatePlan. In case of "Unknown" RatePlan, the currency must be one supported by the hotel or previously agreed upon for communication.
If a non-standard MealsIncluded has to be transmitted, consider using the closest standard MealsIncluded combination. This needs prior agreement among the parts, which is not covered by AlpineBits®. For example in South-Tyrol some hotels offer ¾ board (half board plus afternoon snack, hence a non-standard MealsIncluded combination) to their guests. This may be transmitted as half board, since ¾ board replaces half board for these hotels.
The value of the PhoneNumber attribute (element Telephone) should contain the standard international format (as in +<country code><phone number>) whenever possible.
Some guidelines on how to fill the fields in the HotelReservationID and Profile / CompanyInfo elements are provided here in order to allow easier grouping of the data coming from different servers.
The attributes of the HotelReservationID attributes can be mapped to the attributes used for internet marketing like in the following table:
utm_source |
ResID_Source |
utm_medium |
ResID_SourceContext |
utm_content |
not present in AlpineBits® |
utm_campaign |
ResID_Value |
We can then distinguish different use cases - here are some examples:
1. Request or reservation via homepage
-
Direct (user types domain into browser address bar)
ResID_Source (utm_source) = direct
ResID_SourceContext (utm_medium) =
ResID_Value (utm_campaign) =
Profile / CompanyInfo (travel agent / booking channel) = homepage -
Referral link to hotel site from other website
ResID_Source (utm_source) = otherwebsite.com
ResID_SourceContext (utm_medium) = referral
ResID_Value (utm_campaign) =
Profile / CompanyInfo (travel agent / booking channel) = homepage -
Referral link to hotel site from portal website with campaign infos
ResID_Source (utm_source) = portalwebsite.com
ResID_SourceContext (utm_medium) = referral (or exact medium type of portal, e.g. "banner", "membership", "toplinks")
ResID_Value (utm_campaign) = [campaign-name]
Profile / CompanyInfo (travel agent / booking channel) = homepage -
Search engine organic
ResID_Source (utm_source) = google.com
ResID_SourceContext (utm_medium) = organic_search
ResID_Value (utm_campaign) =
Profile / CompanyInfo (travel agent / booking channel) = homepage -
Search engine paid (e.g. Google Adwords)
ResID_Source (utm_source) = google.com
ResID_SourceContext (utm_medium) = cpc
ResID_Value (utm_campaign) = [campaign-name]
Profile / CompanyInfo (travel agent / booking channel) = homepage -
Social media content link (e.g. Facebook)
ResID_Source (utm_source) = facebook.com
ResID_SourceContext (utm_medium) = social_media
ResID_Value (utm_campaign) = [facebook-post]
Profile / CompanyInfo (travel agent / booking channel) = homepage -
Social media paid (e.g. Facebook Ads)
ResID_Source (utm_source) = facebook.com
ResID_SourceContext (utm_medium) = cpc
ResID_Value (utm_campaign) = [campaign-name]
Profile / CompanyInfo (travel agent / booking channel) = homepage -
Newsletter
ResID_Source (utm_source) = newsletter-[company-name]
ResID_SourceContext (utm_medium) = email
ResID_Value (utm_campaign) = [newsletter-name] (e.g. NL 09/2017)
Profile / CompanyInfo (travel agent / booking channel) = homepage -
QR code in printed magazine
ResID_Source (utm_source) = [magazine-name] (e.g. Bergwelten)
ResID_SourceContext (utm_medium) = qr_code
ResID_Value (utm_campaign) = [magazine-name-and-issue] (e.g. Bergwelten 08/2017)
Profile / CompanyInfo (travel agent / booking channel) = homepage
2. Request or reservation via landing page
-
Bookings/enquiries on landing pages from Google Adwords
ResID_Source (utm_source) = google.com
ResID_SourceContext (utm_medium) = cpc
ResID_Value (utm_campaign) = [campaign-name]
Profile / CompanyInfo (travel agent / booking channel) = landingpage -
Bookings/enquiries on landing pages from portal links
ResID_Source (utm_source) = portalwebsite.com
ResID_SourceContext (utm_medium) = referral (or exact medium type of portal, e.g. "banner", "membership", "toplinks")
ResID_Value (utm_campaign) = [campaign-name]
Profile / CompanyInfo (travel agent / booking channel) = landingpage
3. Reservation on a booking platform
-
Bookings on booking portal (e.g. Booking.com)
ResID_Source (utm_source) = booking.com
ResID_SourceContext (utm_medium) =
ResID_Value (utm_campaign) =
Profile / CompanyInfo (travel agent / booking channel) = [booking portal name] (e.g. booking.com) -
Bookings/enquiries on portals (e.g. suedtirolerland.it)
ResID_Source (utm_source) = [portal name] (e.g. suedtirolerland.it)
ResID_SourceContext (utm_medium) =
ResID_Value (utm_campaign) =
Profile / CompanyInfo (travel agent / booking channel) = [portal operator] (e.g. Peer.travel)
4.2.6. Requests Push client request¶
Starting with AlpineBits version 2018-10, a new capability was added (action_OTA_HotelResNotif_GuestRequests) to allow a push mechanism for the GuestRequest. If the capability is exposed, the Client is capable of acting as an AlpineBits Server, and the Server is capable of acting as an AlpineBits Client. This means that a few arrangements between the two parties have to be made, and those are not negotiated through AlpineBits, namely the endpoint (URL) where the client can receive the pushed GuestRequests, its credentials, etc.
The action parameter is set to the value OTA_HotelResNotif:GuestRequests and the parameter request must contain a OTA_HotelResNotifRQ document.
Please note that this message does not allow to specify a HotelCode or HotelName in the root element, this information is however provided in the corresponding attributes within each Request’s BasicPropertyInfo element. All the Request exchanged with a single message must refer to the same Hotel.
The request must contain a single HotelReservations element with zero or more HotelReservation elements containing the requested information (zero elements indicate the client has no information for the server, but the Client should not initiate a transfer in this case). As for the content of the HotelReservation element, refer to section 4.2.2.
All the GuestRequests described above (e.g. Booking Requests, Quote Requests, Cancellations) can be pushed by using this mechanism.
4.2.7 Requests Push server response¶
The server will send a response indicating the outcome of the request. The response is a OTA_HotelResNotifRS document. Any of the four possible AlpineBits® server response outcomes (success, advisory, warning or error) are allowed.
See Appendix A for details.
In case of success, the OTA_HotelResNotifRS response will contain a single, empty Success element followed by a HotelReservations element with zero or more HotelReservation elements. Each HotelReservation element must contain only a single UniqueID element with the Type and [xml_attribute_name]#ID" attributes referring to one of the GuestRequests the Client sent (quotes, reservations or cancellations).
Each request that could not be processed must be listed in a Warning element, where the RecordID attribute refers to the request ID and Type and Code refer to the reason of the refusal.
|
|
4.2.8 Guest Requests status update¶
Starting with AlpineBits® version 2022-10, clients can send status updates of a given guest request to the server.
The action parameter is set to the value OTA_HotelResNotif:GuestRequests_StatusUpdate and the request parameter must contain a OTA_HotelResNotifRQ document.
The request must contain a single HotelReservations element with one or more HotelReservation elements containing the guest request status update.
Each HotelReservation element must contain the mandatory attributes ResStatus and CreateDateTime (the first timestamp recorded by the client for the guest request). The possible values for the ResStatus attribute expected by AlpineBits® are:
-
Reserved - this is a booking reservation.
-
Cancelled - this is a booking cancellation.
A HotelReservation element may contain the LastModifyDateTime attribute which identifies the timestamp of modification. If the LastModifyDateTime attribute is not specified, the timestamp of the request may be used instead.
Each HotelReservation element contains a mandatory UniqueID element which itself contains the mandatory ID and Type attributes. The ID attribute must match the unique HotelReservation identifier previously sent by the server. The Type attribute is set according to the OTA Unique Id Type (UIT) list.
The Type attribute value must be consistent with the ResStatus attribute of the surrounding HotelReservation element:
-
For ResStatus = Reserved, the Type must be 14 (Reservation).
-
For ResStatus = Cancelled, the Type must be 15 (Cancellation).
Below is an example of a status update sent from a client for some guest requests.
|
|
The server’s response is the same as that described in Chapter 4.2.7.