Web-сервисы: Сервис TourML

Статья находится на стадии разработки.
Версия статьи от 24-04-2014.

Введение

Задача получения данных из программного комплекса Мастер-Тур и передача полученных данных сторонним системам, а также получение данных из сторонних систем в программном комплексе Мастер-Тур весьма актуальна.

Предлагаемое компанией Мегатек решение состоит в использовании общепризнанного механизма взаимодействия между различными системами - WEB-сервис, работающий с единым, для туристической области в России, форматом – TourML.

Формат TourML представляет из себя текстовый XML документ, использование которого позволяет избежать проблем, связанных с внутренними изменениями в программном комплексе Мастер-Тур. Использование веб-сервиса позволяет разработать систему один раз и забыть об особенностях реализации внутренних механизмов программного комплекса Мастер-Тур.

Установка

Для установки сервиса TourML нужно создать директорию сервиса TourML в каталоге c:/inetpub/wwwroot/ (корневом каталоге IIS) и выложить туда распакованные файлы из архива TourML_9.2.x.xxxxx.zip. В управлении IIS необходимо создать виртуальный каталог для папки TourML.

Создание виртуального каталога

По умолчанию корневым каталогом IIS является C:/Inetpub/wwwroot. Для создания виртуального каталога для приложения находящегося в этом каталоге нужно выполнить следующие действия:

• 1. Зайти в Пуск (Start) – Настройки (Settings) – Панель управления (Control Panel)

• 2. В открывшемся окне выбрать Администрирование (Administrative Tools)

• 3. Запустить Internet Information Services (IIS) Manager

• 4. В открывшемся дереве каталогов выбрать Web Sites – Default Web Site. В открывшемся списке найти папку, для которой нужно создать виртуальный каталог, кликнуть по ней правой кнопкой мыши и зайти в Свойства (Properties)

• 5. В открывшемся окне, в закладке Directory нужно нажать кнопку «Create», а затем кнопку «ОК»

Подключение к базе данных ПК «Мастер-Тур»

В файле web.config, расположенном в папке TourML пропишите необходимые параметры подключения (курсивом выделены значения, которые необходимо ввести). Строка подключения к базе данных ПК «Мастер-Тур»:

• 1. <add key = "connectionString" value = "Data Source=ip-адрес сервера базы данных ПК Мастер-тур;Initial Catalog=название базы данных ПК Мастер-тур;User ID=логин пользователя ПК Мастер-тур;Password=пароль пользователя ПК Мастер-тур"/>
• 2. <add key = "connectionStringShort" value = "Data Source=ip-адрес сервера базы данных ПК Мастер-Тур;Initial Catalog=название базы данных ПК Мастер-Тур;"/>

Настройки

После установки «Сервис TourML» доступен по адресу:
http://ip- адрес сервера Мастер-Веб/TourML/Service.asmx

Настройки в файле WEB.CONFIG

Дополнительные настройки, задаваемые в файле web.config, позволяют задать дополнительные условия для отображения и проверки данных.

