Deprecated API

The Legacy Pull Buyers API, our initial Buyers API launched in 2012, is now deprecated and should not be further developed. Instead, we introduced the Hotel-X Buyers API in 2017, which serves as the sole API for new Buyers looking to integrate and participate in our Marketplace.

Reservation Read

Reservation Read allows you to retrieve a specific booking with all its details using the lovators, booking codes. The returned fields for each booking in the list include: Locators, Hotel, TransactionStatus, Holder, Price etc.

caution

The amount of information returned might vary between Sellers.

ReservationRead Request

<soapenv:Envelope xmlns:soapenv = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns = "http://schemas.xmltravelgate.com/hub/2012/06" xmlns:wsse = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <soapenv:Header>
      <wsse:Security>
         <wsse:UsernameToken>
            <wsse:Username>username</wsse:Username>
            <wsse:Password>password</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <ns:ReservationRead>
         <ns:reservationReadRQ>
            <ns:timeoutMilliseconds>20000</ns:timeoutMilliseconds>
            <ns:version>1</ns:version>
            <ns:providerRQ>
               <ns:code>suppliercode</ns:code>
               <ns:id>1</ns:id>
               <ns:rqXML>
                  <ReservationReadRQ xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema">
                      <timeoutMilliseconds>19700</timeoutMilliseconds>
                     <source>
                        <languageCode>en</languageCode>
                     </source>
                     <filterAuditData>
                        <registerTransactions>true</registerTransactions>
                     </filterAuditData>
                     <Configuration>
                        <User>user</User>
                        <Password>password</Password>
                        <UrlAvail>www.supplier.com/avail</UrlAvail>
                        <UrlReservation>www.supplier.com/reservation</UrlReservation>
                        <UrlValuation>www.supplier.com/valuation</UrlValuation>
                        <UrlGeneric>www.supplier.com/generic</UrlGeneric>
                        <Parameters>
                           <Parameter key = "UrlListHotels" value = "http://www.supplier.com/ListHotels"></Parameter>
                           <Parameter key = "Access" value = "22334"></Parameter>
                        </Parameters>
                     </Configuration>
                     <Locators>
                        <Client>XXXXXXX</Client>
                        <Provider>XXXXXXX</Provider>
                        <Property>XXXXXXX</Property>
                     </Locators>
                     <Currency>EUR</Currency>
                     <StartDate>28/01/2014</StartDate>
                     <EndDate>29/01/2014</EndDate>
                     <CreationDate>17/01/2014</CreationDate>
                     <HotelCode>AAA</HotelCode>
                     <Holder title = "Miss" name = "Test11" surname = "TestAp11"/>
                  </ReservationReadRQ>
               </ns:rqXML>
            </ns:providerRQ>
         </ns:reservationReadRQ>
      </ns:ReservationRead>
   </soapenv:Body>
</soapenv:Envelope>

Request Data Breakdown

info

Check the values you need to add in the header and common elements.

