Описание формата TourML. — различия между версиями

Текущая версия на 16:26, 13 октября 2017

Введение

TourML - xml-документ, в котором передается информация о турах, ценах, услугах, входящих в эти цены, квотах.

Структурно xml-документ разделен на 3 части:

• header – заголовок документа
• references (необязательна) – секция справочников
• sources – секция цен

Header

Элемент header обязателен, но содержит необязательную для синхронизации информацию о том, кто и с помощью какой реализации сформировал документ.

• name (обязателен)– строка, содержащая значение, указывающее на владельца документа (но не информации, которая в нем находится). Обычно это название компании, которая формирует документ. Как правило, не используется при синхронизации.
• uri (необязателен)– уникальный идентификатор владельца документа.

Элемент loadTime содержит следующие данные:

• timeValue - информация о времени загрузки (не используется)
• lastKey - для постраничной загрузки максимальный (наибольший) ключ тура, который передается для выгрузки следующей страницы

<header name="ООО МегаТур" uri="www.megatour.com" xmlns="http://tourml.ru/products/2004-04-19">
<loadTime timeValue="100" xmlns="http://www.megatec.ru/tourml/extensions" lastKey="3451235"/>
</header>

References

Элемент references содержит информацию об используемых при описании справочниках. Этот элемент является необязательным, однако, практически всегда используется, так как трудно описать информацию не сославшись как какой-либо справочник. Например, при описании СПО, необходимо ссылаться на страны, валюту и т.д. Таким образом, элементы справочников должны присутствовать в документе практически всегда для сохранения ссылочной целостности.
Элементы справочников, используемые во всем документе, описываются только в данном разделе.
Уникальность первичных ключей элементов справочников поддерживается в пределах элемента references.

В справочниках содержатся следующие разделы:

• countries – раздел, описывающий страны
• resorts – раздел, описывающий регионы
• cities – раздел, описывающий города
• categories – раздел, описывающий категории звездности отелей и кают
• hotels – раздел, описывающий отели
• buildings – раздел, описывающий корпуса отелей
• airlines – раздел, описывающий авиакомпании
• airports – раздел, описывающий аэропорты
• aircrafts – раздел, описывающий авиасуда
• flights – раздел, описывающий перелеты
• roomTypes – раздел, описывающий типы номеров
• roomLocations – раздел, описывающий расположение номера
• roomViews – раздел, описывающий вид из номера
• roomCategories – раздел, описывающий уровень комфортности
• roomDescriptions – используемые комбинации расположения номера, вида из номера и уровня комфортности номера
• roomAccomodations – раздел, описывающий проживание в номере
• rooms – используемые комбинации типов номеров, проживания и описания номера (roomDescriptions)
• serviceClasses – раздел, описывающий типы услуг
• serviceDescriptions – раздел, описывающий дополнительные услуги
• serviceDescriptions1– раздел, описывающий дополнительные услуги
• serviceDescriptions2– раздел, описывающий дополнительные услуги
• transfers – раздел, описывающий услуги переезда
• excursions – раздел, описывающий экскурсионные услуги
• transports – раздел, описывающий транспорт
• cabines – раздел, описывающий каюты
• ships – раздел, описывающий морские суда
• boardings – питание
• currencies – валюта
• tariffs – тарифа перелетов
• tourTypes – типы туров

Пример - справочник городов:

   <countries>
     <country key="29" name="Греция" nameLat="Greece" code="GRC" />
     <country key="375" name="Россия" nameLat="Russia" code="RUS" />
     <country key="99999999" fake="true" stdKey="UNKNOWN" name="UNKNOWN" nameLat="UNKNOWN" code="UNKNOWN" />
   </countries>

У каждого элемента из указанных выше разделов существуют атрибуты:

