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

Статья находится на стадии разработки.
Версия статьи от 13-09-2013.

Содержание

1 Введение
2 Настройки
- 2.1 Настройки в файле WEB.CONFIG
3 Общая информация о методах веб-сервиса
4 Авторизация при использовании web-сервиса
- 4.1 Авторизация с использованием WSE
5 Вызов методов веб-сервиса. Возможные проблемы при авторизации
6 Функции загрузки информации о турах
- 6.1 Формат TourML
  - 6.1.1 Описание формата TourML
- 6.2 Порядок работы с web-сервисом
7 Пример работы с веб-сервисом
- 7.1 Описание тестового примера
8 Рекомендации по составлению запросов
9 Ответы на часто задаваемые вопросы
10 Приложение A. Функции загрузки информации о турах и ценах
11 Приложение B. Функции проверки бронирования и бронирования
12 Приложение С. Функции работы с путевкой

Введение

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

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

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

Настройки

Настройки в файле 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"/>

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

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

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

Метод GetValidTourList

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

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

Нет

Метод GetValidTourListFrom

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

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

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

Метод GetValidTourListFrom_DC

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

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

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

Метод GetSPOPageByKey

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

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

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

Метод GetSPOByKey

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

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

SpoKey – ключ СПО

Метод GetSPOByKey_DC

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

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

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

Метод GetSPOByKeyCompressed

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

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

SpoKey – ключ СПО

Метод GetSPOByKeyCompressed_DC

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

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

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

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

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

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

Метод GetStopSalesAndQuotesByHotels

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

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

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

Метод GetFlightQuotes

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

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

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 - дата по которое будет выводится список созданных путевок

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

Метод 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 части.

header – заголовок документа
references (необязательна) – секция справочников
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, сгруппированных по цене.

Чтобы найти 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 - ключ тарифа.

<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" duration=”5,6” /> 
</quotas>

Квоты по датам преведены в элементах <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" />

на заданное число есть 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” />

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>

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.

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

Для получения информации по авиаперелетам необходимо использовать метод 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>

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

Пример работы с веб-сервисом

В составе дистрибутива веб-сервиса поставляется пример программы, использующей веб-сервис. Программа выполнена для платформы Windows с использованием технологии Microsoft .NET на языке программирования C#. Программа поставляется в виде выполняемого файла, а также в виде исходного кода. Для работы с исходным кодом Вы можете воспользоваться бесплатной версией среды разработки для платформы Microsoft .NET. Скачать данную среду можно по следующей ссылке:

http://www.microsoft.com/rus/express/download/default.aspx.

Разархивируйте файл ServiceClient.zip в любой каталог на компьютере. С помощью среды разработки откройте файл ServiceClient.sln

Описание тестового примера

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

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

Данная программа вызывает единственный метод (GetValidTourList), получая через веб-сервис количество доступных туров за последние 5,10,15,20,25 дней. При нажатии на кнопку “By WSE” вызов осуществляется с помощью WSE авторизации, соответственно “By SOAP header”, “By GET string” - с помощью заголовков SOAP и с помощью авторизации через GET запрос. Результат отображается в поле «доступно СПО». Перед результатом указывается тип авторизации, который был использован.

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

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

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

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

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

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

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

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

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

Содержание

Введение

Настройки

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

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

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

Метод GetValidTourList

Метод GetValidTourListFrom

Метод GetValidTourListFrom_DC

Метод GetSPOPageByKey

Метод GetSPOByKey

Метод GetSPOByKey_DC

Метод GetSPOByKeyCompressed

Метод GetSPOByKeyCompressed_DC

Метод GetSPOPageByKeyCompressed

Метод GetStopSalesAndQuotes

Метод GetHotelKeys

Метод GetHotelQuotes

Метод GetStopSalesAndQuotesByHotels

Метод GetFlightQuotes

Метод GetCountries

Метод GetValidTourListWithoutValidation

Метод ValidatePriceServices

Метод GetAgencies

Метод GetReferences

Метод GetSimpleDogovorsBronni

Метод GetBookingInfo

Метод GetStopSalesAndQuotes2

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

Метод GetAgreementCredentials

Метод CheckBooking

Метод CreateBooking

Метод CancelAgreement

Метод GetAgreementsByNumber

Метод GetAgreementsByKeys

Метод GetAgreementsByCode

Метод GetSimpleDogovorsByCreateDates

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

Метод GetVersion

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

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

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

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

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

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

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

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

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

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

Формат TourML

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

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

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

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

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

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

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

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

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

Раздел Header

Раздел Packets

Раздел Persons

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

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

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

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

Пример работы с веб-сервисом

Описание тестового примера

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

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

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

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

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

Навигация

Поиск