The following services for working with orders are provided in the gate:
- Getting information about booked order,
- Getting the list of booked orders based on specified criteria,
- Preparation of order in xml format,
- Calculation of the final price of the order,
- Order booking,
- Working with preliminary booking orders.
‘aid’ parameter should be added to all service requests.
Order structure http://www.tez-tour.com/article.html?id=7015627
Viewing Order
Request for viewing the order: http://xml.tez-tour.com/xmlgate/order/view?orderId=${orderId}
The system’s reply will contain the order contents in xml form.
Orders List
Request for getting the list of orders based on specified criteria. Request: http://xml.tez-tour.com/xmlgate/order/list?param=
Request needs to contain at least one criterion by which the list will be formed:
creationDateFrom – order creation date, search interval start. If not specified, it is assumed that orders created starting today are requested.
creationDateTo – order creation date, search interval end. If not specified, the orders are searched without limitation on this parameter.
startDateFrom – order validity start date, interval start. As a rule, “order validity start” is the first day of accommodation of tourists. If it is not specified – the search is not limited by this parameter.
startDateTo - order validity start date, interval end. If it is not specified – the search is not limited by this parameter.
country – order’s country. If it is not specified – the search is not limited by this parameter.
authorized – if the parameter value is ‘true’ and user has no ‘infoRestricted’ role, all orders of the agency are displayed in the list.
updatedDateFrom – last edit time for the order. Specified in dd.mm.yyyy hh:mm format. If, at that, creationDateFrom is not used in the request, only orders for the last day are searched starting from 00:00 of the previous day. If creationDateFrom is used in the request parameters, the orders are searched based on specified creation date. If updatedDateFrom parameter is not specified in the request – the search is not limited by this parameter.
The request results have a restriction – time interval for which the orders are returned – 365 days from the tour end date.
Request example: http://xml.tez-tour.com/xmlgate/order/list?creationDateFrom=10.09.2012&aid=11E15C78540155474CA61718D11DF0A8C3C3C71E914
Preparation of XML Order
The request returns an xml file of the booking template: http://xml.tez-tour.com/xmlgate/order/orderFromOfferId.jsp?priceOfferId=12016492&resTariffs=15976793424&flyTariffs=13656040&tariffDepCityId=345&firstTransferType=3635&lastTransferType=3635&resortArrivalRegionId=487545&resortDepartureRegionId=487545
The request uses the following parameters, which values are available in the response of Tour Search service (/getResult):
- resTariffs - residence id
- flyTariffs – flight id, in case of several flights should be separated with comma, flyTariffs=123123,12333
- priceOfferId - price offer id
- tariffDepCityId – departure city id
- firstTransferType - id of transfer type to the hotel
- lastTransferType - id of transfer type from the hotel
- resortArrivalRegionId - resort arrival region id
- resortDepartureRegionId - resort departure region id
- firstTransferVehicleId - выбранный вариант машины из аэропорта в отель (если указан в ссылке на создание в онлайн кабинет)
- lastTransferVehicleId - выбранный вариант машины из отеля в аэропорт (если указан в ссылке на создание в онлайн кабинет)
- spoKindId - tour type id (1: full package, 2: accomodation + transfer, 3: accomodation, 6: accomodation + flight)
- hotelResourceId - additional accomodation id, should be used if tour includes the second accomodation
- promo - promo offer (1 - yes, 0 - no), optional parameter, default value is 1
Transfer types:
- 3635 – G (group transfer),
- 3636 – I (individual/personal transfer),
- 2996 - VIP transfer
Order Calculation
Before booking the order you can make a preliminary calculation of its price. It is necessary to pass the filled order XML (the same xml that is used for booking) in the request body. In the header of http-request it is necessary to pass the value of application/xml for ‘Content-type’ field. http://xml.tez-tour.com/xmlgate/order/calculate The calculation is available for both tour packages and non-package tours. The price is specified in the currency of the order.
If the order has been calculated, an xml is returned:
<CalcOrderResult>
<price>2000.0</price>
<extraPrice>200.0</extraPrice>
<percent>10.0</percent>
<percentWithoutFlex>9.0</percentWithoutFlex>
<priceOfferId>444</priceOfferId>
<priceOffer>SPO 4</priceOffer>
<flexCommissionId>1</flexCommissionId>
</CalcOrderResult>
If the order has not been calculated, there will be no tag with price value. For example, the following reply can be received for the order:
<?xml version="1.0"?>
<CalcOrderResult>
<extraPrice>0.0</extraPrice>
<percent>0.0</percent>
</CalcOrderResult>
This means that the order was not calculated. There are several reasons for such behavior:
1. Order’s xml was prepared incorrectly. Make sure that the tourists’ birthdays are correct. The type of tourist (adult, child) is determined by the birthday and this affects the final price of the tour. Make sure that all tourists in the order are linked to the order services. If any of the services is not linked to the tourist, it is impossible to calculate the order.
2. There is no price for some service in the order.
Order example:
<order>
<OrderType>
<type>Touristic</type>
</OrderType>
<Country>
<id>12695</id>
</Country>
<Summary>
<spoId>10181276</spoId>
<currency>5561</currency>
<containerId>43169918850</containerId>
</Summary>
<Tourist>
<touristId>1</touristId>
<surname>TEST</surname>
<name>TEST</name>
<gender>2688</gender>
<birthday>12.12.1980</birthday>
<nationality>1102</nationality>
<passport_issue_date>11.01.2010</passport_issue_date>
<passport_expiration_date>11.01.2020</passport_expiration_date>
<genderName>MR.</genderName>
</Tourist>
<Tourist>
<touristId>2</touristId>
<surname>TEST</surname>
<name>TEST</name>
<gender>2688</gender>
<birthday>14.01.1978</birthday>
<nationality>1102</nationality>
<passport_issue_date>23.07.2012</passport_issue_date>
<passport_expiration_date>23.07.2022</passport_expiration_date>
<genderName>MR.</genderName>
</Tourist>
<Residence>
<serviceId>1</serviceId>
<checkIn>26.02.2013</checkIn>
<checkOut>06.03.2013</checkOut>
<hotel>882</hotel>
<hotelPansion>1491</hotelPansion>
<hotelRoom>1492</hotelRoom>
<regionId>14259</regionId>
</Residence>
<Transfer>
<serviceId>4</serviceId>
<date>26.02.2013</date>
<fromId>664</fromId>
<toId>882</toId>
<type>3635</type>
<flightDeparture>762902</flightDeparture>
</Transfer>
<Transfer>
<serviceId>5</serviceId>
<date>06.03.2013</date>
<fromId>882</fromId>
<toId>664</toId>
<type>3635</type>
<flightDeparture>762902</flightDeparture>
</Transfer>
<Ticket>
<serviceId>2</serviceId>
<flightDeparture>762902</flightDeparture>
<seatType>3</seatType>
<toResortCountry>true</toResortCountry>
<departure_datetime>25.02.2013 20:40</departure_datetime>
<departureCityId>345</departureCityId>
</Ticket>
<Ticket>
<serviceId>3</serviceId>
<flightDeparture>763960</flightDeparture>
<seatType>3</seatType>
<toResortCountry>false</toResortCountry>
<departure_datetime>06.03.2013 10:15</departure_datetime>
<arrivalCityId>345</arrivalCityId>
</Ticket>
<ServiceTourist>
<serviceId>1</serviceId>
<touristId>1</touristId>
</ServiceTourist>
<ServiceTourist>
<serviceId>1</serviceId>
<touristId>2</touristId>
</ServiceTourist>
<ServiceTourist>
<serviceId>2</serviceId>
<touristId>1</touristId>
</ServiceTourist>
<ServiceTourist>
<serviceId>2</serviceId>
<touristId>2</touristId>
</ServiceTourist>
<ServiceTourist>
<serviceId>3</serviceId>
<touristId>1</touristId>
</ServiceTourist>
<ServiceTourist>
<serviceId>3</serviceId>
<touristId>2</touristId>
</ServiceTourist>
<ServiceTourist>
<serviceId>4</serviceId>
<touristId>1</touristId>
</ServiceTourist>
<ServiceTourist>
<serviceId>4</serviceId>
<touristId>2</touristId>
</ServiceTourist>
<ServiceTourist>
<serviceId>5</serviceId>
<touristId>1</touristId>
</ServiceTourist>
<ServiceTourist>
<serviceId>5</serviceId>
<touristId>2</touristId>
</ServiceTourist>
</order>
Order Booking
There are several different ways to book the order via the gate:
1. Order booking without specifying the price.
2. Order booking with desired price specified.
3. Order booking with the price specified in the price offer.
The difference of order’s xml structure for each of these variants is in the ‘Summary’ element characteristics.
To book the order it is necessary to pass the order xml in the request body at http://xml.tez-tour.com/xmlgate/order/book
In the http-request header it is necessary to pass the ‘application/xml’ attribute value for the ‘Content-Type’ field.
Note that during booking the check-up is not performed that all tourists are linked to all services of the order.
The request should contain the following mandatory elements:
OrderType section
This section is mandatory.
Mandatory elements of the section:
type – ‘Touristic’ element value.
Country section
This section is mandatory.
Mandatory elements of the section:
id – country id.
Tourist section
This section is mandatory.
touristId – unique tourist id. During initial booking any digits can be used as id. After booking the order and saving it in the database, the tourists will be given new ids.
surname – tourist’s surname. Specified in capital Latin letters.
name – tourist’s name. Specified in capital Latin letters
gender – id of the form of address for the tourist. To fill this parameter correctly, use the reference table http://xml.tez-tour.com/xmlgate/list/genders.xml.
ServiceTourist section
This section is mandatory.
Check-up of linking all services to all tourists is not performed.
serviceId – service id in the order.
touristId – tourist id in the order.
Residence section
This section is not mandatory.
serviceId – stay id.
checkIn – check-in date.
checkOut – check-out date.
hotelPansion – Hotel-meal combination id.
hotelRoom – Hotel-room type combination id.
Transfer section - optional
serviceId – transfer id.
date – transfer date.
fromId – transfer departure location (city)
toId – transfer destination (where to)
type – transfer type id.
flightDeparture – flight id. It determines the link of transfer to a specific flight. If there is no value during booking, then the transfer will not be linked to the flight and the tourists will not be met at the airport.
Ticket section
This section is not mandatory.
serviceId – service id.
flightDeparture – flight departure id.
seatType –id of seat type in the aircraft.
Insurance section
Contains information about insurance. Includes nested elements:
serviceId – service id.
from – insurance validity start date.
to – insurance validity end date. Mandatory field
ExtraService section
This section is not mandatory.
serviceId – service idr.
date – date of service.
type – service id in the reference table.
Comment section
This section is not mandatory.
text – comments for order.
Booking Order without Specifying the Price
In order to book the order it is necessary to pass the post-request with the order to http://xml.tez-tour.com/xmlgate/order/book
In case of successful booking the system reply is received containing the order number. Otherwise, the reply will contain the error message.
Booking Order with Price Specified
When placing the order via XML gate, expected order price can be specified. In order to do that, specify expected price in the ‘requestedSpoPrice’ field of the "<Summary>" section.
Example:
<Summary>
<currency>5561</currency>
<requestedSpoPrice>1000</requestedSpoPrice>
</Summary>
In case if the expected and actual prices of the order match, a system reply is received that contains the order number, representing the success of the operation.
Example:
<booking-result>
<orderId>123213123</orderId>
</booking-result>
In case if the specified price does not match the actual price, the order will not be recorded to database, and the reply will contain the actual price for the moment.
Example:
<booking-result>
<error>
<PriceBooking>
<bookingResult>failure</bookingResult>
<containerid>123123</containerid>
<actualPrice>1100.0</actualPrice>
<requestedPrice>1000.0</requestedPrice>
</PriceBooking>
</error>
</booking-result>
Booking Order with the Price Specified in the Price Offer
In order for the order to be booked via XML gate with the specified price, its ‘containerId’ should be specified. To do that, specify the selected container ID in the ‘containerId’ field of the ‘<Summary>’ section.
Example:
<Summary>
<containerId>123456789</containerId>
<spo>TEST</spo>
<price>1100.0</price>
<currency>5561</currency>
<spoId>123456</spoId>
</Summary>
******
Attention! If ‘Transfer’ section does not have ‘flightDeparture’ specified during booking, the transfers are not linked to the specific flight and the tourists will not be met at the airport.
******
Preliminary Booking
The gate allows preliminary booking of orders. To do that, you need to specify the following elements in the xml order passed for booking:
<TimeLimit>
<type>128770</type>
<value>26.01.2013 13:00</value>
</TimeLimit>
Elements:
TimeLimit –element containing the information about the conditions of preliminary booking. Includes nested elements:
type – element containing the information about the type of preliminary booking.
value – date and time up to which the order is in the preliminary booking state. Format: dd:mm:yyyy hh:mm. Preliminary booking can be available for 48 hours maximum. Note that the number of orders for preliminary booking is limited.
Preliminary booking can be canceled. To do this, use the service specified below. Note that the service deletes only the preliminary booking but does not cancel the order:
http://xml.tez-tour.com/xmlgate/deleteTimeLimit?orderId=
You can cancel the preliminary booking order using the following service:
http://xml.tez-tour.com/xmlgate/cancelOrderWithTimeLimit?orderId=
Printing Documents for the Order
Links to the documents for printing are listed in the service: http://xml.tez-tour.com/xmlgate/order/view?orderId=
Elements containing the links:
eTicketURL – link to e-ticket,
insuranceUrl – link to insurances,
aviaNoteUrl – link to avianote. In most cases avianote can be printed only after the departure of tourists.
voucherUrl – link to voucher.
When referencing the link to the document ‘aid’ parameter should be added to url parameters.
To confirm the document print date it is necessary to use the service: http://xml.tez-tour.com/xmlgate/order/docPrintSubmit?orderId=
orderId – mandatory parameter containing the order number.