• key (обязателен) - ключ в таблице соответствующего справочника.
• fake (необязателен) - указывает на то, что первичный ключ является фиктивным (если значение true). Даже в том случае, когда первичный ключ является фиктивным, он должен быть уникален. Обычно ключ (key) такой фиктивной записи равен значению 99999999 или 0. Все остальные атрибуты заполняются значением UNKNOWN.
• stdKey (необязателен) – стандартный ключ элемента справочника. Используется в тех случаях, когда принимающая сторона заранее не имеет данных справочников и не может синхронизировать запись по идентификатору. Реализация может при синхронизации отдавать приоритет атрибуту stdKey перед атрибутами code, name и nameLat, однако вследствие того, что туроператоры не заполняют это поле надлежащим образом, как правило, в нем содержится мусор не имеющий ничего общего со стандартным ключом (ISO кодом).
  

Также могут включать в себя дополнительные атрибуты типа Name, NameLat, Code и др.

Sources

Элемент sources может содержать информацию о туре.
Информация о ценах содержится в элементах packet, который состоит из 3-х частей:

• packetHeader - общая информация о туре и СПО
• services - информация об услугах, включенных в цены
• prices - цены и даты заезда + ссылки на услуги

packetHeader имеет следующую структуру:

         <packetHeader>
           <tour key="2054" name="Халкидики" tourTypeKey="2" countryKey="29" />
           <spo key="3206" for="byRoom" validFrom="2009-09-25" validTo="2009-10-07" currencyKey="2"
                                           state="Created"  issue="2009-08-03T13:04:06.0000000+04:00">
             <dates />
             <comment />
           </spo>
           <spoInfo xmlns="http://www.megatec.ru/tourml/extensions">
             <priceQuantity>3736</priceQuantity>
           </spoInfo>
         </packetHeader>

• tour key - ключ тура
• name - название тура
• tourTypeKey, countryKey - тип тура и страна - описаны в разделе справочники.

• spo key - ключ соответствующего СПО
• for="byRoom" (или "byPerson") - показывает за что указаны цены - за комнату или за человека.
• validFrom="2009-09-25" validTo="2009-10-07" - промежуток времени, на который распространяется данное СПО
• currencyKey - валюта, в которой заведены цены - описана в разделе справочники.
• state="Created" (или "Modified") - статус тура - создан (изменен)
• issue="2009-08-03T13:04:06.0000000+04:00" - дата и время последнего изменения тура.
• <dates /> - даты, на которые есть заезды в указанном туре (будет реализовано в следующей версии)

• spoInfo содержит элемент priceQuantity, в котором указано количество доступных цен для тура.

• services - информация об услугах, на которые есть ссылки из раздела цен.

Услуги разделены по следующим группам:

Услуга проживания. Например,

<hotelService mealKey="44" roomKey="4648" buildingKey="3413">

• mealKey - тип питания из справочника boardings
• roomKey - тип комнаты
• buildingKey - тип здания

Услуга перелета. Например,

<flightService tariffKey="89" flightKey="631">

• tariffKey - тариф на перелет из справочника tariffs
• flightKey - перелет из справочника Flights (описывает город вылета-прилета, авиакомпанию).

Справочник Flights включает в себя элементы FlightTimes (расписания перелетов).

Услуга экскурсий. Например,

<excursionServices transportKey="23" excursionKey="12">

• transportKey,excursionKey - сслылки на справочники тип транспорта (transports) и экскурсия (excursions)

Услуга трансфера. Например,

<transferService transferKey="1989" transportKey="210">

• transferKey, transportKey - соответствующие ссылки на справочники transfers и

transports

Услуга круиз. Например,

<cruiseServices shipKey="123" cabineKey="12">

• shipKey, cabineKey - ссылки на справочники cabines и ships.

Остальные услуги - страховка, виза, доп. услуги и т.д. Например,

<extraService classKey="6" subKey="30037" subKey1="5162" subKey2="17" countryKey="460" cityKey="1">

• classKey - тип услуги из справочника serviceClasses
• subKey - описание услуги из справочника serviceDescriptions
• subKey1 - дополнительное описание 1 из справочника serviceDescriptions1
• subKey2 - дополнительное описание 2 из справочника serviceDescriptions2
• countryKey - ссылка на страну из справочника Country
• cityKey - ссылка на город из справочника City