Element	Rel	Type	Description
ReservationReadRQ	1		Root node.
ReservationReadRQ/Locators	1		Information about the locators (it is mandatory to indicate either client or supplier's locator).
Locators/Client	0..1	String	Client locator.
Locators/Provider	0..1	String	Supplier locator.
Locators/Property	0..1	String	Property locator (see MetaData method in order to verify if the supplier implements it).
ReservationReadRQ/Currency	1	String	Currency code.
ReservationReadRQ/StartDate	0..1	String	Start date of booking.
ReservationReadRQ/EndDate	0..1	String	End date of booking.
ReservationReadRQ/CreationDate	0..1	String	Creation date of booking.
ReservationReadRQ/HotelCode	1	String	Hotel code.
ReservationReadRQ/Holder	0..1		Holder of the booking.
@title	1	String	Holder’s title. Possible values: Mr, Mrs, Miss, Ms
@name	1	String	Holder's name.
@surname	1	String	Holder's surname.

ReservationRead Response

After each request, the Seller will process the data and provide you with a response. Upon receiving a ReservationRead request, the Seller will send you a corresponding ReservatonRead response.

The response options include either success or an error. In the event of success, you will receive all the details of the specific booking that you have requested.

Success

<ReservationReadRS>
   <Locators>
      <Client>2578478</Client>
      <Provider>10TTT31</Provider>
      <Property>HCN8273</Property>
   </Locators>
   <Hotel>
      <Name>LEO</Name>
      <Code>10</Code>
      <CreationDate>17/12/2015</CreationDate>
      <StartDate>28/01/2016</StartDate>
      <EndDate>29/01/2016</EndDate>
      <Holder name = "name" surname = "surname"/>
      <Price currency = "EUR" amount = "36.20" binding = "false" commission = "-1" minimumSellingPrice="-1"/>
      <Rooms>
         <Room id = "4582" roomCandidateRefId = "1" description = "Standard.."/>
      </Rooms>
      <CancelPenalties nonRefundable = "false">
         <CancelPenalty>
            <HoursBefore>120</HoursBefore>
            <Deadline>2016-07-01T05:00:00Z</Deadline>
            <CalculatedDeadline>false</CalculatedDeadline>
            <Penalty type = "Importe" paymentType = "MerchantPay" currency = "EUR">72.40</Penalty>
         </CancelPenalty>
      </CancelPenalties>
   </Hotel>
   <TransactionStatus>
      <ComunicationStatus>OK</ComunicationStatus>
      <RSStatus>EXISTE</RSStatus>
      <ResStatus>OK</ResStatus>
   </TransactionStatus>
</ReservationReadRS>

Success Response Data Breakdown

Element

Number

Type

Description

ReservationReadRS

Root node.

ReservationReadRS/Locators

Information about the locators.

Locators/Client

0..1

String

Client locator.

Locators/Provider

0..1

String

Supplier locator.

Locators/Property

0..1

String

Property locator (see MetaData method in order to verify if the supplier implements it).

ReservationReadRS/Hotel

0..1

Hotel reservation.

Hotel/Code

0..1

String

Hotel Code.

Hotel/Name

0..1

String

Hotel Name.

Hotel/City

0..1

String

Hotel city.

Hotel/CreationDate

0..1

String

Date of booking.

Hotel/StartDate

0..1

String

Check-in date.

Hotel/EndDate

0..1

String

Check out date.

Hotel/MealPlanCode

0..1

String

Booking Mealplan code.

Hotel/Holder

0..1

Reservation Holder .

@name

String

Holder name.

@surname

String

Holder surname.

Hotel/Price

Price of the reservation.

@currency

String

Currency code (Our system uses a standard ISO - 3 for all suppliers).

@amount

Decimal

Total amount for the booking.

@binding

Boolean

If binding is set as true, then the client can’t sell the product for a lower price that the one set by the supplier. If it set as as false, the client can sell the product for a lower price.

@commission

Decimal

Commission Scenarios

Commission	Description
0	The price returned is net.
-1	The supplier has not supplied the sale price nor the commission. This information is in the commercial contract with the supplier.
Greater than 0	X = % of the commission applied to the amount.

@minimumSellingPrice

Decimal

Indicates the minimum selling price it can be sold (determined by the Seller). If is specified (different than "-1"), that field takes preference to amount.

Minimum Selling Price Scenarios

Minimum Selling Price	Description
0	No minimum selling price is provided.
-1	We have no information about MSP from the Seller.
Greater than 0	The lowest possible amount that can be sold commercially.

Hotel/Rooms

0..1

List of rooms reserved

Rooms/Room

1..n

Details of room reserved.

@id

0..1

String

Identifier of the room.

@roomCandidateRefId

0..1

Integer

Identifier of room candidate.

@code

0..1

String

Room code.

@description

0..1

String

Room description.

Hotel/RoomCandidates

0..1

Rooms requested at the time of booking.

RoomCandidates/RoomCandidate

1..n

Room required.

@id

0..1

Integer

Id of the requested room (starting at 1).

RoomCandidate/Paxes

1..n

Pax required.

Paxes/Pax

1..n

Pax required.

@age

0..1

Integer

Passenger age on the day of check-in.

@id

0..1

Integer

Id of the requested room (starting at 1).

Hotel/CancelPenalties

0..1

Information of cancellation policies.

@nonRefundable

Boolean

Indicate if this option is nonRefundable (true or false).

CancelPenalties/CancelPenalty

0..n

Listing of cancellation penalties.

CancelPenalty/HoursBefore

String

Number of hours prior to arrival day in which this Cancellation policy applies.

CancelPenalty/Deadline

String

Date on UTC Standard TimeZone in which this Cancellation policy applies (ISO 8601 e.g: 2016-07-01T05:00:00Z)

CancelPenalty/CalculatedDeadline

Boolean

Indicate if the Deadline is returned by the supplier or it's been calculated by Travelgate.If true, the deadline has been converted to UTC-0 by Travelgate. If False, the supplier returns the deadline on UTC-0, so no calculation is needed.

CancelPenalty/Penalty

Contains the value to be applied in net price.

@type

String

Types of penalties

Penalty	Description
Noches	Indicates the number of nights to be penalized.
Porcentaje	Indicates the percentage to pay based on the option price.
Importe	Indicates the exact amount payable.

@paymentType

String

Indicates payment type.

@currency

String

Currency code (Our system uses a standard ISO - 3 for all suppliers).

Hotel/Remarks

0..1

String

Remarks.

ReservationReadRS/TransactionStatus

Status.

TransactionStatus/ComunicationStatus

String

Status communication (OFFLINE, OK and KO).

TransactionStatus/RSStatus

String

Response Status

Status	Description
DESCONOCIDO	Unknown
EXISTE	Exists
EXISTECANCELADA	exists but it's cancelled
NO_EXISTE	Does not exist

TransactionStatus/ResStatus

String

Reservation Status

Status Code	Description
OK	The reservation was completed with no problems.
RQ	The reservation was completed but the product is still not available, so the reservation goes into a waiting list (Request).
CN	The reservation was completed but due to a supplier error or a timeout the system will immediately cancel the reservation to prevent further possible errors.
UN	The reservation was completed but due to a supplier error or a timeout, the reservation status is unknown. It is the client’s responsibility to check if the booking is OK.

Error

<ReservationReadRS>
   <operationImplemented>true</operationImplemented>
   <applicationError>
      <code/>
      <type>105</type>
      <description>Communication Error.</description>
      <httpStatusCode>0</httpStatusCode>
   </applicationError>
</ReservationReadRS>

Error types that will be included in the response in the event of an error

Error Type	Error Description	Comments
101	System Exception.	Exception not controlled or not classified as general exception.
102	Provider Error.	Seller returns a particular code/description for an error, which is then transmitted to you in our response.
103	Too many requests to the supplier.	Your account has surpassed the agreed-upon request limit with the Seller.
104	Connection Timeout With Provider.	The Seller's response time has exceeded the timeout set in the Buyer's request.
105	Communication Error.	The connection to the Seller has been refused (we haven't been able to connect to their system).
105	Payload too high.	The size of the response by the Seller surpasses the size limitation established on our side for optimal performance (20000 options or 15MB).
204	No results found.	Seller does not return any results for the specific availability criteria set in the Buyer's request (e.g. hotel, dates, market, etc.).
205	Room Candidate Not Supported.	The number of room candidates in your request exceeds the maximum set by the Seller.
206	Dates Not Supported.	Your availability request does not align with the Seller's date specifications.
207	Request XML not accepted by Supplier.	Your availability request does not align with the Seller's specifications.
301	Option Not Found In Valuation.	Seller fails to return the option previously chosen by the Buyer in Search response (the option is no longer available). This error can be encountered in Quote response and Book response (whenever the integration requires an additional Quote to the Seller).
302	Hotel not found.	Our system is unable to locate the hotel you requested in your Hotels (DescriptiveInfo) method
303	Booking not confirmed.	Seller hasn't been able to confirm a booking for some reason (is not very common and might be returned in reservation response).

ReservationRead Request​

Request Data Breakdown​

ReservationRead Response​

Success​

Success Response Data Breakdown​

Error​

ReservationRead Request

Request Data Breakdown

ReservationRead Response

Success

Success Response Data Breakdown

Error