INTEGRATION XML API R2 Rev /06/2016

Transcription

1 Parityrate INTEGRATION XML API Date: Rev.: Page: 06/09/ /06/ / 15 INTEGRATION XML API R2 Rev /06/2016 1

2 Parityrate INTEGRATION XML API Date: Rev.: Page: 06/09/ /06/ / 15 Table of contents 1.Assumption 3 2.INTRODUCTION. 3 3.Functions. 4 4.Sample messages Useful things

3 3 1. Assumption Before proceeding with the integration it is important to understand what Parity Rate can do: What Parityrate can do? Parityrate sends Prices and Room Availability ( quantity ) to all channels a Hotel is connected to. What Parityrate can t do? Parityrate is not an online booking engine system : it doesn t store any kind of information such as reservation policies ( cancellation, modification etc.. ) Who is in scope of integration, who can develop Parityrate API? All channels having a booking system or an extranet having their own database and offering a calendar with room prices and room availability for each hotel connected to that channel. 2. INTRODUCTION The aim of this INTEGRATION XML API is to give the functions that a channel must implement in order to integrate its services with Parityrate Data exchange mechanism Parityrate uses standard XML/RPC to exchange xml messages. XML/RPC is a remote procedure call (RPC) protocol which uses XML to encode its calls and HTTP as a transport mechanism. An XML document that contains a method name and some arguments is sent to a Web server using HTTP POST. The server invokes the method with the specified arguments. Then it wraps up the return value of the method in another XML document, and sends that back to the client. That is: Parityrate send the channel an XML message encapsulated inside the body of a Http POST request. The content of the channel answers is an XML message as well. The channel must provide a unique url where Parityrate will send all the XML calls. This url is referred as the service_url 2.2. Request message structure and access credentials Every call must be enclosed in a Request element, must contain the access credentials inside the username and password attributes, and must be in the following format: </Request> 2.3. Response Message structure Following the basic response message structure is displayed:

4 Error Message In case of error the format is: <error message="authentication Failed - Wrong Password"/> It is mandatory that an error is raised every time a modify request goes wrong. 3. Functions 3.1. Configuration methods Parityrate can manage for each channel, hotel, rate type (ex standard, not refundable), room type (ex single room, double superior room) and day three different parameters: number of available rooms (we call it quantity), price and minimum stay. This implies that if in a certain channel it is possible to define, for a certain rate, different prices for a certain room (ex: double room with standard price and price for single use) in Parityrate a room for each price type will be configured. Mapping between channels and Parityrate rates and rooms is static and it must be performed at least once and anyway every time there s a configuration change inside the channel. For this purpose a set of configuration calls must be implemented by the channel 1. gethotels this method return the list of all hotels associated to an username/password. For each hotel in the list it provides an ID and a description. ID will be used by PR to identify the hotel in all other messages. Hotel element has the following attributes id : String -> hotel code to identify the hotel inside the channel description : String ->hotel name/ description Ex: <hotel id= 324 description= Hotel Parityrate Milano /> 2. getrates gives the list of rates defined for a selected hotel. If there are no rates, channel must return a response containing no rate element. The rate element has the following attributes: id : String -> rate code to identify the rate inside the channel

5 5 description : String ->rate description Ex: <rate id= std description= Standard rate /> 3. getrooms gives the list of rooms for a selected hotel. Each room is represented by a room element. This is a complex type element characterized by two attributes, id and description both required, and by other optional elements. The room element has the following attributes: id : String (required) -> room code to identify the room inside the channel description : String (required) ->room description and the following child elements parentroom : complex type (optional) -> must be returned if the room doesn t have a proper availability or price or minimum stay. roomrates : complex type (optional) -> contains the rate codes (roomrate elements) the room can be sold for.

