Шлюз позволяет выполнять большинство операций с заявкой. Редактирование не входит в число этих операций.
Общая схема работы с заявкой в шлюзе выглядит следующим образом:
- Создание XML-заявки - перед бронированием необходимо создать и заполнить заявку в формате XML. Для удобства можно воспользоваться сервисом http://xml.tez-tour.com/xmlgate/order/orderFromOfferId, который возвращает подготовленный шаблон заявки по идентификатору цены. Подробнее сервис описан здесь.
- Расчет итоговой стоимости - получение итоговой стоимости заявки, включая все доплаты. Шаг не является обязательным. Сервис описан тут.
- Бронирование заявки - внесение вашей заявки в нашу базу. Сервис описан здесь.
- Предварительное бронирование (бронирование с тайм-лимитом) - заявки, внесенные по предварительному бронированию, могут быть отменены без дополнительных санкций. Количество заявок по предварительному бронированию ограничено. Подробно сервис описан здесь.
- Запрос на аннулирование заявки/услуги - шлюз позволяет сделать запрос на аннулирование заявки или отдельной услуги заявки. Подробно сервис описан здесь.
- Печать документов и подтверждение печати документов - по забронированной заявке можно распечатать документы. Сервис печати описан здесь. Распечатку документов необходимо подтвердить с помощью сервиса, описанного тут.
Кроме этого, в шлюзе предусмотрены следующие сервисы по работе с заявками:
- просмотр забронированной заявки,
- просмотр списка забронированных заявок по заданным критериям.
Во всех обращениях к перечисленным сервисам необходимо добавлять aid.
Структура заявки
Все возможные элементы заявки описаны в разделе Структура заявки.
Просмотр заявки
Запрос на просмотр заявки: http://xml.tez-tour.com/xmlgate/order/view?orderId=${orderId}
В ответе будет передано содержимое заявки в формате XML.
Список заявок
Запрос на получение списка заявок по заданным критериям. Запрос: http://xml.tez-tour.com/xmlgate/order/list?param=
В запросе обязательно должен указываться хотя бы один критерий, по которому будет сформирован список:
creationDateFrom - Дата создания заявки, начало интервала поиска. Если не указана, предполагается что нужны заявки, созданные начиная с сегодняшнего дня.
creationDateTo - Дата создания заявки, конец интервала поиска. Если не указана, заявки ищутся без ограничений по этому параметру.
startDateFrom - Дата начала действия заявки, начало интервала. Как правило "начало действия заявки" - дата первого дня проживания туристов. Если не указана - без ограничений по этому параметру.
startDateTo - Дата начала действия заявки, конец интервала поиска. Если не указана - без ограничений по этому параметру.
country - Страна заявки. Если не указана - без ограничений по этому параметру.
authorized - если значение параметра true, и у пользователя нет роли infoRestricted, то в списке отображаются все заявки агентства.
updatedDateFrom - Время последнего редактирования заявки. Указывается в формает dd.mm.yyyy hh:mm Если при этом в параметрах запроса не передается creationDateFrom, то ищутся только заявки за последние сутки, начиная с 00:00 предыдущих суток. Если в параметрах передается creationDateFrom, то ищутся заявки с учетом указанной даты создания. Если параметр updatedDateFrom не указан в запросе - поиск происходит без ограничений по этому параметру.
В результатах запроса используется ограничение - доступны заявки с датой начала поездки не ранее 365 дней от сегодняшней даты.
Пример запроса: http://xml.tez-tour.com/xmlgate/order/list?creationDateFrom=10.09.2012&aid=811BC5F15B49323FF5BCFD192E75DF992C2B538A20141020161454.m08
Формирование xml-заявки по ценовому предложению
Запрос возвращает XML-заявки, сформированный по заданному ценовому предложению.
Если цена динамическая.
Параметры запроса:
- resTariffs - обязательный параметр, идентификатор ячейки тарифа на проживание
- flyTariffs – обязательный параметр, может быть несколько идентификаторов ячейки тарифа на перелет, например, flyTariffs=123123, 12333
- priceOfferId - обязательный параметр, идентификтор тарифа на проживание
- tariffDepCityId – город вылета, обязательный параметр
- firstTransferType - тип трансфера по прибытию на отдых, обязательный параметр
- lastTransferType - тип трансфера при возвращении с отдыха,обязательный параметр
- resortArrivalRegionId - регион вылета, обязательный параметр,
- resortDepartureRegionId - регион прилёта, обязательный параметр
- firstTransferVehicleId - выбранный вариант машины из аэропорта в отель (если указан в ссылке на создание в онлайн кабинет)
- lastTransferVehicleId - выбранный вариант машины из отеля в аэропорт (если указан в ссылке на создание в онлайн кабинет)
- spoKindId - тип пакета (1 - Полный пакет, 2 - Проживание + Трансфер, 3 - Проживание, 6 - Проживание+Перелёт)
- hotelResourceId - дополнительное проживание, необходим если в предложение есть второе проживание
- promo - промо-тариф (1 - Да, 0 - Нет), необязательный параметр, по умолчанию 1
Типы трансферов могут принимать следующие значения:
- 3635 – G (групповой),
- 3636 – I (индивидуальный),
- 2996 - VIP
Обратите внимание. В сформированном ответе элементы блока Tourist заполнены не будут - вам необходимо указать данные конкретных туристов, для которых бронируется заявка.
С 03.04.2014 будет изменен формат данных в ответе сервиса для заявок, созданных по предложениям с динамическим ценообразованием.
В тэг "Summary" будут добавлены параметры для идентификации тарифов:
<resTariffs>
<resTariff id="100043434"/>
</resTariffs>
<flyTariffs>
<flyTariff id="11192732"/>
<flyTariff id="11192733"/>
</flyTariffs>
То есть тэг "Summary" в XML заявки, созданном с помощью сервиса orderFromOfferId по системе динамического ценообразования,
будет иметь следующий вид:
<Summary>
<spo>TARIFF N 10060/0H EGYPT 21.03-09.09.14</spo>
<price>1034.0</price>
<calculated>false</calculated>
<currency>5561</currency>
<spoId>11192731</spoId>
<resTariffs>
<resTariff id="100043434"/>
</resTariffs>
<flyTariffs>
<flyTariff id="11192732"/>
<flyTariff id="11192733"/>
</flyTariffs>
</Summary>
Если цена получена по СПО.
Запрос: http://xml.tez-tour.com/xmlgate/order/orderFromOfferId?cDateId=&priceOfferId=&hotelResourceId=
В запросе используются следующие обязательные параметры:
- cDateId - обязательный параметр. Идентификатор контейнера ценового предложения (цены).
- priceOfferId - обязательный параметр. Идентификатор ценового предложения.
- hotelResourceId - параметр обязателен для предложений, предусматривающих несколько проживаний. Параметр определяет отель для второго проживания. Соответствует идентификатору связки "отель-тип питания-тип размещения" (атрибут hResId в результатах подбора тура).
Расчет заявки
Перед бронированием заявки, можно предварительно рассчитать ее стоимость. Заполненный XML с заявкой (xml тот же, что и при бронировании) необходимо передать в теле запроса. В заголовке http-запроса для поля Content-type необходимо передать значение application/xml. http://xml.tez-tour.com/xmlgate/order/calculate Расчет доступен как для пакетных туров, так и для непакетных туров. Цена указана в валюте заявки.
Если заявка рассчиталась, то возвращается xml:
<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>
<currency>18864</currency>
<Insurance>
<type>VSK-SPAIN</type>
<price>0.0</price>
</Insurance>
<Insurance>
<type>NEVYLET VSK (SPAIN)</type>
<price>0.0</price>
</Insurance>
<Visa>
<type>Туристическая</type>
<price>120.0</price>
</Visa>
</CalcOrderResult>
Стоимость некоторых сервисных услуг, таких как визы (Visa), страховки (Insurance) и ExtraService, отображается в отдельных элементах (при этом их стоимость уже включена в итоговую цену, отображаемую в теге price)
Если заявка не рассчиталась, то тега со значением цены не будет. Например, в ответ на заявку может прийти ответ:
<?xml version="1.0"?>
<CalcOrderResult>
<extraPrice>0.0</extraPrice>
<percent>0.0</percent>
</CalcOrderResult>
Это означает, что заявка не была рассчитана. Существует несколько причин такого поведения:
1. xml-заявка сформирована некорректно. Убедитесь, что даты рождения туристов соответствуют настоящим. По дате рождения определяется тип туриста (взрослый, ребенок), что влияет на конечную цену тура. Убедитесь, что все туристы заявки привязаны к услугам заявки. Если какая-то из услуг не привязана к туристу, то рассчитать заявку невозможно.
2. По какой-либо услуге в заявке нет цены.
Пример заявки:
<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>
<email>test@test.com</email>
</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>
Бронирование заявки
Существует несколько вариантов бронирования заявки через шлюз:
- Бронирование заявки без указания цены.
- Бронирование заявки с указанием желаемой цены.
- Бронирование заявки по цене, указанной в ценовом предложении.
- Бронирование заявки с указанием конкретного тарифа.
- Бронирование заявки без услуги "Виза".
Отличие структуры xml заявки для каждого варианта заключается в особенностях элемента Summary.
Для бронирования заявки необходимо передать xml-заявки в теле запроса на http://xml.tez-tour.com/xmlgate/order/book
В заголовке http-запроса для поля Content-Type необходимо передать значение application/xml.
Обратите внимание, при бронировании не проводится проверка на привязку всех туристов ко всем услугам заявки.
Заявка должна содержать следующие обязательные элементы:
Блок OrderType
Блок является обязательным.
Обязательные элементы блока:
type - значение элемента Touristic.
Блок bookOrderParams
Блок не является обязательным.
Элементы блока:
withoutVisa - true - забронировать заявку без услуги Виза, false - забронировать заявку с указанной услугой виза
ExcludeMissedDepartureInsurance - true - забронировать заявку без услуги Страховка от невылета, false - забронировать заявку с указанным типом страховки
Блок Country
Блок является обязательным.
Обязательные элементы блока:
id - идентификатор страны.
Блок Tourist
Блок является обязательным.
touristId - уникальный идентификатор туриста. При первоначальном бронировании в качестве идентификатора можно использовать любые цифры. После бронирования заявки и ее сохранения в базе, туристам будут присвоены новые идентификаторы.
surname - фамилия туриста. Задается заглавными латинскими буквами.
name - имя туриста. Задается заглавными латинскими буквами.
gender - идентификатор обращения к туристу. Для корректного заполнения используйте справочник http://xml.tez-tour.com/xmlgate/list/genders.xml.
Для визовых заявок:
visaType - варианты оформления визы (0 - визу оформляет Тез-Тур, так же можно указать город оформления визы; 1 - виза не нужна; 2 - документы для самостоятельного оформления)
VisaCityRegistrationId - id города оформления визы. Используется, если необходимо указать город оформления, отличный от того, что проставляется в заявке по умолчанию.
residenceCityId - id города постоянного проживания туриста
Блок ServiceTourist
Блок является обязательным.
Проверка на привязку всех услугу ко всем туристам не проводится.
serviceId - идентификатор услуги в заявке.
touristId - идентификатор туриста в заявке.
Блок Residence
Блок необязателен.
serviceId - идентификатор проживания.
checkIn - дата заезда.
checkOut - дата выезда.
hotelPansion - идентификатор пары Отель - пансионы.
hotelRoom - идентификатор пары Отель - тип комнаты.
Блок Transfer - опционально прилёт
serviceId - идентификатор трансфера.
date - дата выполнения трансфера.
fromId - место отправления трансфера (Аэропорт ID)
toId - место назначения трансфера (Отель ID)
type - идентификатор типа трансфера.
flightDeparture - идентификатор рейса. Определяет привязку трансфера к определнному рейсу. Если значение отсутсвует при бронировании, то трансфер не будет привязан к рейсу. В этом случае у принимающего офиса не будет информации о том, для какого именно рейса необходим трансфер и туристов могут не встретить в аэропорту.
Блок Transfer - опционально возрат
serviceId - идентификатор трансфера.
date - дата выполнения трансфера.
fromId - место отправления трансфера (Отель ID)
toId - место назначения трансфера (Аэропорт ID)
type - идентификатор типа трансфера.
flightDeparture - идентификатор рейса. Определяет привязку трансфера к определнному рейсу. Если значение отсутсвует при бронировании, то трансфер не будет привязан к рейсу. В этом случае у принимающего офиса не будет информации о том, для какого именно рейса необходим трансфер и туристов могут не встретить в аэропорту.
Блок Ticket
Блок необязателен.
serviceId - идентификатор услуги.
flightDeparture - идентификатор вылетающего рейса.
seatType -идентификатор типа кресел в самолете.
Блок Insurance
Содержит информацию о страховке. Включает вложенные элементы:
serviceId - идентификатор услуги.
from - дата начала действия страховки.
to - дата завершения действия страховки. Поле обязательное.
Блок ExtraService
Блок необязателен.
serviceId - идентификатор услуги.
date - дата оказания услуги.
type - идентификатор услуги в справочнике.
Блок Comment
Блок необязателен.
text - комментарии к заявке.
Бронирование заявки без указания цены
Для бронирования заявки необходимо передать post-запрос с заявкой на http://xml.tez-tour.com/xmlgate/order/book
В случае успешного бронирования будет получен ответ, содержащий номер заявки. В ином случае ответ будет содержать сообщение об ошибке.
Бронирование заявки по конкретному тарифу
Бронирование заявки с указанием контейнеров тарифов позволяет внести заявку, рассчитанную именно по указанным тарифам, если они актуальны. Данная опция необходимо если для конкретной заявки есть несколько актуальных предложений, например, с ранним бронированием и без.
В элемент Summary необходимо указать параметры для идентификации ценовых предложений:
resTariffs - контейнер тарифа на проживание,
flyTariffs - контейнер тарифа на перелет.
Пример:
<Summary>
</spo>
</price>
</calculated>
</currency>
</spoId>
<resTariffs>
<resTariff id="100043434"/>
</resTariffs>
<flyTariffs>
<flyTariff id="11192732"/>
<flyTariff id="11192733"/>
</flyTariffs>
</Summary>
Бронирование заявки с указанием цены
При внесении заявки через XML-шлюз можно указать предполагаемую стоимость заявки. Для этого в поле requestedSpoPrice блока "<Summary>" нужно вписать ожидаемую стоимость.
Пример:
<Summary>
<currency>5561</currency>
<requestedSpoPrice>1000</requestedSpoPrice>
</Summary>
В случае совпадения предполагаемой и актуальной стоимости данной заявки, будет получено сообщение, содержащее номер заявки, обозначающее успешное завершение операции.
Пример:
<booking-result>
<orderId>123213123</orderId>
</booking-result>
В случае, если указанная цена не совпала с актуальной ценой, то заявка не будет внесена в базу данных, и в ответ придет сообщение с актуальной ценой на данный момент.
Пример:
<booking-result>
<error>
<PriceBooking>
<bookingResult>failure</bookingResult>
<containerid>123123</containerid>
<actualPrice>1100.0</actualPrice>
<requestedPrice>1000.0</requestedPrice>
</PriceBooking>
</error>
</booking-result>
Бронирование заявки по цене, указанной в ценовом предложении
Для того, чтобы заявка, при внесении через XML-шлюз, забронировалась по выбранной цене, нужно передавать его containerId. Для этого в поле containerId блока "<Summary>" нужно вписать ID выбранного контейнера.
Пример:
<Summary>
<containerId>123456789</containerId>
<spo>TEST</spo>
<price>1100.0</price>
<currency>5561</currency>
<spoId>123456</spoId>
</Summary>
Бронирование заявки без услуги "Виза"
При внесении заявок по визовым направлениям, в заявку автоматически будет добавлена услуга "Виза". Наличие услуги "Виза" в заявке накладывает ряд ограничений(например ограничение на печать документов).
Для внесения заявки без услуги "Виза"нужно добавить параметр <withoutVisa>true</withoutVisa> в элемент <BookOrderParams>
Выглядеть это будет так:
<BookOrderParams>
<withoutVisa>true</withoutVisa>
</BookOrderParams>
пример:
<order>
....
<Ticket>
<serviceId>3</serviceId>
<flightDeparture>1266492</flightDeparture>
<flightNumber>HG 8106</flightNumber>
<departure_datetime>03.08.2014 11:10</departure_datetime>
<departure_airport>VIENNA (VIE)</departure_airport>
<arrival_airport>DME</arrival_airport>
</Ticket>
<BookOrderParams>
<withoutVisa>true</withoutVisa>
</BookOrderParams>
</order>
Бронирование заявки без услуги "Страховка от невылета"
При внесении заявок в заявку автоматически будет добавлена услуга "Страховка от не вылета".
Для внесения заявки без услуги "Страховка от не вылета" нужно добавить параметр <ExcludeMissedDepartureInsurance>true</ExcludeMissedDepartureInsurance> в элемент <BookOrderParams>
Выглядеть это будет так:
<BookOrderParams>
<ExcludeMissedDepartureInsurance>true</ExcludeMissedDepartureInsurance>
</BookOrderParams>
пример:
<order>
....
<Ticket>
<serviceId>3</serviceId>
<flightDeparture>1266492</flightDeparture>
<flightNumber>HG 8106</flightNumber>
<departure_datetime>03.08.2014 11:10</departure_datetime>
<departure_airport>VIENNA (VIE)</departure_airport>
<arrival_airport>DME</arrival_airport>
</Ticket>
<BookOrderParams>
<withoutVisa>true</withoutVisa>
</BookOrderParams>
</order>
Предварительное бронирование
Шлюз позволяет выполнять предварительно бронирование заявок. Для этого в xml заявке, передаваемом на бронирование, указать следующие элементы:
<TimeLimit>
<type>128770</type>
<value>26.01.2013 13:00</value>
</TimeLimit>
Элементы:
TimeLimit - элемент, содержащий информацию об условиях предварительного бронирования. Содержит вложенные элементы:
type - элемент, содержащий информацию о типе предварительного бронирования.
value - дата и время, до которого заявка находится на этапе предварительного бронирования. Формат dd:mm:yyyy hh:mm. Предварительное бронирование доступно не более чем на 48 часов. Обратите внимание, количество заявок по предварительному бронированию ограничено.
Предварительное бронирование можно отменить. Для этого необходимо воспользоваться сервисом, указанным ниже. Обратите внимание, сервис удаляет только предварительное бронирование, но не снимает заявку:
http://xml.tez-tour.com/xmlgate/deleteTimeLimit?orderId=
Снять заявку предварительного бронирования можно с помощью сервиса:
http://xml.tez-tour.com/xmlgate/cancelOrderWithTimeLimit?orderId=
Запрос на аннулирование заявки/услуги
Шлюз позволяет сделать запрос на аннулирование заявки или отдельной услуги заявки. Для этого в xml-шлюзе необходимо сделать следующие запросы:
Запрос на аннулирование заявки:
http://xml.tez-tour.com/xmlgate/order/cancel?orderId=${orderId}
${orderId} - номер заявки
В случае успешного аннулирования заявки, xml-шлюз возвратит:
<Success>
Изменения приняты.
</Success>
Если в результате выполнения запроса на аннулирование заявки возникла ошибка, xml-шлюз возвратит:
<Error>
текст ошибки
</Error>
Запрос на аннулирование отдельной услуги:
http://xml.tez-tour.com/xmlgate/order/cancelTourService?tourServiceId=${tourServiceId}
${tourServiceId} - номер услуги
В случае успешного аннулирования услуги, xml-шлюз возвратит:
<Success>
Изменения приняты.
</Success>
Если в результате выполнения запроса на аннулирование услуги возникла ошибка, xml-шлюз возвратит:
<Error>
текст ошибки
</Error>
Печать документов по заявке
Ссылки на документы для печати содержатся в сервисе http://xml.tez-tour.com/xmlgate/order/view?orderId=
Элементы, содержащие ссылки:
eTicketURL - ссылка на электронный билет,
insuranceUrl - ссылка на страховки,
aviaNoteUrl - ссылка на авиасправку. В большинстве случаев печать авиасправки возможна только после отбытия туристов.
voucherUrl - ссылка на ваучер.
При обращении к ссылке на документ в параметры url необходимо добавить aid.
Для подтверждения даты печати документов необходимо использовать сервис http://xml.tez-tour.com/xmlgate/order/docPrintSubmit?orderId=
orderId - обязательный параметр, содержащий номер заявки.