Retrieve Reservations
The connected PMS should retrieve reservations, modifications and cancellations from Effective Tours using the OTA_ReadRQ message.Effective Tours API will respond with aOTA_ResRetrieveRS that contain the reservations, modifications or cancellations that meet the request criteria in the read request.
The integrated PMS MUST return the reduced ‘Availability’ (
BookingLimit) value via the ‘Inventory API’ immediately after a reservation has been delivered. It is expected that the integrated PMS will pass back ‘Availability’ changes (reduction or replenishment) once a reservation, modification or cancellation message has been processed to confirm availability.
OTA_ReadRQ
The message below will return all undelivered reservations, modifications and cancellations for the hotel with HotelCode ABC
Request all undelivered for a hotel
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:30:47+08:00" EchoToken="echo-abc123">
<POS>
<Source>
<RequestorID Type="22" ID="PMS1"/>
</Source>
</POS>
<ReadRequests>
<HotelReadRequest HotelCode="ABC">
<SelectionCriteria SelectionType="Undelivered"/>
</HotelReadRequest>
</ReadRequests>
</OTA_ReadRQ>
The message below will return all undelivered new reservation for the hotel with HotelCode ABC
Request undelivered reservations
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:30:47+08:00" EchoToken="echo-abc123">
<POS>
<Source>
<RequestorID Type="22" ID="PMS1"/>
</Source>
</POS>
<ReadRequests>
<HotelReadRequest HotelCode="ABC">
<SelectionCriteria SelectionType="Undelivered" ResStatus="Book"/>
</HotelReadRequest>
</ReadRequests>
</OTA_ReadRQ>
The message below will return all undelivered cancellations for the hotel with HotelCode ABC
Request undelivered cancellations
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:30:47+08:00" EchoToken="echo-abc123">
<POS>
<Source>
<RequestorID Type="22" ID="PMS1"/>
</Source>
</POS>
<ReadRequests>
<HotelReadRequest HotelCode="ABC">
<SelectionCriteria SelectionType="Undelivered" ResStatus="Cancel"/>
</HotelReadRequest>
</ReadRequests>
</OTA_ReadRQ>
The message below will return all undelivered modifications for the hotel with HotelCode ABC
Request undelivered modifications
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:30:47+08:00" EchoToken="echo-abc123">
<POS>
<Source>
<RequestorID Type="22" ID="PMS1"/>
</Source>
</POS>
<ReadRequests>
<HotelReadRequest HotelCode="ABC">
<SelectionCriteria SelectionType="Undelivered" ResStatus="Modify"/>
</HotelReadRequest>
</ReadRequests>
</OTA_ReadRQ>
OTA_ReadRQ Specification
| Element | Number | Description |
|---|---|---|
| OTA_ReadRQ | 1 | Root element |
| @Version | 1 | Current Version 1.0 |
| @EchoToken | 1 | Globally unique identifier for the request, value will be returned as an EchoToken in the response. |
| @TimeStamp | 1 | Time of the transaction in xml schema dateTime format |
| OTA_ReadRQ / POS / Source / RequestorID | 1 | This identifies the system which is sending the reservation. This element must appear in the first Source element. |
| @Type | 1 | Fixed at 22 (ESRP) |
| @ID | 1 | The ID used will be agreed by the trading partners and remain the same throughout the messages. |
| OTA_ReadRQ / ReadRequests | 1 | |
| ReadRequests / HotelReadRequest | 1 | |
| @HotelCode | 0..1 | Hotel code as recognised by pmsXchange. If omitted all reservations for the PMS will be returned.Note: This attribute is only optional for central property management systems. It is mandatory for on-site systems. |
| HotelReadRequest / SelectionCriteria | 1 | |
| @SelectionType | 1 | Must be “Undelivered” |
| @ResStatus | 0..1 | Allowed values are “Book”, “Modify” or “Cancel”. If omitted new, modified and cancelled reservations will be returned. |
OTA_ResRetrieveRS
This message is returned by Effective Tours API in response to the OTA_ReadRQ. It’s primary payload is a list of HotelReservations which meet the request criteria in the OTA_ReadRQ.
Reservations that meet the request criteria are returned
Effective Tours API is channeling reservations from multiple different booking sources. The OTA_ResRetrieveRS Specification below has a number listed next to the node name to indicate if the node is mandatory or not. The OTA_ResRetrieveRS spec below is not designed to appear exactly in the order presented below. Coding to Effective Tours API should be flexible and allow for order variations to nodes/elements.
- The
<Success/>element indicates a successful response - In this example 2 new reservations are returned. As covered in Retrieve & Confirm Use Cases documents, the Effective Tours API reservation identifiers are “WTF-001” and “HTL-002” and the message ids for these reservations are “1243132” and “1243133”.
<tns:OTA_ResRetrieveRS Version="1.0" TimeStamp="2005-08-01T09:32:47+0000" EchoToken="echo-abc123">
<tns:Success></tns:Success>
<tns:ReservationsList>
<tns:HotelReservation CreateDateTime="2007-12-09T08:51:45+00:00" ResStatus="Book">
<tns:UniqueID Type="14" ID="WTF-001"/>
<tns:UniqueID Type="16" ID="ETR-442570-1565094220-237891" ID_Context="MESSAGE_UNIQUE_ID"/>
<!-- HOTEL RESERVATION DETAILS OMITTED -->
</tns:HotelReservation>
<tns:HotelReservation CreateDateTime="2007-12-09T08:51:45+00:00" ResStatus="Book">
<tns:UniqueID Type="14" ID="HTL-002"/>
<tns:UniqueID Type="16" ID="ETR-441670-1565160285-2102652" ID_Context="MESSAGE_UNIQUE_ID"/>
<!-- HOTEL RESERVATION DETAILS OMITTED -->
</tns:HotelReservation>
</tns:ReservationsList>
</tns:OTA_ResRetrieveRS>
No reservations are found that meet the request criteria
- The presence of the
<Success/>element indicates successful processing but the lack of theReservationsListelement shows no reservations were available.
<tns:OTA_ResRetrieveRS Version="1.0" TimeStamp="2005-08-01T09:31:00+0000" EchoToken="echo-abc123">
<tns:Success></tns:Success>
</tns:OTA_ResRetreiveRS>
An error occurred processing the request
- The presence of the
<Errors/>element indicates an error in business logic occurred.
<tns:OTA_ResRetrieveRS Version="1.0" TimeStamp="2005-08-01T09:31:00+08:00" EchoToken="echo-abc123">
<tns:Errors>
<tns:Error Type="3" Code="392">Invalid Hotel Code</Error>
</tns:Errors>
</tns:OTA_ResRetreiveRS>
OTA_ResRetrieveRS Specification
The main payload of the OTA_ResRetrieveRS message is a list of HotelReservation elements. The content will vary because Effective Tours API is delivering reservations from many different upstream sources (Booking Channels), many of which have vastly different reservation formats and data structures.
In general, the following can be said about HotelReservations:
- A
HotelReservationrepresents a single reservation made with an upstream system. - A
HotelReservationcan have one or moreRoomStays, one for each room type booked. - A
RoomStayrepresents a stay in one room type over a continuous timespan, non-continuous timespan stays (split stays) will result in multipleRoomStays. - A
HotelReservationcan have zero, one or manyResGuestslinked to either theRoomStaythe guest stay in or the reservation.
Elements and attributes marked with Number=1 or more are mandatory and will always be sent. 0..n means that the element or attribute is optional.
| Element | Number | Description |
|---|---|---|
| OTA_ResRetrieveRS | 1 | Root element |
| @Version | 1 | Current Version 1.0 |
| @EchoToken | 1 | Globally unique identifier for the request, value will be returned as an EchoToken in the response. |
| @TimeStamp | 1 | Time of the transaction in xml schema dateTime format |
| OTA_ResRetrieveRS / Success | 0..1 | Should only be present if the request processed successfully. The Errors node will not be present if the Success node is present. |
| OTA_ResRetrieveRS / Errors | 0..1 | Contains a list of errors if the request failed to process. |
| Errors / Error | 1..n | Should be at least one node if there is an Errors Node. |
| @Type | 1 | Mandatory if Error present. Any type from the OTA code table for ‘Error Warning Type (EWT)’ can be used. In particular, the following types are used |
| 3: Biz rule (The business rules for the request message were not met) | ||
| 4: Authentication error (If username and password are not authenticated) | ||
| 6: Authorization error (If authenticated username is not authorized to alter hotel data) | ||
| 10: Required field missing (If xml does not meet the schema, i.e missing request fields or invalid data types.) | ||
| @Code | 0..1 | Any code from the OTA code table for ‘Error Codes (ERR)’ can be used. |
| OTA_ResRetrieveRS / ReservationsList | 0..1 | ReservationList is only present if there are HotelReservation elements. |
| ReservationsList / HotelReservation | 1..n | At least one reservation element if ReservationList exists. |
HotelReservationType
| Element | Number | Description |
|---|---|---|
| @CreateDateTime | 1 | This is the date when the reservation was first made. Mandatory if ResStatus is “Book”. |
| @LastModifyDateTime | 0..1 | This indicates the last date and time when the reservation was last modified. Mandatory if ResStatus is “Modify” or “Cancel”. |
| @ResStatus | 1 | Status is “Book”, “Modify” or “Cancel” |
| HotelReservation / UniqueID | 1..2 | The reservation reference in Effective Tours. The first UniqueID element will contain the unique identifier for the entire reservation. This identifier will identify the reservation through any subsequent modifications or cancellations. The second UniqueID element with ID_Context=”MESSAGE_UNIQUE_ID” is the unique id for this message.This identifier should be used to confirm the message once processed |
| @Type | 1 | Value ’14’ is the unique id for the reservation in Effective Tours. Value ’16’ is the unique id for the message transferring the reservation. |
| @ID | 1 | Identifier of the reservation according to Effective Tours. Note, this is NOT the reservation id according to the upstream system. This is located in the HotelReservationID element.There is the possiblility that this ID will contain special characters such as ‘/’. |
| @ID_Context | 0..1 | Only present for the second UniqueID element and when present it will always be “MESSAGE_UNIQUE_ID” |
| HotelReservation / POS | 1 | Point of sale |
| POS / Source | 1..2 | Source of the reservation. A second POS / Source node can be present to define a secondary channel source. |
| Source / RequestorID | 0..1 | This identifies the system which is sending the reservation. This element will only appear in the first Source element. |
| @Type | 1 | Fixed at 22 (ESRP) |
| @ID | 1 | Value is always ‘EFFECTIVETOURS’ |
| Source / BookingChannel | 1 | Contains booking channel information |
| @Primary | 1 | Indicates the primary booking source |
| @Type | 1 | Always ‘7’ for ‘Internet’. |
| BookingChannel / CompanyName | 1 | Name of the Booking Channel.NOTE: This name is subject to change/variation by the Booking Channel. Please use the @Code attribute below to identify Booking Channels on incoming reservations. |
| @Code | 0..1 | Effective Tours’s code to identify the Booking Channel. See the [OTA Booking Channel Type (BCT)]table for reference. For secondary channels this code may not be available, when present it will be the secondary channel code as provided by the source channel. |
| HotelReservation / RoomStays / RoomStay | 0..n | One instance of RoomStay per room booked. A RoomStay element will always exist if ResStatus is “Book” or “Modify”. If ResStatus is “Cancel” it is possible that no RoomStay element exists. |
| Reservation / ResGuests / ResGuest | 0..n | One instance of ResGuest per reservation guests. This guest information is dependent on the sometimes limited information retrieved from the booking agents. ResGuests might not always be directly linkable to the RoomStays. Either all ResGuests are linked to RoomStays or none are. |
| HotelReservation / ResGlobalInfo | 1 | Contains general information about the Reservation |
ResGlobalInfo
| Element | Number | Description |
|---|---|---|
| HotelReservationIDs / HotelReservationID | 0..2 | Reference number/string or PNR as supplied by the Booking agent will be supplied here. If this reservation is linked under an itinerary, the itinerary id given by the source booking agent will be supplied in a second. |
| @ResID_Type | 1 | Will be sent as 14 or 26.14: OTA code for ‘Travel Agent PNR’. If this type is used the @ResID_Value will be the reservation identifier as provided by the source booking channel.26: OTA code for ‘Associated itinerary reservation’. If this type is used the @ResID_Value will be the itinerary identifier for one or more bookings in an itinerary as provided by the source booking channel. |
| @ResID_Value | 1 | Reference number/string supplied by the Booking agent. ResID_Value could potentially contain special characters such ‘/’. |
| Total | 0..1 | The total amount for the Reservation. Will add up to the sum of the RoomStay totals PLUS any additional fees sent by the BookingAgent.NOTE: It is possible that some OTAs do not provide any form of Rate information. As such we cannot guarantee Rate information will be provided. |
| Fees / Fee | 0..n | A container for added fees |
| @Type | 1 | Always ‘Inclusive’ |
| @Amount | 0..1 | Commission amount |
| Comments / Comment / Text | 0..n | Reservation comments |
| BasicPropertyInfo | 1 | Holds information about the Hotelier which this reservation is for. |
| @HotelCode | 1 | The code for the Hotel for which the booking was made. |
ResGuestType
| Element | Number | Description |
|---|---|---|
| @PrimaryIndicator | 0..1 | When true indicates this is the primary guest |
| ResGuest / Profiles | 1 | Contains the guest profile information |
RoomStayType
| Element | Number | Description |
|---|---|---|
| RoomStay / UniqueID | 1 | The room reference inside reservation. |
| @Type | 1 | Value ’17’ is the unique id for the room inside reservation in Effective Tours. |
| @ID | 1 | Identifier of the room inside reservation according to Effective Tours. |
| RoomStay / RoomTypes / RoomType | 0..1 | Container for room information, will be omitted if none was provided by the source channel. There will only ever be one RoomType per RoomStay |
| @RoomType | 0..1 | The name of the RoomType as provided by source channel |
| @RoomTypeCode | 0..1 | Room code, identifier for the room in Effective Tours |
| @ChannelRoomTypeCode | 0..1 | Room code, identifier for the room in the source channel |
| RoomType / RoomDescription / Text | 0..1 | A text description of the room |
| RoomStay / RatePlans | 0..1 | Container for room information, will be omitted if none was provided by the source channel |
| RatePlans / RatePlan | 0..n | Contains information for the Rate Plan(s) used for the RoomStay. |
| @RatePlanCode | 0..1 | Rate code, identifier for the rate plan in Effective Tours |
| @ChannelRatePlanCode | 0..1 | Rate code, identifier for the rate plan in the source channel |
| @RatePlanName | 0..1 | Name of the rate plan as provided the source channel |
| RatePlan / RateDescription / Text | 0..1 | A text description of the rate |
| RoomStay / RoomRates / RoomRate | 1..n | Multiple RoomRates per RoomStay. Multiple rates are listed under each RoomRate. This can happen when there is a single room booked but more than one rate plan applies during the stay. |
| RoomStay / GuestCounts / GuestCount | 0..3 | How many guests will be staying in the room. The count is split over potentially three GuestCount elements under GuestCounts, one for each type of guest: adult, child or infant. |
| @AgeQualifyingCode | 1 | Specifies the guest type for this GuestCount – uses OTA Spec for identifiers, will be one of three values 10 – Adult, 8 – Child, 7 – Infant |
| @Count | 1 | The actual count for this type of guest |
| RoomStay / RoomGuests | 0..1 | Contains guest names for this room |
| RoomGuests / RoomGuest | 0..n | Contains guest name |
| @Name | 1 | Full guest name |
| RoomStay / TimeSpan | 1 | Contains the timespan which this RoomStay covers |
| @Start | 1 | Check in date |
| @End | 1 | Check out date |
| RoomStay / Total | 0..1 | The total amount of the RoomStay. |
| RoomStay / Total / Taxes | 0..1 | The total tax amount for the RoomStay |
| @Amount | 0..1 | The tax amount |
| RoomStay / BasicPropertyInfo | 1 | Holds information about the Hotelier which this reservation is for.NOTE: If you are requesting reservations for all your hotels, using a single OTA_ReadRQ (centralised) we recommend using [ResGlobal / BasicPropertyInfo / @HotelCode] |
| @HotelCode | 1 | The code for the Hotel for which the booking was made. |
RoomRateType
| Element | Number | Description |
|---|---|---|
| RoomStay / RoomRates / RoomRate | 1..n | Multiple RoomRates per RoomStay. Multiple rates are listed under each RoomRate. This can happen when there is a single room booked but more than one rate plan applies during the stay. |
| @RoomTypeCode | 1 | The code of the room booked |
| @NumberOfUnits | 1 | Always 1. Each room will be listed in it’s own RoomStay element. |
| @RatePlanCode | 1 | This is the rate booked for the room type code listed in the RoomTypeCode attribute. |
| RoomRate / Rates | 0..1 | Container for the daily rate breakdown information, if none was provided by the channel this will be omitted |
| Rates / Rate | 1..n | The Rate element contains a timespan with daily rate information. The dates covered in the Rates will cover all the dates in the RoomStay/TimeSpan element. |
| @RateTimeUnit | 1 | Always “Day” |
| @EffectiveDate | 1 | The date of the rate in the form yyyy-MM-dd. |
| @Amount | 1 | The amount charged for the Rate. |
ProfilesType
| Element | Number | Description |
|---|---|---|
| Profiles / ProfileInfo | 1..n | Profile information |
| ProfileInfo / UniqueID | 0..n | Contains profile ids provided by the source channel. There can 0 to many identifiers passed through here |
| @Type | 1 | This will always be “16” to represent ‘Reference’ from the OTA code table Unique Id Type (UIT) |
| @ID | 1 | The reference identifier for the profile as provided by the source channel |
| @ID_Context | 1 | This can be one of 2 values: CHANNEL: To specify that this is a channel reference id. IATA: To specify that this is an IATA identifier for a travel agent |
| ProfileInfo / Profile | 1 | Contains the profile information |
| @ProfileType | 1 | The type of profile |
| Profile / Customer | ||
| Customer / PersonName | 0..1 | Profile name details. Always present for type Customer. |
| PersonName / GivenName | 0..1 | The name of the profile. Always present for type Customer. |
| PersonName / Surname | 0..1 | The last name of the profile. Always present for type Customer. |
| Customer / Telephone | 0..1 | Contact telephone number for the profile if available |
| @PhoneNumber | 0..1 | The actual number, will be there if the Telephone element is there |
| Customer / Email | 0..1 | The email address of the profile if available |
| Customer / Address | 0..1 | Address information for the profile if available |
| Address / AddressLine | 0..n | One or more address lines for the profile |
| Address / CityName | 0..1 | Customer city of residence if available |
| Address / PostalCode | 0..1 | Post code for profile if available |
| Address / CountryName | 0..1 | Country name |
TotalType
| Element | Number | Description |
|---|---|---|
| @CurrencyCode | 0..1 | The ISO currency code for the total |
| @AmountAfterTax | 0..1 | The total amount after tax |
| @AmountBeforeTax | 0..1 | The total amount before tax |
| Taxes | 0..1 | The total tax amount for the TotalType |
| @Amount | 0..1 | The total tax amount |
Last Updated: Nov 26, 2019
—- —- —- —- —- —- —- — — — — —
Back to API Documentation