6 6 parentroom element has the following attributes: parentroomid : String (required) -> room code assigned to the parent room inside the channel parentroomdescription : String (required) ->parent room description usepp : 0 or 1 (optional) -> must be set to 1 if room has the same price as the parent room usepq : 0 or 1 (optional) -> must be set to 1 if room has the same availability as the parent room usepm : 0 or 1 (optional) -> must be set to 1 if room has the same minimum stay as the parent room The couple parentroomid/parentroomdescription must have a value corresponding to a room id/description value present in the message roomrates element contains a sequence of roomrate elements roomrate element has the following attributes: rateid : String (required) -> rate code that identifys the rate inside the channel roomrateid : String (required) ->room rate id roomratedescription : String (required) ->room rate description Ex: <getrooms hotelid= 3284 > </Request> <room id= TWI description= Twin Room > <roomrates> <roomrate rateid= 1 roomrateid= 1 roomratedescription= Twin Room Standard Rate /> <roomrate rateid= 2 roomrateid= 1 roomratedescription= Twin Room Special Rate /> </roomrates> </room> <room id= DBL description= Doubel Room > <parentroom parentroomid= TWI parentroomdescription= Twin Room usepq= 1 usepm= 1 /> <roomrates> <roomrate rateid= 1 roomrateid= 2 roomratedescription= Double Room Standard Rate /> <roomrate rateid= 2 roomrateid= 2 roomratedescription= Double Room Special Rate /> </roomrates> </room> Remarks: In a getrooms response:

7 7 each room id/description must be unique; if the channel has no rates, room id must be unique because it is the code used in the modify message request to univocally identify the room the request refers to each room id/rateid/roomrateid must be unique; it will be used to univocally identify which room and rate we deal with in an availabilities view/modify request The combination room/parentroom and room/roomrate give Parityrate the availability to build the modify grid in order to manage data accordingly with the real need of the channel. Let s assume, for instance, that for a certain channel each room can have a price for the standard room occupancy (ex 2 beds for the double) and a price for an extrabed. In this case we are in presence of a room type with 2 kind of prices that is a single room code but two different prices. The corresponding data structure in Parityrate will have 2 room types, one for the standard occupancy and the other for the extrabed. The getrooms call we expect is looking, more or less, like the following: <room id= 1 description= Double Room > <roomrates> <roomrate rateid= 1 roomrateid= std roomratedescription= Double Room Standard Rate /> </roomrates> </room> <room id= 1 description= Extra Bed for Double Room > <parentroom parentroomid= 1 parentroomdescription= Double Room usepq= 1 usepm= 1 /> <roomrates> <roomrate rateid= 1 roomrateid= exb roomratedescription= Extra Bed Standard Rate for Double Room /> </roomrates> </room> Obviously will be the channel to choose the codes combination to use in order to guarantee the data consistency. A particular case is that of a channel that has no rates but give the availability to set up different prices for the same room type. For example, it is the case of a per occupancy pricing schema. In this case, since a room should be identified only by the id in every view/modify ParityRate XML message, a serious problem would rise. It would be not possible indeed to identify which occupancy a price refers to. To avoid such problems we suggest to define a fake standard rate and to use roomrateid and ParentRoom objects to identify room types and occupancy as shown in the example above View and modifications Using data retrieved using the above methods, it's possible then to view or modify rooms availabilities, prices and minimum stay per rate using the function calls view and modify. The availability is the basic object that is used to exchange information with this two functions. availability element has the following attributes: day : date (required) -> day the data refer to roomid : String (required) -> room the availability refers to rateid : String (optional) -> rate the availability refers to; it can be omitted if and only if channel uses no rates roomrateid : String (optional) -> rate the availability refers to; it can be omitted if and only if channel uses no rates currency : String (optional) -> in a view response it can be omitted if and only if room has a parent room and usepp is set to 1; can always be omitted in a modify request price : Double (optional) -> in a view response it can be omitted if and only if room has a parent room and usepp is set to 1; if omitted in a modify request original data must be left unchanged quantity : Integer (optional) -> in a view response it can be omitted if and only if room has a parent room and usepq is set to 1; if omitted in a modify request original data must be left unchanged