№	Описание	Значение	Настройка
1	Настройка, определяющая ключи типов туров, которые будут передаваться.	Ключи типов туров через запятую.	<add key="tipTursFilter" value="5,6,10" />
2	Настройка, включающая возможность передавать ключи типов туров через запятую.	true - использовать фильтрацию по ключам типов туров через запятую; false или отсутствие настройки - не использовать фильтрацию по ключам типов туров через запятую.	<add key="isUseTipTursFilter" value="true" />
3	Настройка, включающая возможность отображения наличия мест для квот определенным пользователям.	В значении настройки через запятую перечисляются пользователи, которым должны быть доступны для показа количество мест. Если настройка не указана или задано пустое значение, квоты доступны всем.	<add key="showFullQuotasUserNames" value="username" />
4	Настройка, отвечающая за отображение количества мест в квоте.	true - отображает количество мест в квоте; false или отсутствие настройки - количество мест в квоте не отображается.	<add key="isShowQuantity" value="true" />
5	Настройка, снижающая нагрузку обращений к базе за счет увеличения времени отработки метода GetAgreementsByKeys. Время, указанное в настройке, является промежутком между временем окончания отработки метода и временем возврата результата.	Значение задержки измеряется в секундах. Рекомендуется указывать значение от 7 до 15 сек. Например, метод возвращал данные через 5 сек. Если в настройке указать значение 10 сек, то время обработки метода и возвращения результата будет составлять 15 сек.	<add key="delayBeforeReturn" value="10"/>
6	Настройка, включающая в методе GetReferences возможность отображения партнеров, предоставляющих услуги отеля, определенным пользователям.	В значении настройки через запятую перечисляются логин пользователей, которым должны быть доступны для показа партнеры по услуге.	<add key="showBOOAddInfoUserNames" value="test" />
7	Настройка, определяющая загрузку не выставленных в онлайн СПО туров. Работает только при включенной настройке notOnlineTourTypes	true – показывает все выставленные онлайн СПО и не выставленные онлайн СПО с ключами; false или отсутствие настройки – показывает только выставленные онлайн СПО туры	<add key="showNotOnlineSPO" value="true" />
8	Настройка, определяющая ключи типов туров СПО. Ключи хранятся в таблице TipTur.	key – перечисляются ключи типов туров через запятую	<add key="notOnlineTourTypes" value="5" />
9	Настройка, включающая в методе GetFlightQuotes отображение информации по авиаперелетам (расписание и квоты).	В значении настройки через запятую перечисляются ключи тарифов, по которым производится вывод информации по авиаперелетам.	<add key="tarifsToLoadFlightQuotes" value="89,67,114"/>
10	Настройка, позволяющая через запросы к URL и авторизацию с помощью параметров запроса Login и Password, вызывать методы в TourMl.	true – метод выполняется по запросу к URL; false или отсутствие настройки – запрос не вызывает метод (Пример: http: //ip-адрес сервера/TourMl/Service.asmx/GetHotelKeys?checkPoint=2014-01-01&cityKey=614&Login=test&Password=qUqP5cyxm6YcTAhz05Hph5gvu9M=)	<add key="allowSimpleAuth" value="true"/>

Общая информация о методах веб-сервиса

В данном разделе представлена общая информация о методах веб-сериса, которые можно использовать для взаимодействия с программным комплексом Мастер-Тур.

Методы загрузки туров

Метод GetValidTourList

Данный метод возвращает список доступных опубликованных СПО.

Список принимаемых параметров:

• Нет

Метод GetValidTourListFrom

Данный метод возвращает список доступных опубликованных СПО.

Список принимаемых параметров:

• checkPoint – дата, начиная с которой выгружается информация о доступных опубликованных СПО

Метод GetValidTourListFrom_DC

Данный метод возвращает список актуальных туров с определенной даты по заданному ключу страны

Список принимаемых параметров:

• calculatingKey – ключ расчета
• countryKey – ключ страны (между методами передается как необязательный)

Метод GetSPOPageByKey

Данный метод осуществляет постраничную загрузку цен.

Список принимаемых параметров:

• SpoKey – ключ СПО
• minPriceKey – ключ цены, начиная с которой осуществлять выгрузку
• pageSize – количество записей получаемых за один запрос

Метод GetSPOByKey

Данный метод осуществляет загрузку цен.
Запись полученных результатов производится в таблицы FileRepos и FileHeaders в том случае, если у пользователя, который осуществляет загрузку цен указаны права Insert, Delete, Select и Update. Права указываются в свойствах таблиц в разделе Permissions.

Список принимаемых параметров:

• SpoKey – ключ СПО

Метод GetSPOByKey_DC

Данный метод осуществляет загрузку цен (только для динамического ценообразования!).

Список принимаемых параметров:

• SpoKey – ключ СПО
• calcKeyFrom, calcKeyTo – начальный и конечный ключи цен, возвращаемые методом (колонка TP_CalculatingKey из таблицы TP_Prices для актуальных цен и колонка TPD_CalculatingKey из таблицы TP_PriceDeleted для удаленных цен).

Метод GetSPOByKeyCompressed

Данный метод осуществляет загрузку цен (данные возвращаются в сжатом виде).

Запись полученных результатов производится в таблицы FileRepos и FileHeaders в том случае, если у пользователя, который осуществляет загрузку цен указаны права Insert, Delete, Select и Update. Права указываются в свойствах таблиц в разделе Permissions.

Список принимаемых параметров:

• SpoKey – ключ СПО

Метод GetSPOByKeyCompressed_DC

Данный метод осуществляет загрузку цен (данные возвращаются в сжатом виде). Только для динамического ценообразования!

Запись полученных результатов производится в таблицы FileRepos и FileHeaders в том случае, если у пользователя, который осуществляет загрузку цен указаны права Insert, Delete, Select и Update. Права указываются в свойствах таблиц в разделе Permissions.

Список принимаемых параметров:

• SpoKey – ключ СПО
• calcKeyFrom, calcKeyTo – начальный и конечный ключи цен, возвращаемые методом (колонка TP_CalculatingKey из таблицы TP_Prices для актуальных цен и колонка TPD_CalculatingKey из таблицы TP_PriceDeleted для удаленных цен).

Метод GetSPOPageByKeyCompressed

Данный метод возвращает СПО по ключу постранично в формате .ZIP.

Список принимаемых параметров:

• spoKey – ключ СПО
• minPriceKey – ключ цены, начиная с которой осуществлять выгрузку
• pageSize – количество записей получаемых за один запрос (не больше 5000)

Метод GetStopSalesAndQuotes

Данный метод возвращает информацию по квотам.

Список принимаемых параметров:

• сheckPoint – дата, начиная с которой, выгружается информация по квотам и их изменениям

Метод GetHotelKeys

Данный метод возвращает список отелей, по которым имеются туры.

Список принимаемых параметров:

• сheckPoint – дата, начиная с которой, выгружаются ключи по созданным или измененным отелям до настоящего момента
• cityKey – ключ города

Возвращаемые значения:

• список отелей в формате: <Hotels><Hotel key name></Hotel></Hotels>

Метод GetHotelQuotes

Данный метод возвращает список отелей и квот (наличие и количество мест) по ним. Количество мест в квоте отображается только при включенной настройке isShowQuantity

Список принимаемых параметров:

• hotelKey – ключ отеля
• сheckPoint – дата, начиная с которой, выгружаются ключи по отелям
• days – количество дней, на которые метод возвращает результат

Метод GetStopSalesAndQuotesByHotels

Данный метод всегда возвращает информацию по квотам и Stop-Sale по дате по конкретному ключу отеля, вне зависимости от установленного значения настройки isShowQuantity.

Список принимаемых параметров:

• сheckPoint – дата, начиная с которой, выгружается информация по квотам и их изменениям
• hotelKey – ключ отеля

Метод GetFlightQuotes

Данный метод возвращает расписание и квоты (наличие и количество мест) по авиаперелетам. Количество мест в квоте отображается только при включенной настройке isShowQuantity.

Список принимаемых параметров:

• cityFrom – город вылета
• cityTo – город прилета
• CheckPoint – дата вылета

Метод GetCountries

Данный метод возвращает список стран, по которым имеются туры. В каждой стране – список городов, на которые имеются квоты.

Список принимаемых параметров:

• параметров нет

Возвращаемые значения:

• список стран в формате: <Countries><Country key name><Cities><City key name></City></Cities></Country></Countries>

Метод GetValidTourListWithoutValidation

Данный метод возвращает список туров с отключенной валидацией.

Список принимаемых параметров:

• параметров нет

Метод ValidatePriceServices

Данный метод проверяет валидность услуг на даты заездов.

Список принимаемых параметров:

• параметров нет

Метод GetAgencies

Данный метод возвращает список агентств по определенному фильтру.

Список принимаемых параметров:

• параметров нет

Метод GetReferences

Данный метод возвращает справочники по фильтрам. Список принимаемых параметров:

• queryType - идентификатор запроса
• param - ключ фильтра

Метод GetSimpleDogovorsBronni

Данный метод возвращает список путевок в формате Бронни. Список принимаемых параметров:

• agency - ключ туристического агентства
• dateFrom - дата с которой будут выводится созданные путевки
• dateTo - дата по которое будет выводится список созданных путевок

Метод GetBookingInfo

Данный метод возвращает информацию о путевке.

Список принимаемых параметров:

• XML документ, содержащий заявку, в которой указаны дата заезда, ключ агентства, ключ рассчитанного тура, туристы.

Возвращаемое значение - XML документ, содержащий договор.

Метод GetStopSalesAndQuotes2

Данный метод возвращает полную информацию по квотам (наличие мест, количество мест, стопы, запреты на заезд), по всему услугам в туре

Список принимаемых параметров:

• сheckPoint – дата, начиная с которой, выгружается информация по квотам и их изменениям. Дата создания квоты или дата последнего изменения должны быть больше или равны дате выгрузки информации.

Методы бронирования

Метод GetAgreementCredentials

Данный метод возвращает ключ агентства по логину и паролю онлайн пользователя.

Список принимаемых параметров:

• agencyLogin – имя пользователя
• agencyPassword – пароль пользователя

Метод CheckBooking

Данный метод осуществляет проверку возможности бронирования рассчитанного прайса. Возвращает услуги по прайсу, их статусы (есть или нет мест), актуальную цену путевки.

Список принимаемых параметров:

• XML документ, содержащий заявку, в которой указаны дата заезда, ключ агентства, ключ рассчитанного тура, туристы.

Возвращаемое значение - XML документ, содержащий договор.

Метод CreateBooking

Данный метод осуществляет бронирование путевки по рассчитанному прайсу. Возвращает услуги по прайсу, их статусы (есть или нет мест), актуальную цену путевки.

Список принимаемых параметров:

• XML документ, содержащий заявку, в которой указыны дата заезда, ключ агентства, ключ рассчитанного тура, туристы.

Возвращаемое значение - XML документ, содержащий договор.

Метод CancelAgreement

Данный метод отправляет запрос на аннуляцию путевки.

Список принимаемых параметров:

• agencyId - ключ туристического агентства
• agreementNumber – ключ договора путевки

Метод GetAgreementsByNumber

Данный метод возвращает информацию по забронированным путевкам.

Список принимаемых параметров:

• agency - ключ туристического агентства
• codes – ключ договора

Возвращаемое значение - XML документ, содержащий ключ агентства и коды забронированных путевок.

Метод GetAgreementsByKeys

Данный метод возвращает список путевок по ключам.

Список принимаемых параметров:

• codes - ключ договора

Метод GetAgreementsByCode

Данный метод возвращает список путевок по кодам.

Список принимаемых параметров:

• agency - ключ агентства
• codes - номер путевки

Метод GetSimpleDogovorsByCreateDates

Данный метод возвращает список путевок по датам создания. Список принимаемых параметров:

• dateFrom - дата с которой будут выводится созданные путевки
• dateTo - дата по которое будет выводится список созданных путевок
• agency - ключ агентства
• BTKey - значение из таблицы tbl_Dogovors

Метод GetDogovorsByPartnerGroup

Данный метод возвращает список путевок по датам создания Список принимаемых параметров:

• dateFrom - дата с которой будут выводится созданные путевки
• dateTo - дата по которое будет выводится список созданных путевок
• agencyGroupKey - ключ группы партнеров, в которую входит партнер, оформивший путевку

Метод проверки работы

Метод GetVersion

Данный метод возвращает версию базы данных Мастер-Тур и текущей бизнес-логики сервиса

Список принимаемых параметров:

• login – имя пользователя
• password – пароль пользователя

Возвращаемое значение - XML документ, содержащий информацию о версии базы данных программного комплекса Мастер-Тур и версию бизнеслогики, используемую web-сервисом.

Авторизация при использовании web-сервиса

При работе с web-сервисом TourML перед запросом данных требуется произвести авторизацию. Web-сервис позволяет использовать несколько методов авторизации, доступные для использования из различных программных средств.

Основным методом авторизации является использование WSE (Web Services Enhancements). По умолчанию web-сервис использует именно этот механизм авторизации. Более детально о механизме безопасности WSE можно прочитать по следующей ссылке:

http://msdn.microsoft.com/en-us/library/aa894200.aspx

Для упрощения работы c web-сервисом предусмотрен механизм упрощенной авторизации, позволяющий производить работу с web-сервисом без использования механизма WSE. Данный вариант авторизации является опциональным и должен быть разрешен явным образом через установку настройки в конфигурационном файле web-сервиса. Более детально о механизме упрощенной авторизации будет рассказано ниже.

Авторизация с использованием WSE

При работе со средой разработки Microsoft Visual Studio в секцию Reference проекта необходимо добавить ссылку на библиотеку Microsoft.Web.Services2.dll

Ниже приведен пример кода на языке c#, позволяющий создать подключение к веб-сервису. Обратите внимание на то, что после автоматического создания прокси-класса с помощью MS Visial Studio, необходимо внести изменения в сгенерированный код.

Нужно указать в качестве базового класса следующий класс:

Microsoft.Web.Services2.WebServicesClientProtocol 

Более подробно можно ознакомится с авторизацией по следующей ссылке:

http://msdn.microsoft.com/en-us/library/ms996952.aspx

Пример работа с WSE авторизацией при использовании библиотекой WSE

SoapContext reqCtx = sp.RequestSoapContext;

UsernameToken tok = new UsernameToken("login", "password",  asswordOption.SendHashed);
reqCtx.Security.Tokens.Add(tok);
MessageSignature sig = new MessageSignature(tok);
sig.SignatureOptions = SignatureOptions.IncludeAction;
reqCtx.Security.Elements.Add(sig);
ServiceClient.ServiceProxy.Version ver = sp.GetVersion();

Пример работа с WSE авторизацией без использовании библиотеки WSE

Передача запроса в виде XML

1.Создание дайджеста пароля:

DateTime dt = DateTime.Now.ToUniversalTime();
//Создание строк nonce, passwordDigest
private void GetPasswordDigest(out string nonce, out string digest, DateTime dt)
{
DateTime created = dt;
//строка, сгенеренная случайным образом. Внимание! Сервис не
//даст одну и ту же строку передавать несколько раз.
byte[] baNonce = new byte[20];
byte[] baCreated;
Random r = new Random(Environment.TickCount);
r.NextBytes(baNonce);
string cr = String.Format("{0:yyyy-MM-ddTHH:mm:ssZ}", created);
baCreated = Encoding.UTF8.GetBytes(cr);
string password = "pass";
byte[] baPassword = Encoding.UTF8.GetBytes(password);
int baDigestLength = baNonce.Length + baCreated.Length + baPassword.Length;
byte[] baDigest = new byte[baDigestLength];
Array.Copy(baNonce, 0, baDigest, 0, baNonce.Length);
Array.Copy(baCreated, 0, baDigest, baNonce.Length, baCreated.Length);
Array.Copy(baPassword, 0, baDigest, baNonce.Length + baCreated.Length, baPassword.Length);
byte[] hash = SHA1Managed.Create().ComputeHash(baDigest);
nonce = Convert.ToBase64String(baNonce);
digest = Convert.ToBase64String(hash);
}

2.Подпись XML. Обязательно хоть что-нибудь должно быть подписано. Для упрощения задачи можно подписать только wsa:Action.

const string wsaNS = "xmlns:wsa=\"http://schemas.xmlsoap.org/ws/2004/03/addressing\";
const string wsuNS = "xmlns:wsu=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd\";
string action = http://tourml.ru/service/2004-08-13/products/GetVersion;
//wsa:Action в канонической форме (с нужными namespace'ами) запишится так 
string strToSign = String.Format("<wsa:Action {0} {1} wsu:Id=\"Id-622cdaf1-1721-4fff-8235-7ace4e4549ab\">{2}</wsa:Action>",wsaNS,wsuNS,action);
//DigestValue - считаем от этой строки Base64(SHA1())
signatureInfo += String.Format("<ds:DigestValue>{0}</ds:DigestValue>", GetBase64SHA1(strToSign));

3.SignatureValue - подпись всех элементов SignatureInfo, которые также канонизированы по стандарту xml-exc-c14n.

header += String.Format("<SignatureValue>{0}</SignatureValue>", GetBase64SHA1(signatureInfo));

Более подробную справочную информацию обо всех этапах формирования XML-запроса для работы с WSE-авторизацией можно получить по следующим ссылкам:

http://www.w3.org/TR/xml-exc-c14n/
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf
http://www.xml.com/pub/a/2001/08/08/xmldsig.html
http://www.citforum.ru/security/internet/web_service/
http://www.faqs.org/rfcs/rfc3075.html

Пример работа без использования WSE авторизации

С целью упрощения авторизации на веб-сервисе (для закачки информации по турам и квотам) из языков программирования типа PHP, в сервисе предусмотрена возможность передачи логина и пароля через заголовок WebRequest и параметрами через POST запрос. Данная возможность является опциональной и включается с помощью настройки в конфигурационном файле web-сервиса.

<add key="allowSimpleAuth" value="true"/>

Внимание! Настройка добавляется в web.config web-сервиса

Запрос с использованием GET

При вызове метода веб-сервиса можно в качестве параметров передать информацию о логине и пароле

Login=test1&Password=qUqP5cyxm6YcTAhz05Hph5gvu9M=

где в качестве пароля выступает Base64(SHA1(‘пароль’, true))

Запрос с использованием SOAP

В каждом методе веб-сервиса есть описание заголовка и Soap-запроса к этому методу.

Например, для метода GetValidTourList: Заголовок:

POST /Service.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: http://tourml.ru/service/2004-08-13/products/GetValidTourListFrom

Для передачи логина и пароля в заголовок добавляются следующие элементы:

Login      : логин 
Password: Base64(SHA1(пароль))

Soap запрос:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetValidTourListFrom xmlns="http://tourml.ru/service/2004-08-13/products">
      <checkPoint>dateTime</checkPoint>
    </GetValidTourListFrom>
  </soap:Body>
</soap:Envelope>

Пример упрощенной авторизации на языке c#

const string xsiNS = "xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"";
const string xsdNS = "xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"";
const string soapNS = "xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\";

string message = "<?xml version=\"1.0\" encoding=\"utf-8\"?>";
message += String.Format("<soap:Envelope {0} {1} {2}>", xsiNS, xsdNS, soapNS);
message += "<soap:Body><GetValidTourListFrom xmlns=\"http://tourml.ru/service/2004-08-13/products\"><checkPoint>2009-01-06</checkPoint></GetValidTourListFrom></soap:Body></soap:Envelope>";

HttpWebRequest wr = (HttpWebRequest)WebRequest.Create("http://localhost:3153/service.asmx");
wr.Method = "POST";
wr.ContentType = "text/xml; charset=utf-8";

//Прописываем Soap запрос
Stream connectionStream = wr.GetRequestStream();
StreamWriter sw = new StreamWriter(connectionStream, Encoding.UTF8);
sw.Write(message);
sw.Close();
//Прописываем логин и пароль
wr.Headers.Add("Login", "test");
wr.Headers.Add("Password", Convert.ToBase64String(SHA1Managed.Create().ComputeHash(Encoding.UTF8.GetBytes("test"))));
wr.Headers.Add("SOAPAction", "http://tourml.ru/service/2004-08-13/products/GetValidTourListFrom");
WebResponse resp = wr.GetResponse();

Вызов методов веб-сервиса. Возможные проблемы при авторизации

Если метод вызывается через браузер и если Вы используете браузер Internet Explorer, то при возникновении любой ошибки на этапе авторизации возвращается HTTP 500 - Внутренняя ошибка сервера. Internet Explorer скрывает текст возникшей ошибки. В данном случае стоит воспользоваться каким-либо альтернативным браузером (Opera, Mozilla), где сообщение от сервера выведется на экран. Также текст ошибок можно получать, воспользовавшись логгерами Http, которые отслеживают запросы\ответы по этому протоколу. Логгерами можно воспользоваться также при обращениях к сервису с клиента.

Запрос	Возникшая ошибка	Пояснение
GetStopSalesAndQuotes(2009-05-05)	System.Data.SqlClient.SqlException: Cannot open database AvalonTest requested by the login. The login failed. Login failed for user 'ESYSTEM'. at System.Data.SqlClient.SqlInternalConnection.OnError(SqlException exception, Boolean breakConnection) at System.Data.SqlClient.TdsParser.ThrowExceptionAndWarning(TdsParserStateObject stateObj) at System.Data.SqlClient.TdsParser.Run(RunBehavior runBehavior, SqlCommand cmdHandler, SqlDataReader dataStream, BulkCopySimpleResultSet bulkCopyHandler, TdsParserStateObject stateObj) at System.Data.SqlClient.SqlInternalConnectionTds.CompleteLogin(Boolean enlistOK)…	Проблема на стороне оператора. Веб-сервис не может получить доступ к базе данных под учетной записью, указанной в web.config веб-сервиса.
GetSPOPageByKey(253,0,5000)	System.Data.SqlClient.SqlException: The transaction log for database 'AvalonTest' is full. To find out why space in the log cannot be reused, see the log_reuse_wait_desc column in sys.databases	Проблема на стороне оператора. Требуется передать указанную ошибку администратору базы данных оператора.
GetSPOPageByKey(253,0,5000)	System.Web.Services.Protocols.SoapException: System.Web.Services.Protocols.SoapException: Серверу не удалось обработать запрос. ---> System.Data.SqlClient.SqlException: Could not find stored procedure 'sp_GetPricePage'. в System.Data.SqlClient.SqlConnection.OnError(SqlException exception, Boolean breakConnection) в System.Data.SqlClient.SqlInternalConnection.OnError(SqlException exception, Boolean breakConnection) в System.Data.SqlClient.TdsParser.ThrowExceptionAndWarning(TdsParserStateObject stateObj) в System.Data.SqlClient.TdsParser.Run(RunBehavior runBehavior, SqlCommand cmdHandler, SqlDataReader	В базе данных оператора отсутствует хранимая процедура 'sp_GetPricePage'. Проблема на стороне оператора. Требуется передать указанную ошибку администратору базы данных оператора. По поводу обновления или установки данной процедуры оператор может связаться со службой поддержки компании Мегатек.
GetSPOPageByKey(253,0,5000) (При вызове из браузера)	System.Web.Services.Protocols.SoapException: Username was not specified	Указанный метод требует указание логина\пароля. И не может быть вызван из браузера напрямую.
GetSPOPageByKey(253,0,5000)	System.Exception: WSE authorization error 565 Или System.Web.Services.Protocols.SoapHeaderException: Microsoft.Web.Services2.Security.SecurityFault: The security token could not be authenticated or authorized ---> System.ArgumentNullException: Значение не может быть неопределенным. Имя параметра: secret	Не удалось авторизоваться с переданным логином\паролем.
GetSPOPageByKey(253,0,5000)	System.Web.Services.Protocols.SoapHeaderException: Microsoft.Web.Services2.Security.SecurityFault: The security token could not be authenticated or authorized ---> System.Exception: Password has expired.	Истек срок действия переданного логина.
GetStopSalesAndQuotes(2009-05-05)	System.Web.Services.Protocols.SoapException: You are not allowed to use this function	С переданным логином\паролем нельзя вызвать эту функцию. В списке групп функций, доступных по этому логину, отсутствует группа с вызываемой процедурой.

Функции загрузки информации о турах

Формат TourML

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

Формат TourML был разработан для того, чтобы стать единым “языком”, который будут понимать различные системы и программные средства, работающие в туристической сфере.

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

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

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

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

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

• 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 может содержать информацию о квотах или о ценах какого-либо тура. Информация о ценах содержится в элементах packet, который состоит из 3-х частей:

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

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

Порядок работы с web-сервисом

Web-сервис TourML позволяет организовать полный цикл взаимодействия с программным комплексом Мастер-Тур – от получения цен до бронирования и аннуляции заявок. Ниже рассмотрен полный цикл работы с web-сервисом.

Получение списка доступных спецпредложений

Первым шагом при работе с web-сервисом является получение списка спецпредложений, выставленных оператором для просмотра в онлайне. Эта операция может быть выполнена с помощью двух методов:

• GetValidTourList
• GetValidTourListFrom

Результат выполнения данных методов - TourML документ, в котором содержится список доступных СПО, а также их актуальность.

Разделы документа, которые будут заполнены: В разделах packet (которых будет по количеству доступных СПО) будет заполнен элемент packetHeader, содержащий информацию о СПО и количестве цен.

 
 <sources xmlns="http://tourml.ru/products/2004-04-19">
    <source name="ООО МегаТур" uri="http://www.mega tour.com/">
      <quotaServices />
      <packets>
        <packet>
          <packetHeader>
            <tour key="311" name="Test Tour" tourTypeKey="5" countryKey="90">
            </tour>
            <spo key="467" for="byPerson" validFrom="2009-01-11" validTo="2009-12-29" currencyKey="1" state="Created" issue="2009-01-10T14:12:00.0000000+03:00">
              <dates />
              <comment />
            </spo>
            <spoInfo xmlns="http://www.megatec.ru/tourml/extensions">
              <priceQuantity>20520</priceQuantity>
            </spoInfo>
          </packetHeader>
          <services>
            <hotelServices />
            <flightServices />
            <excursionServices />
            <transferServices />
            <cruiseServices />
            <extraServices />
          </services>
          <prices />
        </packet>
        <packet>
         ........
        </packet>

При выгрузке информации об СПО будут заполнены только те справочники, на которые есть ссылки в элементах tour и spo, а именно: страна, валюта, тип тура.

<references xmlns="http://tourml.ru/products/2004-04-19">
   <countries>
     <country key="86" name="Турция" nameLat="TURKEY" code="TR" />
     <country key="90" name="Австрия" nameLat="AUSTRIA" code="AT" />
     <country key="9" name="Египет" nameLat="Egypt" code="EG" />
   </countries>
   <resorts />
   <cities />
   <categories />
   <hotels />
   <buildings />
   <airlines />
   <airports />
   <aircrafts />
   <flights />
   <roomTypes />
   <roomLocations />
   <roomViews />
   <roomCategories />
   <roomDescriptions />
   <roomAccomodations />
   <rooms />
   <serviceClasses />
   <serviceDescriptions />
   <serviceDescriptions1 />
   <serviceDescriptions2 />
   <transfers />
   <excursions />
   <transports />
   <cabines />
   <ships />
   <boardings />
   <currencies>
     <currency key="1" name="US Dollar" nameLat="US Dollar" code="$" />
   </currencies>
   <tariffs />
   <tourTypes>
     <tourType key="32" name="Сложный тур" nameLat="Complex tour" />
     <tourType key="5" name="Специальное предложение" nameLat="Special offer" />
     <tourType key="0" name="Не определен" nameLat="Not detected" />
   </tourTypes>
 </references>

Загрузка цен по конкретному спецпредложению

На втором шаге с помощью метода GetSPOPageByKey выполняется загрузка цен по конкретному спецпредложению. Метод принимает следующие параметры:

• SpoKey – ключ СПО
• minPriceKey – ключ цены, начиная с которой осуществлять выгрузку
• pageSize – количество записей получаемых за один запрос (не больше 5000)

Внимание!

Количество записей (pageSize) рекомендуется брать не более 5000, поскольку это значение гарантирует приемлемую производительность сервиса.

Выгрузка страницы с 5000 ценами занимает порядка 5-20 секунд, в зависимости от производительности сервера и его текущей загрузки.

Пример

Пусть требуется выгрузить СПО с ID = 25. Из результатов метода GetValidTourList мы знаем, что в данном СПО 26430 цен.

Первый запрос мы отправляем с параметрами 25, 0, 5000. В качестве ответа сервиса получим TourML, в котором будут описаны первые 5000 прайсов указанного СПО.

Чтобы выполнить загрузку следующей страницы нам нужно передать в качестве параметров 25, maxPriceID, 5000, где maxPriceID - максимальный ID цены которая вернулась в предыдущем запросе.

В ответе сервиса ID прайсов возвращаются в тегах date, сгруппированных по цене,

<serviceSet ids="_10818">
   <price gross="10990">
     <date key="12575" from="2014-05-24" to="2014-05-24"/>
   </price>
</serviceSet>

где:

• ids - ключи услуги, поле TL_TSKey из таблицы TP_SERVICELISTS
• price gross - цена, поле TP_Gross из таблицы TP_PRICES
• date key - ключ цены, поле TP_Key из таблицы TP_PRICES

Чтобы найти maxPriceID нужно перебрать все теги date и выбрать тот, у которого атрибут key максимальный. В последних версиях сервиса доступен атрибут lastKey у элемента loadTime, в котором указан maxPriceID. Если lastKey=-1, то загрузка окончена и этот TourML - последняя страница.

<header name="" uri="http://notfound.net">
    <loadTime timeValue="100" lastKey="87546090" xmlns="http://www.megatec.ru/tourml/extensions" /> 
</header>

Таким образом, чтобы выгрузить весь тур (26430 цен) необходимо отправить 6 запросов. Последний запрос также можно отправить с pageSize = 5000. Сервис вернет оставшиеся 1430 цен.

Загрузка информации о квотах

Для получения информации о квотах необходимо использовать метод GetStopSalesAndQuotes.

Внимание!

В результат работы метода 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>

В разделе

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

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

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

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

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

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

<flightService flightKey="526" tariffKey="89">
  <stopsales>
    <stopsale dateFrom="2009-05-01" dateTo="2009-05-02" typeVisit="byPeriod" status="Modified" />
  </stopsales>
</flightService>

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

<flightService flightKey="526" tariffKey="89">
  <quotas> 
    <quota date="2009-05-05" places="125" freeAccess="many" typeQuantity="byPerson" typeVisit="byPeriod"   status="Created" duration=”5,6” /> 
  </quotas> 
</flightService>

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

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

Остальные атрибуты всегда остаются такими 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" /> 
</flightService>

на заданное число есть 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" duration=”5,6” /> 
  </quotas>
</hotelService>

• buildingKey - ключ гостиницы
• roomTypeKey - тип комнаты (HotelRoom.RoomKey)
• roomDescriptionKey - категория комнаты (HotelRoom.RoomsCategoryKey)
• typeQuantity="byRoom" - квота предоставляется на комнату
• Атрибут duration – продолжительность, на которую заведена квота. Если квота без продолжительности, то атрибут не выводится.

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

При использовании метода GetStopSalesAndQuotes2.

<hotelService buildingKey="3233" roomDescriptionKey="20" roomTypeKey="1"> 
  <quotas>
    <quota status="Modified" typeQuantity="byRoom" typeVisit="byPeriod" uniqueKey="2778" agentKey="0" freeAccess="many" places="20" date="2013-10-01" quoteType="0" checkInStop="false"/>
    <quota status="Modified" typeQuantity="byRoom" typeVisit="byPeriod" uniqueKey="2779" agentKey="0" freeAccess="many" places="20" date="2013-10-02" quoteType="0" checkInStop="true"/>
  </quotas>
</hotelService>

• checkInStop - атрибут, отвечающий за наличие запрета на заезд. Принимает значение true - запрет на заезд выставлен, false - запрет на заезд не выставлен.

<hotelService buildingKey="3233" roomDescriptionKey="20" roomTypeKey="1">
  <stopsales>
    <stopsale status="Modified" typeVisit="byPeriod" uniqueKey="22" dateFrom="2013-11-02" dateTo="2013-11-02" quoteType="1"/>
    <stopsale status="Modified" typeVisit="byPeriod" uniqueKey="20" dateFrom="2013-11-09" dateTo="2013-11-09" duration="2" quoteType="1"/>
    <stopsale status="Modified" typeVisit="byPeriod" uniqueKey="28" dateFrom="2013-11-11" dateTo="2013-11-11" quoteType="0"/>
  </stopsales>
</hotelService>

• duration - продолжительность услуги. Атрибут не отображается, если он равен "0".
• quoteType - тип Stop-Sale. 1 - частный Stop-Sale. 0 - общий Stop-Sale.

Информация о квотах и Stop-Sale!
quoteType указанный в тэге </quotas>...</quotas> указывают на тип квоты.
quoteType указанный в тэге <stopsales>...</stopsales> указывают на тип Stop-Sale.

Загрузка информации по авиаперелетам (расписание и квоты)

Для получения информации по авиаперелетам необходимо использовать метод GetFlightQuotes.

GetFlightQuotes(int cityFrom, int cityTo, DateTime checkPoint)

Возвращает информацию по авиаперелетам (расписание и квоты) с городом вылета cityFrom, городом прилета cityTo, с датой вылета равной CheckPoint.

Возвращается расписание на все перелеты, на которые есть вылеты на будущие даты, по тарифам, указанным в настройке tarifsToLoadFlightQuotes.

На даты вылетов по указанным тарифам также должна выводиться информация по квотам (число свободных для бронирования мест). В данном методе эта информация в настоящее время не заполняется.

Проверка бронирования и бронирование

Перед бронированием какого-либо обсчитанного тура, требуется произвести проверку бронирования с помощью функции CheckBooking. Результатом такой проверки является xml документ, содержащий в себе информацию по услугам тура, статусу этих услуг, цене. В таком же формате приходят и ответы на запросы CreateBooking.

Запрос на проверку бронирования\бронирование (booking) состоит из 3-х частей:

• Header
• Packets
• Persons

Раздел Header

Раздел заполняется следующим образом:

<header id="int" checkin="2009-10-29" buyerPerson="1" mainPerson="1" agreementKey="0"> 
<comment>Данная заявка выполнена для проверки работы сервиса. Саму заявку в работу оправлять не нужно</comment> 
 </header>

Где:

• id - agencyID из функции GetAgreementCredentials (вызов этой функции будет описан в разделе порядок работы)
• checkin - дата, на которую производится проверка (дата, на которую планируется заезд по проверяемой цене, указанной в <calculated key="00000000" />).

Даты, на которую действует указанная цена, можно узнать из TourML при загрузке цен оператора.

<date key="00000000" from="2009-10-29" to="2009-10-30" />

Если в указанную дату нет заезда, то вернется сообщение об ошибке (Could not find price key 00000000).

Раздел Packets

В разделе Packets передаются пакеты, которые будут бронироваться. В элементе <calculated> в атрибуте key передается ключ цен 044B

<packet id="_1"> 
  <calculated key="00000000" /> 
</packet>

У самого пакета есть атрибут id, на который будут ссылаться туристы при привязке.

Раздел Persons

В разделе Persons передается информация о клиентах

<person key="1" sourceKey="0" packets="_1" firstNameRus="TEST" lastNameRus="TEST" firstNameLat="TEST" lastNameLat="TEST" sex="male" birthday="1982-03-03" nationalityRus="" nationalityLat="" isTourist="true">
 <contacts>
  <phones /> 
  <addresses /> 
  <emails /> 
  </contacts>
 <passports>
  <passport type="foreign" series="1111" number="111111111" emittedBy="ОВД" emittedWhen="1990-01-01" validTo="2007-03-03" /> 
  </passports>
</person>

У элемента person есть следующие атрибуты:

• key="1" — уникальный ключ клиента. На него ссылаются в атрибутах buyerPerson="1" mainPerson="1" в Header
• sourceKey="0" — Ключ туриста у внешней системы (не используется)
• packets="_1" — id пакета, к которому будет привязан турист (турист привязывается ко всем услугам этой рассчитаной цены)
• firstNameRus="TEСT" — Имя клиента русскими буквами
• lastNameRus="TEСT" — Фамилия клиента русскими буквами
• firstNameLat="TEST" — Имя клиента латиницей
• lastNameLat="TEST" — Фамилия клиента латиницей
• sex="male" — пол клиента. Может принимать значения male, female, child, infant
• birthday="1982-03-03" — дата рождения клиента
• nationalityRus="" - национальность (русскими буквами)
• nationalityLat="" - национальность (латиницей)
• isTourist="true" — признак является ли клиент туристом

В раздел паспортов необходимо добавить хотя бы один паспорт. Элемент паспорт

• type="foreign" — тип паспорта foreign (загран), national (национальный)
• series="1111" — серия
• number="111111111" — номер
• emittedBy="ОВД" — Кем выдан
• emittedWhen="1990-01-01" — Когда выдан
• validTo="2007-02-02" — Дата окончания действия

Все описанные данные о клиентах являются обязательными!
Если Вы бронируете тестовую путевку в рабочую базу оператора, ОБЯЗАТЕЛЬНО у туристов   
задавайте имя-фамилия ТЕСТ-ТЕСТ
Если бронируйте реальную путевку, ОБЯЗАТЕЛЬНО указывайте корректные данные.

В качестве ответа на проверку бронирования\бронирование возвращается XML документ с информацией о путевке, которая приведена в разделе agreement. Этот раздел состоит из четырех частей:

• header
• packets
• persons
• penaltyConditions

В заголовке (header) приведена общая информация о путевке, характеризуемая следующими атрибутами:

• checkin — дата заезда (дата на которую идет проверка бронирования)
• buyerPerson — ключ клиента, который является покупателем
• mainPerson — ключ клиента, который является главным туристом
• agreementKey — ключ путевки (при проверке бронирования < 0, при бронировании реальный ключ из базы)
• agreementCode — код путевки (при проверке бронирования < 0, при бронировании реальный код из базы)
• country — Название страны тура
• city — Название города тура
• days — продолжительность тура
• quantity — количество туристов
• price — цена (туристу к оплате), включает в себя комиссию
• pricePaid — уже оплачено
• currency — валюта путевки
• creationDate — текущая дата
• payUntil — дата, до которой нужно произвести оплату
• status — статус брони
• errorStatus — статус ошибки
• reasonRus — в случае ошибки или отказа бронирования здесь указываются причины
• reasonLat — в случае ошибки или отказа бронирования здесь указываются причины (латиницей)
• commission — комиссия агентству

Статус'	Расшифровка статуса
Общие статусы
Ок	Заявка подтверждена
Waitlist	Заявка в листе ожидания
rejected	Бронирование отклонено
Annulled	Путевка аннулирована
Error	Ошибка
Waitcancel	В ожидании отмены по пользовательскому запросу
Cancel	Не используется
Статусы ошибок
Unknown	Передается во всех остальных случаях
agencyNotFound	Не найдено агентство по логину/паролю
priceNotFound	Не найден запрашиваемый прайс

Для того, чтобы определить произошла ошибка или нет необходимо проверить дополнительный атрибут reasonRus, reasonLat, в которых передаются дополнительные комментарии.

Например, в ответе в разделе Header приходит следующее значение:

status="waitlist" errorStatus="unknown"

• status - это статус заявки (путевки).
• waitlist — означает что можно бронировать под запрос,
• ок - подтверждено
• rejected - в случае если бронирование не возможно по каким-то причинам.
• errorStatus особой функциональной нагрузки не несет

Если какая-то ошибка произошла или по каким-то причинам нельзя бронировать, то в атрибутах reasonRus и reasonLat указывается причина ошибки:

status="rejected" errorStatus="unknown" reasonRus="Бронирование выполнить нельзя т.к. отсутствует квота на услугу А_П::Москва/Дубровник/LLM9351, DME-DBV, 07:00-08:20/Y Эконом класс/. " reasonLat="Booking could
not be done, because quota on service А_П::Москва/Дубровник/LLM9351, DME-DBV, 07:00-08:20/Y Эконом класс/ is absent. 

Элемент Packets содержит пакеты, помеченные атрибутом id, состоящие из наборов услуг, разбитых на группы (аналогично тому, как разбивались варианту услуг в TourML):

• hotelServices
• flightServices
• excursionServices
• transferServices
• cruiseServices
• extraServices

Каждая из услуг описывается набором атрибутов, например:

<hotelService key="-12" name="HOTEL::АНТАЛИЯ/_NO_CENDER-4*,7 ночей/Double(Standart),Взр./AI Всё включено/" dayBeg="1" nights="7" days="7" men="2" reasonRus="Места есть" reasonLat="Places available" 
sourceKey="0" buildingKey="1037" roomKey="1113" mealKey="38" />

Атрибуты, общие для всех типов услуг:

• key – ключ услуги (при реальном бронировании ключ услуги из услуг договора)
• name — наименование услуги
• dayBeg — день начала предоставления услуги
• nights — продолжительность услуги в ночах
• days — продолжительность услуги в днях
• men — количество человек, пользующихся услугой
• reasonRus - Объяснение причины, по которой услуга не доступна при бронировании (например, нет мест)
• reasonLat - То же самое, что reasonRus, но на английском
• sourceKey - Идентификатор услуги у внешней системы (не используется)

Дополнительные атрибуты, для различных типов услуг:

Услуги проживания(hotelService):

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

Услуги авиаперелета(flightService):

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

Услуги экскурсии(excursionServices):

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

Услуги трансфера(transferService):

• transferKey – ссылка на справочник трансферов
• transportKey – ссылка на справочник транспортов

Услуги круиз(cruiseServices):

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

Остальные услуги(extraService):

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

В разделе Persons передается информация о клиентах. Формат данных такой же, как описан выше для запроса. Ответ функции CreateBooking отличается от ответа функции CheckBooking только тем, что при создании путевки возвращаются реальные ключи из базы.

Получение ключа агентства (функция GetAgreementCredentials)

В функцию бронирования и проверки бронирования необходимо передавать ключ агентства. Для получения ключа необходимо воспользоваться функцией GetAgreementCredentials.

В качестве входных параметров в функцию передаются логин и пароль web–пользователя агентства (логин-пароль под которым агентство заходит в Мастер-Веб).

Результатом выполнения этого метода будет xml-документ следующего вида

<RegisterAgencyResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <credentials agencyId="10795" agreementNumber="w2435" expirationDate="2009-12-11T00:00:00" xmlns="http://tourml.ru/agencies/2004-09-28" />
</RegisterAgencyResponse>

где,

• agencyId – id агентства, к которому принадлежит указанный пользователь.
• AgreementNumber — номер договора с агентством
• ExpirationDate - дата истечения договора.

Метод возвращает тот номер договора, у которого текущая дата попадает между начальной и конечной датой договора, есть признак Договор по умолчанию, или дата обновления самая поздняя.

Если такого логина не существует, то вернется сообщение об ошибке

<RegisterAgencyResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <credentials agencyId="0" expirationDate="0001-01-01T00:00:00" xmlns="http://tourml.ru/agencies/2004-09-28" />
  <error errorStatus="loginNotFound" errorDescriptionRus="Логина test не существует." errorDescriptionLat="The login test  does not exist." xmlns="http://tourml.ru/agencies/2004-09-28" />  
</RegisterAgencyResponse>

Если неправильно указан пароль, то возвращается следующее сообщение об ошибке:

<RegisterAgencyResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <credentials agencyId="0" expirationDate="0001-01-01T00:00:00" xmlns="http://tourml.ru/agencies/2004-09-28" />
  <error errorStatus="passwordIncorrect" errorDescriptionRus="Неверный пароль." errorDescriptionLat="The incorrect password." xmlns="http://tourml.ru/agencies/2004-09-28" />
</RegisterAgencyResponse>

Получение справочной информации (функция GetReferences)

Для получения справочной информации по идентификатору и ключу необходимо воспользоваться функцией GetReferences.

В качестве входных параметров в функцию передаются идентификатор запроса и ключ фильтра:

Значение "queryType"	Значение "param"	Описание
GetPartnerByDgKey	Ключ путевки	Возвращает партнеров, указанных в услугах, связанных с данной путевкой.
HotelByCityId	Ключ города	Выводит все отели данного города.
HotelByCountryId	Ключ страны	Выводит все отели данной страны.
HotelById	Ключ отеля	Выводит отель с заданным ключом.
CityByCountryId	Ключ страны	Выводит все города данной страны.
CityById	Ключ города	Выводит город с заданным ключом.
CountryById	Ключ страны	Выводит страну с заданным ключом.
RoomAccomodationById	Ключ типа размещения	Выводит тип размещения с заданным ключом.
RoomTypeById	Ключ типа комнаты	Выводит тип комнаты с заданным ключом.
RoomCategoryById	Ключ категории номер	Выводит категорию номера с заданным ключом.
BoardingById	Ключ типа питания	Выводит тип питания с заданным ключом.
HotelRoomById	Ключ размещения	Выводит размещение с заданным ключом.

Порядок работы при проверки бронирования и бронировании

Для того, чтобы забронировать тур у оператора, необходимо выполнить следующие действия:

• По логину и паролю получить id агентства, от которого будет производиться бронирование.
• Из TourML, полученного с помощью методов загрузки данных, необходимо выбрать ключ цены для бронирования, а также дату, на которую планируется тур, с учетом атрибутов from,to.
• С помощью функции CheckBooking произвести проверку бронирования. Если status="waitlist" или status="OK", то можно вызывать метод createBooking.
• Произвести бронирование с помощью метода CreateBooking. Ключ и код путевки, которые вернулись в ответе, необходимо сохранить для дальнейшей работы (например, для получения путевки из базы )

Пример запроса\ответа, а также созданная в Мастер-Туре путевка, приведены в приложении Б, посвященному разделу бронирования.

Работа с путевкой

Для получения информации по забронированной путевке можно воспользоваться методом GetAgreementsByNumber, который по коду забронированной путевки и ключу агентства возвращает xml-документ, аналогичный тому, что возвращается при проверке бронирования и бронировании. Необходимо отправить следующий запрос:

<GetAgreementsByNumber xmlns="http://tourml.ru/service/2004-08-13/products">
	<agency>10795</agency> - ключ агентства
	<codes>
		<int>43037</int> - ключ путевки
	</codes>
</GetAgreementsByNumber>

Данная функция используется для того, чтобы можно было отслеживать статус путевки и каждой услуги в отдельности.

Рекомендации по составлению запросов

Web-сервис это сложный программный комплекс, работа с которым требует определенных навыков. Ниже представлены рекомендации по составлению вопросов при обращении в службу технической поддержки. Следование этим рекомендациям позволит специалистам технической поддержки ответить на Ваши вопросы наиболее полно и оперативно.

• Проверьте, не описан ли Ваш вопрос в разделе часто задаваемых вопросов
• Указывайте в запросе, какой метод web-сервиса Вы вызывали и с какими параметрами. Такая информация крайне полезна для повторения ситуации. Повторение ситуации, описываемой в Вашем запросе, облегчает понимание запроса и позволяет более оперативно решать возникшие вопросы

Ответы на часто задаваемые вопросы

Основные моменты, касающиеся работы веб-сервиса работы с TourML описаны в ответах на часто задаваемые вопросы.

Приложение A. Функции загрузки информации о турах и ценах

Функции загрузки информации о турах и ценах описаны в приложении A.

Приложение B. Функции проверки бронирования и бронирования

Функции проверки бронирования и бронирования описаны в приложении B.

Приложение С. Функции работы с путевкой

Функции работы с путевкой описаны в приложении С.