Описание формата TourML.

Материал из Wiki
Перейти к: навигация, поиск

Введение

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".

Источник — «http://wiki2.mag.travel/index.php?title=Описание_формата_TourML.&oldid=380»