8 8 minimumstay: Integer (optional) -> in a view response it can be omitted if and only if room has a parent room and usepm is set to 1; if omitted in a modify request original data must be left unchanged status: String (optional) -> in a view response it can be omitted; it can assume following values: open, closed; if status = closed then the room roomid is not bookable for the rate rateid coa: 0 or 1 (optional) -> in a view response it can be omitted; if status = 1 then the room roomid is not bookable on checkin for the rate rateid cod: 0 or 1 (optional) -> in a view response it can be omitted; f status = 1 then the room roomid is not bookable on checkout for the rate rateid For each day the triple roomed/rateid/roomrateid must be unique ex: <availability day= roomid= 1 rateid= 1 roomrateid= 1 currency= EUR price= 120 quantity= 2 minimumstay= 1 status= open coa= 1 cod= 0 /> An availability represents the minimum block of information managed by our view and modification functions for a certain room and rate on a certain day. Availabilities must be daily, so one availability used in a certain day means a view or a modification on prices, room quantities or minimum stay in a fixed day. ParityRate don t have a specific management for free sale,but for convention assigns to the quantity value 99 the meaning of Free Sale availability (FS). Having this clear, the other calls are: 4. view gives back the list of availabilities read in a selected period 5. modify modify the rooms using the availabilities passed to the function call 3.3. Reservations The aim of this function is just to give the user a rapid glance on a list of reservations by check-in date. The request has the following form <!-- Please return all reservations for hotel with ID xx, with check-in date between start date and end date --> <reservations hotelid="xx" startdate=" " enddate=" "/> </Request> The response must return a list of reservation elements. reservation element has the following attributes: id : String (required) -> channel reservation code checkin : Date (required) ->check-in date checkout: Date (required) ->check-out date client: String (required) -> customer name rooms: Integer (required) -> number of booked rooms price: Double (required) -> total price status: String (required) -> reservation status status can assume following values:

9 9 CANCELLED="0" SUBMITTED="1" CONFIRMED="2" Ex: <reservation id= checkin= checkout= client= Mario Rossi rooms= 2 price= 120. status= 2 > 3.4. Download reservations Parityrate periodically retrieves reservations from the channels and stores the collected data in its own database. This process is used for several purposes like the generation of statistical reports, the automatic update of the rooms stock, to induce the application of revenue management rules and so on Parityrate supports 2 different methods to retrieve reservations from a channel. PULL METHOD Every 20 minutes ParityRate will perform a downloadreservations request for each hotel <downloadreservations hotelid="xx" dlm==" :00:00" /> </Request> This method is used to retrieve all reservations of a certain hotel, created, modified or cancelled since the dlm date. If dlm is omitted we expect to receive all the reservations created, modified or cancelled in the last seven days. The returned data will contain a list of reservationwd elements. PUSH METHOD When a reservation is created, modified or cancelled, the channel can PUSH the reservation to Parityrate by sending an HTTP Post request to a dedicated page in the Parityrate website. The url to call will contain the reservation id and the hotel id the reservation refers to. e.g..: The body of the post request will contain the XML message including a reservationwd If a channel implements the PUSH method, Parityrate will reduce the frequency of PULL requests to one every 2 hours. reservationwd (reservation with detail) element has the following attributes and child elements (many of the informations described below are not mandatory but the more data are collected the better the service for the channel clients) id String (required) -> the channel reservation code checkin Date (required) -> the check-in date checkout Date (required) -> the check-out date reservation_date DateTime (required) -> date and time when reservation was made (yyyy- MM-ddThh:mm:ss). If time is not available set as time 00:00:00 cancellation_date DateTime (optional) -> date and time when reservation was cancelled (yyyy-mm-ddthh:mm:ss). If time is not available set as time 00:00:00 firstname String (required) -> the first name of the customer that has completed this reservation