Внутри элемента каждой такой услуги приведены варианты этой услуги (элемент variant) в зависимости от продолжительности, дня начала предоставления и других параметров

<flightService tariffKey="330" flightKey="2284">
   <variant providerKey="0" dayBeg="1" nights="0" days="0" men="1" allowDelete="true" 
                  allowEditMainService="true" allowEditSubService="true" id="_39839489">
       <info>
           <additionalAttributes allowEditCity="true" allowEditPartner="true" 
                                      xmlns="http://www.megatec.ru/tourml/extensions" />
       </info>
   </variant>
   <variant providerKey="0" dayBeg="1" nights="0" days="0" men="2" allowDelete="true" 
                 allowEditMainService="true"  allowEditSubService="true" id="_39839488">
       <info>
           <additionalAttributes allowEditCity="true" allowEditPartner="true" 
                                      xmlns="http://www.megatec.ru/tourml/extensions" />
       </info>
   </variant>
</flightService>

Элемент variant имеет следующие атрибуты:

• providerKey - ключ партнера, предоставляющего услугу (не используется - возвращается 0)
• dayBeg - день начала предоставления услуги
• nights - продолжительность услуги в ночах
• days - продолжительность услуги в днях
• men - количество человек, на которое расчитана данная услуга
• id - ключ услуги, на который ссылается serviceSet из раздела prices
• allowDelete - флаг, показывающий можно ли удалить данную услугу
• allowEditMainService - флаг, показывающий можно ли изменять услугу
• allowEditSubService - флаг, показывающий можно ли изменять SubService (подчиненную услугу) у данной услуги

У элемента variant существует вложенный опциональный элемент info, в который выводится дополнительные атрибуты услуги (если хотя бы одна из них true):

• allowEditCity - у услуги возможно редактирование города
• allowEditPartner - у услуги возможно редактирование партнера, предоставляющего услугу
• allowEditDuration - у услуги возможно редактировать продолжительность
• Invisible - флаг, показывающий что услуга скрытая (сейчас этот флаг не используется, поскольку скрытые услуги отсеиваются на этапе выгрузки из базы)

Как для атрибутов у variant так и для атрибутов info справедливо следующее правило: если какой-то из флагов имеет значение false, то он не возвращается в ответе. То есть

<additionalAttributes allowEditCity="true" allowEditPartner="true" xmlns="http://www.megatec.ru/tourml/extensions" />

означает:

• allowEditCity = true
• allowEditPartner = true
• allowEditDuration = false
• Invisible = false

prices - раздел, в котором сгруппированы обсчитанные услуги и указаны цены на пакеты из этих услуг, в зависимости от дат заезда.

В элементе serviceSet в атрибуте ids указан список id услуг пакета (ключей элементов variant, описанных выше).

<serviceSet ids="_2000051 _2000056 _2000061 _2000066 _2000071 _2000076 _2000081 _2000441">
   <price gross="3586">
       <date key="67222503" from="2009-09-25" to="2009-09-25" />
       <date key="67222504" from="2009-09-27" to="2009-09-27" />
   </price>
   <price gross="3756">
       <date key="67222793" from="2009-09-29" to="2009-09-29" />
   </price>
</serviceSet>

В элементах price указаны цены (gross) за набор услуг пакета. Внутри элемента price вложены элементы data, имеющие следующие атрибуты:

• key - ключ обсчитаной цены
• from, to - промежуток дат, на который распространяется эта цена.

При проверке бронирования данный ключ + дата из промежутка from, to должны передаваться в качестве параметров.

Таким образом, это означает, что пакет с ключем 67222503 на 2009-09-25 стоит (предварительная цена) 3586 (валюта берется из описания СПО) и состоит из следующих услуг: "_2000051 _2000056 _2000061 _2000066 _2000071 _2000076 _2000081 _2000441".