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.

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.

samples/GuestRequests-OTA_ReadRQ.xml

<?xml version="1.0" encoding="UTF-8"?>

<OTA_ReadRQ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns="http://www.opentravel.org/OTA/2003/05"
            xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_ReadRQ.xsd"
            Version="1.001">

    <ReadRequests>
        <HotelReadRequest HotelCode="123" HotelName="Frangart Inn">
           <SelectionCriteria Start="2012-03-21T15:00:00+01:00"></SelectionCriteria>
       </HotelReadRequest>
    </ReadRequests>

</OTA_ReadRQ>

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.
Reserved - this is a booking reservation.
Modify - this is a booking modification.
Cancelled - this is a booking cancellation.

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:

samples/GuestRequests-OTA_ResRetrieveRS-reservation.xml - outer part

<?xml version="1.0" encoding="UTF-8"?>

<OTA_ResRetrieveRS
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.opentravel.org/OTA/2003/05"
        xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_ResRetrieveRS.xsd"
        Version="7.000">

    <Success/>

    <ReservationsList>

        <HotelReservation CreateDateTime="2012-03-21T15:00:00+01:00"
                          ResStatus="Reserved">

              <!-- Type 14 -> Reservation -->
            <UniqueID Type="14" ID="6b34fe24ac2ff810"/>

             <RoomStays>      <!-- stays, see below -->                    </RoomStays>

             <ResGuests>      <!-- customer data, see below -->            </ResGuests>

             <ResGlobalInfo>  <!-- additional booking data, see below -->  </ResGlobalInfo>

        </HotelReservation>

    </ReservationsList>

</OTA_ResRetrieveRS>

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 (all mandatory) discussed in the following paragraphs.

Part I: RoomStays.

The RoomStays element contains one or more RoomStay elements, each indicating a desired stay.

samples/GuestRequests-OTA_ResRetrieveRS-reservation.xml - RoomStay element

<RoomStays>

    <RoomStay>

        <RoomTypes>
            <RoomType RoomTypeCode="bigsuite" RoomClassificationCode="42"/>
     </RoomTypes>

        <RatePlans>
            <RatePlan RatePlanCode="123456-xyz">
                <Commission Percent="15"/>
                <!-- Code 1 -> All inclusive -->
                <MealsIncluded MealPlanIndicator="true" MealPlanCodes="1"/>
            </RatePlan>
        </RatePlans>

        <!-- 2 adults + 1 child + 1 child = 4 guests -->
        <GuestCounts>
            <!-- 2 adults -->
            <GuestCount Count="2"/>
            <!-- 1 child -->
            <GuestCount Count="1" Age="9"/>
            <!-- 1 child -->
            <GuestCount Count="1" Age="3"/>
        </GuestCounts>

        <TimeSpan Start="2012-01-01" End="2012-01-12"/>

        <Guarantee>
            <GuaranteesAccepted>
                <GuaranteeAccepted>
                    <PaymentCard CardCode="VI"
                                 ExpireDate="1216">
                        <CardHolderName>Otto Mustermann</CardHolderName>
                        <CardNumber>
                            <PlainText>4444333322221111</PlainText>
                        </CardNumber>
                    </PaymentCard>
                </GuaranteeAccepted>
            </GuaranteesAccepted>
        </Guarantee>

        <Total AmountAfterTax="299" CurrencyCode="EUR"/>

    </RoomStay>

</RoomStays>

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.

If multiple RoomStay elements are given, all the TimeSpan elements must have exactly the same values.

As a special case, however, only for quote requests (ResStatus is Requested), it is possible to add at most one optional RoomStay element that contains only the TimeSpan element. In this case, this last TimeSpan is allowed to have different values (as a matter of fact, they must be different) and it ought to be interpreted by the client as an alternative period with regard to the preceding RoomStay element(s).

Part II: ResGuests.

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).

samples/GuestRequests-OTA_ResRetrieveRS-reservation.xml - Customer element