10 10 lastname String (required) -> the last name of the customer that has completed this reservation telephone String (optional) -> complete telephone number of the client. String (optional) -> address of the client. rooms Integer (required) -> the total number of rooms booked price Double (required) -> the total price of the reservation status String (required) -> the state of the reservation; it can assume the following values: CANCELLED="0" NEW="1" MODIFIED="2" paymenttype String (optional) -> code of the type of payment used by the client; it can assume the following values: 1 = by transfer 2 = by postal order 3 = by paypal 4 = by credit card offer String (optional) -> if there is any offer applied here the channel can report the description. cancancel String (optional) -> parameter which indicates that the hotelier can cancel the reservation; can assume following values: 1 true,0 false) cancelbydetail String (optional) -> parameter which indicates that the hotelier can cancel the details of the reservation; can assume following values: 1 true,0 false) notes String (optional) -> reservation notes adults Integer (required) -> number of adults hosted children Integer (optional) -> number of children hosted address String (optional) -> address of the client city String (optional) -> city of the client country Country (optional) -> country of the client. The channel must use the ISO 3166 Countries A2 currencycode String (optional) -> currency of the total price. The channel must use the ISO 4217 Currency Code List zipcode String (optional) -> zip code of the client address ccdata: tag used in case of payment by credit card which contains credit card details. It s Optional, and so are all his fields: cccode String (optional) -> Credit card's CVC Security Code ccnumber String (optional) -> Credit card number ccexpiredate String (optional) -> Expiration date. The formats accepted are MM/yy and MM/yyyy. ccholder String (optional) -> Holder of the credit card reservationdetail: contains details for every room reserved. id String (required) -> code of this reservationdetail. If the Channel doesn t use codes for the reservationdetail it must use the code of the room. currency String (required) ->currency of the price. The channel must use the ISO 4217 Currency Code List checkin Date (required) -> the check-in date for this room checkout Date (required) -> the check-out date for this room roomid String (required) ->it's the code of the room

11 11 rates_id String (optional) ->the code of the rate plan name String (required) -> it's the name of the room quantity Integer (required) ->it s the quantity reserved price Double (required) ->it s the total price for the reservation of this room. commission String (optional) ->amount of the commission taken by the channel on the price for this room children Integer (optional) -> number of children hosted in this room. childrenprice Double (optional) -> total price paid for the children hosted in this room. It must be included in the price field adults Integer (required) -> number of adults hosted in this room rates_id String (optional) -> portal rate applied to this room cancellation_policy String (optional) -> cancellation policy applied to this room dayprice :tag used to specify for every room for every day the price charged to the client.optional roomid String (required) -> it's the code of the room rates_id String (optional) -> the code of the rate plan detailid String (optional) -> the id of the reservation detail this element is referred to day Date (required) -> the day in which this price is charged price Double (required) -> it s the total price for the reservation of this room for this day childrenprice Double (optional) -> total price payed for the children hosted in this room for this day.it must be included in the price field. supplement : tag used to send informations (for every room) about supplements charged to the client for services he bought.optional roomid String (required) -> it's the code of the room to which this supplement applies rdetailid String (optional) ->the id of the reservation detail this element is referred to description String (required) -> description of this service type roomsquantity Integer (optional) -> it s the quantity reserved of this room Optional price Double (required) -> price of this supplement number Integer (required) -> quantity of this service bought by the client (=0 if it can be quantified) type Integer (optional) -> type of this supplement ; it can assume the following values: 0= daily 1= by person 2= by number 3= daily and by person Persons Integer (optional) -> number of persons for which this service is bought. Optional guest :tag used to specify the guests information. Optional roomid :String (optional) -> it's the code of the room detailid : String (optional) -> it's the id of the reservationdatail the guest is referred to title : String (optional) -> the title of the guest firstname : String (required) -> the first name of the guest secondname : String (required) -> the second name of the guest String (optional) -> of the guest phone : String (optional) -> phone of the guest address : String (optional) -> address of the guest zipcode : String (optional) -> zip code of the guest city : String (optional) -> city of the guest

