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 section 2.3 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 four parts: each HotelReservation contains the elements: RoomStays, Services, ResGuests and ResGlobalInfo discussed in the following paragraphs.
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.
RoomStays¶
RoomStays is 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 RoomRate element with:
-
A RatePlanCode attribute (mandatory).
-
A RoomTypeCode attribute (mandatory).
-
One ore more Rate elements (mandatory), where each element contains:
-
An EffectiveDate (mandatory) attribute: Indicating the starting date.
-
An ExpireDate attribute: Indicating the ending date.
-
An ExpireDateExclusiveInd attribute: When true, indicates that the ExpireDate is the first day after the applicable period (e.g. when expire date is Oct 15 the last date of the period is Oct 14).
-
An RateTimeUnit attribute: Indicating the time unit for the rate.
-
An UnitMultiplier attribute: Indicating the number of rate time units such as "3 Days".
-
A Base element (mandatory) : The base amount charged for the accommodation or service per unit of time (eg: Nightly, Weekly, etc). Note that any additional charges should be itemized in the other elements.
-
-
-
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, either in DepositPayments or Guarantee (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
TimeSpan
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.
In general, a separate RoomStay element should be used for each room and rate plan.
RoomRates
RoomRates allow to track the exact costs of a room per day.
|
|
This covers two use cases:
-
In eras of revenue management it becomes more and more frequent that each day has its own unique rate. In order to be able to provide the hotel with data on how much revenue was made on each single day, this information needs to be as detailed as possible.
-
Some portals do grant discounts on the prices they receive from PMS. In order to be able to get the information which price has been offered to the guest back to the PMS, the reservation message has to contain the daily room rates (the base price of a single room on a daily basis).
NB: In a PMS (AlpineBits Client) such gross prices for the rooms often have to be split internally, either for internal cost accounting or for tax regulations (different tax rates). Therefore both the sold offer (rate plan) and the calculated room rate must be known in the PMS.
The amounts specified via the Rate/Base element should only define the room rates. Any other surcharges do not need to be specified in detail. Therefore, the total amount specified under ResGlobalInfo/Total may exceed the sum of the room rates.
Regarding RoomRates there are the following rules to be followed:
-
Since there are separate RoomStay elements per room and rate plan, only one RoomRate element is required.
-
The Rate elements defines the unit prices of a certain period per room and time unit.
-
ExpireDate is optional and is usually specified inclusive. If this attribute is omitted, the price is valid only for EffectiveDate.
-
The ExpireDateExclusiveInd attribute is an indicator that must be used only in combination with ExpireDate and determines whether ExpireDate is exclusive (true) or inclusive (false).
-
The amounts specified in the Base element should only define the room rates. Any other surcharges do not need to be specified in detail. Therefore, the total amount specified under ResGlobalInfo/Total may exceed the sum of the room rates.
Services¶
The optional Services element contains one or more Service elements. The Service element can be used to specify additional services booked with the reservation and also allows to give a more precise indication of the price composition.
|
|
Each Service element contains:
-
One ServiceDetails element with:
-
One optional GuestCounts element containing one or more GuestCount elements with the attribute Count and the optional attribute Age. The purpose of this element is to identify the number of guests and their age.
-
One optional TimeSpan element with the mandatory attribute Start and the optional attribute End. The purpose of this element is to specify the exact start and end time of the service.
-
One optional Comments element containing exactly one Comment element. The Comment element contains one Text element having the attribute TextFormat set to
PlainText. This element should be used to add a comment that has been inserted by the customer who has booked the service. -
One mandatory Total element with the mandatory attributes AmountAfterTax and CurrencyCode; the AmountAfterTax must follow the currency decimal format. The indicated amount must not be multiplied by the quantity of the service, but already represents the total cost of the service including all taxes.
-
One optional ServiceDescription element containing one Text element with the attribute TextFormat set to
PlainText. This is used to specify the description of the service.
-
-
The mandatory attribute ServiceCategoryCode is an enumerated type that identifies the category of the service. Allowed values are:
ACTIVITY,BEVERAGE,BOARD,FOOD,SUPPLEMENT,TOURISTTAX,TRANSPORT,OTHER -
The mandatory attribute ServiceInventoryCode for identification of the service in conjunction with the ServiceCategoryCode.
-
The mandatory attribute ID attribute should be used to specify the unique identifier of the originating system. If the originating system does not manage such an ID, it should be set to the concatenated value of ServiceCategoryCode and ServiceInventoryCode to uniquely identify the service.
-
The mandatory attribute ServicePricingType is an enumerated type that indicates how a service was priced. Allowed values are:
Per stay,Per person,Per night,Per person per night,Per use. -
The mandatory attribute Inclusive indicates whether the price for this service is already included in the room rate.
-
The mandatory attribute Quantity is used to indicate the quantity of the booked services. Also serves as the number of persons/nights when pricing class is per person or per person per night.
-
The optional attribute ServiceRPH is a unique ID for a service that may be referenced in a RoomStay element of the HotelReservation
ResGuests¶
Nested inside the mandatory 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.
ResGlobalInfo¶
|
|
The mandatory 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. In most cases the AlpineBits® client software will just display this to a human hotel employee with no further processing. Each ListItem element must have Language and ListItem attributes. At most one ListItem element is allowed for each combination of Language and ListItem. -
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 Comment element (optional) with attribute Name set to
additional infocontaining a single Text element freely filled with additional information NOT entered by the customer. In general this is used by the portal to provide useful information that is not covered by OTA elements. -
One or more SpecialRequest elements (optional). For further specification see dedicated chapter below.
-
One DepositPayments element (optional). For further specification see dedicated chapter below.
-
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 Profiles element (optional). For further specification see dedicated chapter below.
-
One mandatory BasicPropertyInfo element with the mandatory HotelCode and optional HotelName attributes following the same rules of that used in the corresponding attributes in the request (see section 4.2.1).
SpecialRequest
The SpecialRequest element has 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.
|
|
DepositPayments
The DepositPayments element contains one or more GuaranteePayment elements and is used to specify the information about the payments made with the booking.
|
|
Each GuaranteePayment element contains:
-
One AcceptedPayments element containing exactly one AcceptedPayment element. It has the mandatory GuaranteeTypeCode which refers to the OpenTravel Code List Payment Type (PMT). We currently support
28to specify a bank transfer payment,46for online payments and3if the payment was done with a voucher. The mandatory attribute GuaranteeID is used this to identify the payment service provider and the optional PaymentTransactionTypeCode attribute is used this to specify if the amount was already charged or only reserved/pre-authorized. The only allowed values ar eitherchargeorreserve. Nested under the AcceptedPayment element either an PaymentCard, BankAcct or Voucher element must be specified.-
The PaymentCard element should be used to describe online payments made with the booking. The optional attribute CardCode is a 2 digit code that references the credit card vendor. The optional attributes ExpireDate indicates the expiration date of the credit card. The optional CardHolderName element identifies the owner of the card. And the optional CardNumber element can be used to specify more detailed data about the payment made. It has the optional attribute Mask which is used to transmit a masked representation of the card number and the optional attributes Token and TokenProviderID which can be used to transmit the data about the credit card tokenization.
-
The BankAcct element should be used to describe bank transfer payments. The optional BankAcctName could be used to specify the name of the bank accounts owner used for the transaction. And the optional BankAcctNumber can be used to describe more in detail the bank account used for the payment. It has the optional attribute Mask which is used to transmit a masked representation of the bank account number and the optional element PlainText which can be used to specify the entire bank account number.
-
The Voucher element should be used to describe payments made with a voucher. The ElectronicIndicator is mandatory and must be always true. We currently support only electronic vouchers. The mandatory Identifier element should be used to specify the unique code of the voucher.
-
-
One AmountPercent element with the mandatory attributes Amount and CurrencyCode. The purpose of this element is to specify total amount of the payment.
-
The mandatory attribute GuaranteeCode is used to specify the unique identifier of the payment transaction
-
The mandatory attribute Start identifies the timestamp of the payment transaction.
Profiles
The Profiles element contains one Profile element nested within a ProfileInfo element with attribute ProfileType set to "4" with information about the booking channel;
|
|
The Profile element contains:
-
The required CompanyName element with attributes Code and CodeContext.
-
The optional AddressInfo, TelephoneInfo and Email elements: 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)
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 section 2.3 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 section 2.3 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.
4.2.9. Tabular representation of OTA_ReadRQ¶
Unresolved directive in 042-guestrequests.adoc - include::tables/OTA_ReadRQ.adoc[] AlpineBits XSD Schema
4.2.10. Tabular representation of OTA_ResRetrieveRS¶
Unresolved directive in 042-guestrequests.adoc - include::tables/OTA_ResRetrieveRS.adoc[] AlpineBits XSD Schema
4.2.11. Tabular representation of OTA_NotifReportRQ¶
Unresolved directive in 042-guestrequests.adoc - include::tables/OTA_NotifReportRQ.adoc[] AlpineBits XSD Schema
4.2.12. Tabular representation of OTA_NotifReportRS¶
Unresolved directive in 042-guestrequests.adoc - include::tables/OTA_NotifReportRS.adoc[] AlpineBits XSD Schema
4.2.13. Tabular representation of OTA_HotelResNotifRQ¶
Unresolved directive in 042-guestrequests.adoc - include::tables/OTA_HotelResNotifRQ.adoc[] AlpineBits XSD Schema
4.2.14. Tabular representation of OTA_HotelResNotifRS¶
Unresolved directive in 042-guestrequests.adoc - include::tables/OTA_HotelResNotifRS.adoc[] AlpineBits XSD Schema