<ResGuests>
    <ResGuest>
        <Profiles>
            <ProfileInfo>
                <Profile>

                    <Customer Gender="Male" BirthDate="1980-01-01" Language="de">

                        <PersonName>
                            <NamePrefix>Herr</NamePrefix>
                            <GivenName>Otto</GivenName>
                            <Surname>Mustermann</Surname>
                            <NameTitle>Dr</NameTitle>
                        </PersonName>

                        <!-- Code 1 -> Voice -->
                        <Telephone PhoneTechType="1" PhoneNumber="+4934567891"/>
                        <!-- Code 3 -> Fax -->
                        <Telephone PhoneTechType="3" PhoneNumber="+4934567892"/>
                        <!-- Code 5 -> Mobile -->
                        <Telephone PhoneTechType="5" PhoneNumber="+4934567893"/>

                        <Email Remark="newsletter:yes">otto.mustermann@example.com</Email>

                        <Address Remark="catalog:yes">

                            <AddressLine>Musterstraße 1</AddressLine>
                            <CityName>Musterstadt</CityName>
                            <PostalCode>1234</PostalCode>
                            <CountryName Code="DE"/>

                        </Address>

                    </Customer>

                </Profile>
            </ProfileInfo>
        </Profiles>
    </ResGuest>
</ResGuests>

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.

samples/GuestRequests-OTA_ResRetrieveRS-reservation.xml - ResGlobalInfo element

<ResGlobalInfo>
    <Comments>
        <Comment Name="included services">
            <ListItem ListItem="1" Language="de">Parkplatz</ListItem>
            <ListItem ListItem="2" Language="de">Schwimmbad</ListItem>
            <ListItem ListItem="3" Language="de">Skipass</ListItem>
        </Comment>

        <Comment Name="customer comment">
            <Text>
                Sind Hunde erlaubt?

                Mfg.
                Otto Mustermann.
            </Text>
        </Comment>
    </Comments>

    <SpecialRequests>
        <SpecialRequest Name="PETS">
            <Text TextFormat=”PlainText”>zwei Hunde</Text>
        </SpecialRequest>
    </SpecialRequests>

    <CancelPenalties>
        <CancelPenalty>
            <PenaltyDescription>
                <Text>
                Cancellation is handled by hotel.
                Penalty is 50%, if canceled within 3 days before show, 100% otherwise.
                </Text>
            </PenaltyDescription>
        </CancelPenalty>
    </CancelPenalties>

    <HotelReservationIDs>
        <!-- ResID_Type 13 -> Internet Broker -->
        <HotelReservationID ResID_Type="13"
                            ResID_Value="Slogan"
                            ResID_Source="www.example.com"
                            ResID_SourceContext="top banner" />
    </HotelReservationIDs>

    <Profiles>
        <ProfileInfo>
            <!-- ProfileType 4 -> Travel Agent -->
            <Profile ProfileType="4">
                <CompanyInfo>
                    <CompanyName Code="123" CodeContext="ABC">
                        ACME Travel Agency
                    </CompanyName>
                    <AddressInfo>
                        <AddressLine>Musterstraße 1</AddressLine>
                        <CityName>Flaneid</CityName>
                        <PostalCode>12345</PostalCode>
                        <CountryName Code="IT"/>
                    </AddressInfo>
                    <!-- Code 1 -> Voice -->
                    <TelephoneInfo PhoneTechType="1" PhoneNumber="+391234567890"/>
                    <Email>info@example.com</Email>
                </CompanyInfo>
            </Profile>
        </ProfileInfo>
    </Profiles>

    <BasicPropertyInfo HotelCode="123" HotelName="Frangart Inn"/>
</ResGlobalInfo>

The ResGlobalInfo element contains:

One Comment element (optional) with attribute Name set to included services containing 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 comment containing a single Text element freely filled out by the customer and fed through unchecked by the portal.
One SpecialRequest element (optional) with attribute Name set to PETS containing a single Text element (optional) with attribute TextFormat set to PlainText that states details regarding pets that will accompany the customer. Such SpecialRequest element without the Text sub-element means that it is known that the customer will not bring any pets for the stay (on the other hand, even an empty Text sub-element means that pets will be present but without further details). For this reason, the Text sub-element must not be used to explicitly communicate absence of pets (e.g. “no pets” or “none” must not be valid contents for the Text sub-element). The absence of the whole SpecialRequest element means that the information about potential presence of pets 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”.

SpecialRequest - PETS (example A)