12 12 country : String (optional) -> country of the guest. The channel must use the ISO 3166 Countries A Restrictions As a general rule we don t accept ids containing the following characters:,. : ; & % * + - / \ [ ]? ^ $ < > <SPACE> <TAB> <NL> <CR> while in the description fields we don t accept the following characters:. * + - < > <TAB> <NL> <CR> 4. Sample messages Following all the API functions are documented: 4.1. gethotels Request: <gethotels/> </ Request> Response: <hotel id= 1 description= Hotel Alpha /> <hotel id= 2 description= Hotel Beta /> 4.2. getrates Request: <getrates hotelid= 1 /> </ Request> Response: <rate id= 0 description= Standard Rate /> <rate id= 1 description= Standard Rate Non refundable /> <rate id= 2 description= Special price /> The rate element can be absent.

13 getrooms Request: <getrooms hotelid= 1 /> </ Request> Response: <room roomid=.. pricecode=.. description=.. parentroomid=.. upp=.. upq=.. upm=.. > <roomrate rateid=.. roomrateid=.. roomratedescription=.. /> <roomrate rateid=.. roomrateid=.. roomratedescription=.. /> </room> <room roomid=.. pricecode=.. description=.. parentroomid=.. upp=.. upq=.. upm=.. > <roomrate rateid=.. roomrateid=.. roomratedescription=.. /> <roomrate rateid=.. roomrateid=.. roomratedescription=.. /> </room> 4.4. view Request: <view hotelid=.. rateid=.. startdate= yyyy-mm-dd enddate= yyyy-mm-dd /> </ Request> Response: <availability day= yyyy-mm-dd rateid=.. roomid=.. roomrateid=.. currency=.. quantity=.. minimumstay=.. price=.. /> modify Request: <modify hotelid=.. rateid=.. startdate= yyyy-mm-dd enddate= yyyy-mm-dd > <availability day= yyyy-mm-dd roomid=.. rateid=.. roomrateid=.. currency=.. quantity=.. minimumstay=.. price=.. >.

14 14 </availability> </modify> </ Request> Response: <ok/> 4.6. reservations Request: <reservations hotelid=.. startdate= yyyy-mm-dd enddate= yyyy-mm-dd /> </ Request> Response: <reservation id=.. checkin= yyyy-mm-dd checkout= yyyy-mm-dd client=.. rooms=.. price=.. status=.. > States can have the following values: CANCELLED="0" SUBMITTED="1" CONFIRMED="2" 4.7. download reservations Request: < downloadreservations hotelid=.. /> </ Request> Response: <reservationwd id="" checkin=" yyyy-mm-dd" checkout=" yyyy-mm-dd " client="" telephone="" ="" rooms="" price="" reservation_date=" yyyy-mm-dd HH:MM:ss" status="" paymenttype="" offer="" cancancel="" cancelbydetail="" notes="" persons="" children="" address="" city="" country=""

15 15 currencycode=" zipcode= > <ccdata cccode= ccnumber="" ccexpiredate="" ccholder="" /> <reservationdetail id="" currency="" checkin=" yyyy-mm-dd " checkout=" yyyy-mm-dd " roomid="" name="" quantity="" price="" commission="" children="" childrenprice="" numberofguests= rates_id= /> <reservationdetail/> <dayprice roomid="" day="yyyy-mm-dd" price="" childrenprice="" /> <supplement roomid="" description="" roomsquantity="" price="" type="" number="" persons="" /> </reservationwd> 5. Useful things Following pages can be used to exchange XML messages using standard XML/RPC Parityrate xml schema can be retrieved from following URL