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

Версия 12:38, 4 мая 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 /> - даты, на которые есть заезды в указанном туре (будет реализовано в следующей версии)
• <comment /> - комментарий к СПО (будет реализовано в следующей версии)

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

Информация о стопах и квотах

Внимание! В результат работы метода GetStopSalesAndQuotes(DateTime checkPoint) попадают только те данные, которые изменялись за период c checkPoint по текущую дату. Такой вариант работы подразумевает ведение своей собственной базы с занесением в нее информации по квотам и стопам.

В разделе references приведены справочники, на которые ссылаются отобранные перелеты или гостиницы.

   <references>
     <countries>
        <country key="460" name="Россия" nameLat="Russia" code="RU" />
        <country key="86" name="Турция" nameLat="TURKEY" code="TR" />
     </countries>
     <resorts /> 
     <cities>
         <city key="1" name="Москва" nameLat="Moscow" code="MOW" countryKey="460" />
         <city key="187" name="АНТАЛИЯ" nameLat="ANTALYA" code="AYT" countryKey="86" /> 
      </cities>

и т.д. Более подробно о структуре справочной информации можно прочитать в разделе "формат TourML".

В разделе

<sources>
   <source name="name" uri="http://www.name.ru/">
       <quotaServices>

приведена информация по квотам.

Информация по квотам на перелет

Для каждого авиаперелета и тарифа формируется следующая информация^

<flightService flightKey="552" tariffKey="330">

где flightKey - ключ перелета, tariffKey - ключ тарифа.

<stopsales>
   <stopsale dateFrom="2009-05-01" dateTo="2009-05-02" typeVisit="byPeriod" status="Modified" />
</stopsales>

В элементах <stopsale> приведена информация об остановках продаж на период времени с dateFrom по dateTo.

<quotas> <quota date="2009-05-05" places="125" freeAccess="many" typeQuantity="byPerson" typeVisit="byPeriod" status="Created" /> </quotas>

Квоты по датам преведены в элементах <quota>.

• Атрибут date - дата, на которую проверяется квота.
• Атрибут places - количество свободных мест (отображается если настройка isShowQuantity установлена в true)
• Атрибут freeAccess - в зависимости от результата проверки квот и настроек <quoteQualifiers> может принимать значения "byQuery", "none", "little", "many".

• Остальные атрибуты всегда остаются такими typeQuantity="byPerson" typeVisit="byPeriod".
• Если атрибут status="Deleted", то это означает, что данная квота или стоп сейл были удалены из базы данных.

Примеры возвращаемых данных:

 <flightService flightKey="10823" tariffKey="332">
 <quotas>
 <quota date="2009-05-28" places="0" freeAccess="byQuery" typeQuantity="byPerson" typeVisit="byPeriod" status="Created" />

- квота на заданное число не задана.

 <quota date="2009-05-31" places="0" freeAccess="none" typeQuantity="byPerson" typeVisit="byPeriod" status="Created" /> 

- на заданное число нет мест

 <quota date="2009-06-10" places="17" freeAccess="little" typeQuantity="byPerson" typeVisit="byPeriod" status="Created" />

- на заданное число есть 17 мест.
Если на какое либо число отсутствует квота в разделе <quotas>, то считается что данная услуга также имеет статус "под запрос" (byQuery).

Информация по квотам на проживания

<hotelService buildingKey="3239" roomTypeKey="1" roomDescriptionKey="20">
<quotas>
 <quota date="2009-07-15" places="0" freeAccess="byQuery" 
               typeQuantity="byPerson" typeVisit="byPeriod" status="Created" />
 <quota date="2009-07-16" places="0" freeAccess="byQuery" 
               typeQuantity="byPerson" typeVisit="byPeriod" status="Created" />

• buildingKey - ключ гостиницы
• roomTypeKey - тип комнаты (HotelRoom.RoomKey)
• roomDescriptionKey - категория комнаты (HotelRoom.RoomsCategoryKey)
• typeQuantity="byRoom" - квота предоставляется на комнату
• ...."byPerson" - квота предоставляется на человека. При проверке нужно учитывать количество людей. (используется реже)
• typeVisit="byPeriod" - квота задана на указанный день. Квоты должны проверяться на все дни тура
• ...."byCheckin" - на заезд. проверка квот идет только на первый день. Если в первый день заезда места есть, то считается что есть. (используется реже)

Примеры возвращаемых данных:

<hotelService buildingKey="3275" roomTypeKey="79" roomDescriptionKey="51">
 <stopsales>
   <stopsale dateFrom="2009-08-14" dateTo="2009-08-15" typeVisit="byPeriod" status="Modified" />
   <stopsale dateFrom="2009-08-17" dateTo="2009-08-18" typeVisit="byPeriod" status="Modified" />
 </stopsales>
 <quotas>
   <quota date="2009-08-16" places="1" freeAccess="little" typeQuantity="byRoom" 
                                                       typeVisit="byPeriod" status="Modified" />
 </quotas>
</hotelService>

Расширенная информация о квотах

<flightService flightKey="552" tariffKey="330">

<stopsales>
   <stopsale dateFrom="2009-05-01" dateTo="2009-05-02" typeVisit="byPeriod" status="Modified" />
</stopsales>

 <flightService flightKey="10823" tariffKey="332">
 <quotas>
 <quota date="2009-05-28" places="0" freeAccess="byQuery" typeQuantity="byPerson" typeVisit="byPeriod" status="Created" />

 <quota date="2009-05-31" places="0" freeAccess="none" typeQuantity="byPerson" typeVisit="byPeriod" status="Created" /> 

 <quota date="2009-06-10" places="17" freeAccess="little" typeQuantity="byPerson" typeVisit="byPeriod" status="Created" />

<hotelService buildingKey="3239" roomTypeKey="1" roomDescriptionKey="20">
<quotas>
 <quota date="2009-07-15" places="0" freeAccess="byQuery" 
               typeQuantity="byPerson" typeVisit="byPeriod" status="Created" />
 <quota date="2009-07-16" places="0" freeAccess="byQuery" 
               typeQuantity="byPerson" typeVisit="byPeriod" status="Created" />

<hotelService buildingKey="3275" roomTypeKey="79" roomDescriptionKey="51">
 <stopsales>
   <stopsale dateFrom="2009-08-14" dateTo="2009-08-15" typeVisit="byPeriod" status="Modified" />
   <stopsale dateFrom="2009-08-17" dateTo="2009-08-18" typeVisit="byPeriod" status="Modified" />
 </stopsales>
 <quotas>
   <quota date="2009-08-16" places="1" freeAccess="little" typeQuantity="byRoom" 
                                                       typeVisit="byPeriod" status="Modified" />
 </quotas>
</hotelService>