<SpecialRequests>
    <SpecialRequest Name="PETS">
        <Text TextFormat=”PlainText”>two dogs</Text>
    </SpecialRequest>
</SpecialRequests>

Example B: the customer will surely bring pets but no further information is given.

SpecialRequest - PETS (example B)

<SpecialRequests>
    <SpecialRequest Name="PETS">
        <Text TextFormat=”PlainText”></Text>
    </SpecialRequest>
</SpecialRequests>

Example C: the customer will surely not have any pet with him.

SpecialRequest - PETS (example C)

<SpecialRequests>
    <SpecialRequest Name="PETS"></SpecialRequest>
</SpecialRequests>

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:

samples/GuestRequests-OTA_ResRetrieveRS-cancellation.xml

<?xml version="1.0" encoding="UTF-8"?>

<OTA_ResRetrieveRS
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.opentravel.org/OTA/2003/05"
        xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_ResRetrieveRS.xsd"
        Version="7.000">

    <Success/>

    <ReservationsList>

        <HotelReservation CreateDateTime="2012-03-21T15:00:00+01:00"
                          ResStatus="Cancelled">

              <!-- Type 15 -> Cancellation -->
            <UniqueID Type="15" ID="c24e8b15ca469388"/>

            <!-- the following are optional for cancellations: -->
            <!--
            <RoomStays>     ...  </RoomStays>
            <ResGuests>     ...  </ResGuests>
            <ResGlobalInfo> ...  </ResGlobalInfo>
            -->

        </HotelReservation>

    </ReservationsList>

</OTA_ResRetrieveRS>

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.

samples/GuestRequests-OTA_ReadRQ-ack.xml

<?xml version="1.0" encoding="UTF-8"?>

<OTA_NotifReportRQ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.opentravel.org/OTA/2003/05"
        xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_NotifReportRQ.xsd"
        Version="1.000">

    <Success/>

    <Warnings>
        <!-- refuse reservation with ID=f054bbd2f5ebab9 -->
        <Warning Type="3" Code="450" RecordID="f054bbd2f5ebab9">
            Unable to process reservation
        </Warning>
    </Warnings>

    <NotifDetails>
        <HotelNotifReport>
            <HotelReservations>

                <HotelReservation>
                    <!-- ACK reservation with ID="6b34fe24ac2ff810" -->
                    <UniqueID Type="14" ID="6b34fe24ac2ff810"/>
                </HotelReservation>

                <HotelReservation>
                    <!-- ACK cancellation with ID="c24e8b15ca469388" -->
                    <UniqueID Type="15" ID="c24e8b15ca469388"/>
                </HotelReservation>

                <HotelReservation>
                    <!-- ACK quote request with ID="1000000000000001" -->
                    <UniqueID Type="14" ID="1000000000000001"/>
                </HotelReservation>

            </HotelReservations>
        </HotelNotifReport>
    </NotifDetails>

</OTA_NotifReportRQ>

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
08:00	action = OTA_Read:GuestRequests; request = OTA_Read with SelectionCriteria Start today 00:00	OTA_ResRetrieveRS with UniqueID=1 (Reservation) and UniqueID=2 (Request)	the server answers with today’s two requests (1 and 2)
08:01	action = OTA_NotifReport:GuestRequests; request = OTA_NotifReportRQ with UniqueID=1	OTA_NotifReportRS Success	server knows the client got 1, it will not be sent again
09:00	action = OTA_Read:GuestRequests; request = OTA_Read	OTA_ResRetrieveRS with UniqueIDs 2 and 3 (Request)	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
10:00	action = OTA_Read:GuestRequests; request = OTA_Read	OTA_ResRetrieveRS with UniqueIDs 2 and 3 (Request)	same server response as at 09:00 because 2 and 3 were not ack’ed
10:01	action = OTA_NotifReport:GuestRequests; request = OTA_NotifReportRQ with UniqueID=2, 3	OTA_NotifReportRS Success	server now knows the client got all three
11:00	action = OTA_Read:GuestRequests; request = OTA_Read with SelectionCriteria Start today 00:00	OTA_ResRetrieveRS with UniqueIDs 1, 2 and 3 (Request)	the SelectionCriteria Start overrides the fact that all three guest requests had already been ack’ed, so the server sends all three again

time

client request

server response

comment