Общее описание MixVel API

Структура сообщения веб-сервиса¶

Общие положения¶

Методы MixVel API построены на основе стандартов IATA NDC, версии 20.2, однако имеют сокращенную форму.

Функционал, заложенный в форматы сообщений стандартов IATA NDC 20.2, но который не поддерживается в текущей версии MixVel, исключен из форматов MixVel.

(XSD-схемы методов MixVel входят в комплект документации)

Далее по тексту: MixVel NDC

Взаимодействие клиентской системы c веб-сервисом MixVel производится по протоколу HTTPS, поддерживающему шифрование с использованием криптографических протоколов SSL и TLS

Электронные сообщения передаются в виде стандартного HTTP запроса с использованием метода POST.

Электронные сообщения передаются в формате XML 1.0 в кодировке UTF-8.

<?xml version='1.0' encoding='UTF-8\'?>

Именование схем и методов¶

Наименования всех методов имеют формат "Mixvel_" + Наименование метода NDC + Тип запроса (RQ/RS).

Пример: Mixvel_AirShoppingRQ, Mixvel_OrderCreateRQ.

Пространства имен¶

Каждая проектируемая схема должна принадлежать строго к своему уникальному пространству имен, с указанием номера версии схемы сообщения.

Пространство имен имеет следующую структуру именования:

http://www.mixvel.com/API/XSD/%наименование схемы%/%версия схемы%

Пример: http://www.mixvel.com/API/XSD/Mixvel_AirShoppingRQ/1_00

ElementFormDefault во всех схемах установлен в unqualified.

Структура сообщения¶

Электронное сообщение состоит из следующих блоков:

Рисунок 31

Примечание:

* — Функционал наложения/проверки электронной подписи запланирован к реализации в следующих версиях MixVel.

XSD-схема¶

XSD-схема Mixvel_Envelop входит в комплект документации.

Рисунок 32

Пример XML-сообщения¶

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://www.mixvel.com/API/XSD/mixvel_envelope/1_06">
    <Header/>
    <Body id="ID1">
        <MessageInfo MessageId="ad1320cf-d9da-4e03-bec8-3dfc34b71501" TimeSent="2020-04-27T12:27:17Z"/>
        <AppData>
            <Shop:Mixvel_AirShoppingRQ xmlns:Shop="http://www.mixvel.com/API/XSD/Mixvel_AirShoppingRQ/1_01">
                …
            </Shop:Mixvel_AirShoppingRQ>
        </AppData>
    </Body>
</Envelope>

Сценарий использования веб-сервиса¶

Методы MixVel API¶

№ п/п	Метод	Назначение
1.	AirlineProfileRQ / AirlineProfileRS	Запрос маршрутов, выполняемых перевозчиком.
2.	Mixvel_AirShoppingRQ / Mixvel_AirShoppingRS	Поиск коммерческих предложений.
3.	Mixvel_ServiceListRQ / Mixvel_ServiceListRS	Запрос коммерческих предожений на доступные дополнительные услуги (кроме выбора мест).
4.	Mixvel_SeatAvailabilityRQ / Mixvel_SeatAvailabilityRS	Запрос коммерческих предожений выбора мест на рейсе.
5.	Mixvel_OfferPriceRQ / Mixvel_OfferPriceRS	Запрос уточнения стоимости коммерческого предложения / получение альтернативных предложений.
6.	Mixvel_OrderRulesRQ / Mixvel_OrderRulesRS	Запрос условий применения тарифа.
7.	Mixvel_InvGuaranteeRQ / Mixvel_InvGuaranteeRS	Запрос на резервирование мест.
8.	Mixvel_InvReleaseNotifRQ / Mixvel_Acknowledgement	Запрос на отмену зарезервированных мест.
9.	Mixvel_OrderCreateRQ / Mixvel_OrderViewRS	Создание заказа
10.	Mixvel_OrderCancelRQ / Mixvel_OrderCancelRS	Запрос на отмену заказа и аннулирование электронных документов.
11.	Mixvel_OrderChangeRQ / Mixvel_OrderViewRS	Запрос на внесение изменений в Заказ: изменение информации в Заказе, добавление / удаление услуг в / из Заказа, первичная оплата Заказа, вторичная операция с Заказом, включая оплату штрафов и неустоек.
12.	Mixvel_OrderReshopRQ / Mixvel_OrderReshopRS	Получение предложений на проведение вторичной операции.
13.	Mixvel_OrderRetrieveRQ / Mixvel_OrderViewRS	Отображение действующего состояния MixOrder.
14.	Mixvel_OrderImportRQ / Mixvel_OrderImportRS	Импортирование существующего Заказа / создание копии Заказа в MixVel.

Процессы, поддерживаемые MixVel¶

Поиск и оценка вариантов перевозки и дополнительных услуг;
Бронирование авиа-контента;
Управление бронированием (просмотр, изменение, отмена);
Выписка билетов;
Аннулирование билетов;
Возврат билетов.

Базовый сценарий¶

Рисунок 33

Описание операций¶

AirlineProfileRQ / RS — Запрос маршрутов, выполняемых перевозчиком
AirShoppingRQ / RS — Поиск коммерческих предложений
ServiceListRQ / RS — Запрос коммерческих предожений на доступные дополнительные услуги (кроме выбора мест)
SeatAvailabilityRQ / RS — Запрос коммерческих предожений выбора мест на рейсе
OrderRulesRQ / RS — Запрос условий применения тарифа
OrderCreateRQ / OrderViewRS — Создание заказа
OrderChangeRQ / OrderViewRS — Запрос на внесение изменений в Заказ: изменение информации в заказе, добавление / удаление услуг в / из заказа, первичная оплата Заказа, вторичная операция с Заказом, включая оплату штрафов и неустоек
OrderRetrieveRQ / OrderViewRS — Отображение действующего состояния MixOrder
OrderReshopRQ / RS — Получение предложений на проведение вторичной операции
OrderImportRQ / RS — Импортирование существующего заказа / создание копии заказа в MixVel

Структура коммерческих предложений¶

Определения и обозначения¶

Offer — коммерческое предложение, сформированное в MixVel Gate, на основании коммерческих предложений и/или вариантов оценки перевозки / услуги, полученных от внешних поставщиков.

Travel-контент — (в контексте NDC — Service) - любая услуга, связанная с перемещением, размещением, или оказанием услуги. Билет на самолет, размещение в отеле, страховка, упаковка багажа.

Ассоциированная услуга

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

(Пример: услуга выбора места на борту самолета не может быть приобретена отдельно от билета на самолет)

По ценообразованию — услуга, коммерчески связанная с другой, услугой, стоимость которой зависит от факта приобретения связанной услугой

(Пример: скидка на бизнес-зал при приобретении билета в бизнес-классе обслуживания)

Неассоциированная услуга

Отдельная (самостоятельная) услуга, не привязанная к родительской.

(Пример: размещение в отеле, экскурсия и т.д.)

Для запроса коммерческого предложения используется запрос AirShoppingRQ.

Услуги¶

Рисунок 34

Коммерческое предложение (Offer)¶

Рисунок 35

Общие сущности¶

OwnerCode и атрибут Provider¶

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

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

OriginDest¶

Точка отправления и точка назначения на конкретную дату или диапазон дат, в рамках которой осуществляется поиск или предоставляются предложения.

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

PaxJourney¶

Сущность, которая включает в себя сегмент (PaxSegment) или массив сегментов.

PaxJourney представляет собой уникальную комибинацию PaxSegment в рамках запроса или ответа, которые удоволетворяют поисковому запросу агентства на конкретном OriginDest.

PaxSegment¶

Структура с информацей о сегменте в рамках ответа, который состоит из плеч (DatedOperatingLeg), показывающий информацию в рамках конкретного сегмента относительно топонимов / аэропортов вылета и прилета, дате и времени вылета и прилета, типе воздушного судна, предоставляемого на каждом из плеч, маркетинговом и оперирующем перевозчике и прочей информации.

Предложение услуг перемещения¶

Offer¶

Конечное коммерческое предложение, связанное с услугой перемещения (перелета), имеющее срок жизни внутри платформы. Offer предоставляется из конкретного источника (OwnerCode и Provider конкретного OwnerCode).

Offer должен полностью удовлетворять условиям, которые были заданы пользователем сервиса при поисковом запросе (OriginDest).

Offer представляется на платформе через уникальный OfferID и состоит из OfferItem, которые раскрывают его наполнение. Каждый Offer состоит минимум из одного OfferItem.

Указав OfferID и OfferItemID в соответветствующих запросах, пользователь может запросить дополнительные услуги как поставщика, который сформировал предложение, так и сторонних поставщиков, уточнить стоимость Offer (если первоначальная стоимость была получена с использованием кэша поставщика), а также запросить альтернативные предложения (например, в различных брендах).

Offer при бронировании преобразуется в Order.

OfferItem¶

OfferItem формируется для группы пассажиров (как правило одной категории пассажиров (PTC)), которые имеют общие стоимостные и иные коммерческие условия на сегменте или ряде сегментов.

В соответствии с OfferItem для каждого пассажира будет сформирован отдельный OrderItem, который является прообразом документа, который подлежит оформлению после операции оплаты.

OfferItem представляется на платформе через уникальный OfferItemID.

Через вложенную структуру Service указывается информация о валидирующей стороне, а также о сегменте (PaxSegment) или группе сегментов (массив PaxSegment, PaxJourney или массив PaxJourney), который будет оформлен валидирующей стороной.

Например, на маршруте DME–TJM–DME для 2 ADT и 2 CNN в классической схеме оформления услуг будет предложены 2 OfferItem на каждую из категорий пассажиров:

OfferItem 1: 2 ADT / DME–TJM, TJM–DME (2 PaxJourney в Service);

OfferItem 2: 2 CNN / DME–TJM, TJM–DME (2 PaxJourney в Service).

OfferItem также может отображать мультибланковый кейс. При мультибланковом кейсе на запрошенном OriginDest будет создано несколько OfferItem, которые посредством Service будут покрывать весь запрошенный маршрут через ссылки на PaxJourney, PaxSegment, массив PaxSegment. При мультибланковом кейсе допускается участие нескольких валидирующих сторон в рамках одного Offer и оформление нескольких не связанных документов.

Например, на маршруте LED–S7–DME–U6–SVX–U6–DME–S7–LED сформировано предложение двух валидирующих сторон, которые предлагаются к оформлению на разных документах для 2 ADT и 2 CNN.

OfferItem 1: 2 ADT / LED–DME, DME–LED / S7 (2 PaxSegment в Service);

OfferItem 2: 2 CNN/ LED–DME, DME–LED / S7 (2 PaxSegment в Service);

OfferItem 3: 2 ADT / DME–SVX, SVX–DME / U6 (2 PaxSegment в Service);

OfferItem 4: 2 CNN / DME–SVX, SVX–DME / U6 (2 PaxSegment в Service).

Service (OfferItem)¶

Service вляется вложенной структурой OfferItem.

Предоставляет пользователю информацию о валидирующей стороне, а также о сегменте (PaxSegment) или группе сегментов (массив PaxSegment, PaxJourney, массив PaxJourney), к которым относится конкретный OfferItem.

Предложение дополнительных услуг:¶

ALaCarteOffer¶

Набор предложений дополнительных услуг (ассоциированных и неассоциированных) различных поставщиков (OwnerCode и Provider конкретного OwnerCode), тематически сгруппированных через ServiceCategory в соответствии с RFISC или типом SSR.

Данные дополнительные услуги предлагаются в контексте существующего заказа, созданного через платформу MixVel, или заказа, информация о котором была внесена пользователем в платформу Mixvel.

ALaCarteOffer идентифицируется на платформе уникальным кодом OfferID и обязательно содержит хотя бы один ALaCarteOfferItem.

ALaCarteOfferItem¶

Представляет конкретную единицу дополнительной услуги, которая ссылается (относится) на конкретный сегмент (PaxSegment), массив сегментов или весь Offer посредством структуры EligibilityFlightAssociations.

При получении предложений дополнительных услуг создается отдельнный ALaCarteOfferItem на каждого отдельного пассажира предложения / заказа.

Через структуру Service ALaCarteOfferItem раскрывает информацию со ссылкой на описание конкретной единицы услуги в ServiceDefinition и указывает валидирующую сторону.

ALaCarteOfferItem представляется на платформе через уникальный OfferItemID.

Заказ¶

MixOrder¶

MixOrder представляет собой корзину заказов, созданных посредством отправки запроса Mixvel_OrderCreate на основании одного или нескольких коммерческих предложений.

Order¶

Эквивалент заказа (бронирования) поставщика, который включен в MixOrder.

OrderItem¶

Эквивалент документ на услугу (авиационную перевозку или дополнительную услугу), которая относится к конкретному пассажиру. Создается для конкретного пассажира на основании OfferItem или группы OfferItem, которые относятся к пассажиру в рамках Offer.

Service (OrderItem)¶

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

При отнесении к норме провоза сдаваемого багажа или ручной клади для каждого из типов багажа, определенного в BaggageAllowance, или дополнительных услуг, размещаемых на отдельных документах (EMD), создается отдельный Service со ссылкой на родительский Service с указанием конкретного сегмента (PaxSegment) или массива сегментов в рамках OrderItem.

Правила идентификации объектов¶

Все сущности, передаваемые в ответах агенту, делятся на 2 категории:

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

Сквозная идентификация¶

Offer — guid.

OfferItem — guid.

ALaCarteOffer — guid.

ALaCarteOfferItem — guid.

MixvelOrder — строка, формируется по маске.

Order — строка, формируется по маске.

Маска сквозных идентификаторов¶

1) Идентификатор должен быть мнемоническим для возможности:

вербальной передачи сотрудникам служб MixVel и ТКП;
ввода идентификатора пользователем с клавиатуры;
осуществления визуального поиска по списку идентификаторов и осуществления визуальной расшифровки идентификатора.

2) Максимальная длина строки-идентификатора не должна превышать 20 символов.

3) Допустимые символы к использованию в идентификаторе:

Цифры: 0 1 2 3 4 5 6 7 8 9

Буквы: E T Y O P A H K X C B M

Символы: -

Маска¶

%Код агента Mixvel%-%Дата%-%Тип сущности%%Номер заказа%, где:

Код агента: порядковый номер агента в MixVel в диапазоне: [1..99999] (от 1 до 99999 включительно).

Дата: Дата (по гринвичу) создания в MixVel идентифицируемой сущности в формате YYMMDD (2 разряда - год, 2 разряда - месяц, 2 разряда - день).

Тип сущности: M - MixVel Order, O - Order

Номер заказа: Порядковый номер заказа: 2 строковых символа из списка разрешенных, 4 - числовых

Пример:

00001-200211-MAC1234

Идентификация в рамках сообщения¶

Требования распространяются на сущности:

Response \ DataLists \ BaggageAllowanceList \ BaggageAllowance \ BaggageAllowanceID
Response \ DataLists \ ContactInfoList\ContactInfo\ContactInfoID
Response \ DataLists \ OriginDestList \ OriginDest \ OriginDestID
Response \ DataLists \ PaxJourneyList \ PaxJourney \ PaxJourneyID
Response \ DataLists \ PaxList \ Pax \ PaxID
Response \ DataLists \ PaxSegmentList \ PaxSegment \ PaxSegmentID
Response \ DataLists \ PaxSegmentList \ PaxSegment \ DatedOperatingLeg \ DatedOperatingLegID
Response \ DataLists \ PriceClassList \ PriceClass \ PriceClassID
Response \ DataLists \ SeatProfileList \ SeatProfile \ SeatProfileID
Response \ DataLists \ ServiceDefinitionList \ ServiceDefinition \ ServiceDefinitionID
Offer \ .. \ Service \ ServiceId
ALaCarteOffer \ .. \ Service \ ServiceId

Идентификация осуществляется по следующей маске:

%Наименование сущности%

Примеры:

PaxJourney

BaggageAllowance

Авторизация¶

Общие положения¶

Endpoint: /api/Accounts/login

Для авторизации агента используется стандарт JWT (rfc7519).

Агент обращается к сервису авторизации для получения JWT-токена.

JWT-токен ограничен по сроку жизни и действует 24 часа, по истечении которых JWT-токен запрашивается повторно.

Примечание:

Срок жизни JWT-токен может быть фактически меньше регламентного времени в случае отзыва (блокировки) токена.

Получение токена¶

Для получения токена используется метод Auth, описанный в XSD схеме Mixvel_Auth.xsd (входит в комплект документации)

В запросе передаются параметры:

Login
Password
StructureUnitId (Идентификатор структурного подразделения, задается в Личном Кабинете) на основании которых осуществляется идентификация агента.

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

StructureUnitId получается из Кабинета агентства MixVel из настроек Подразделения с вкладки «Данные» и имеет следующий формат:

%Код агента Mixvel%_%Уникальный идентификатор Подразделения%, где:

Код агента: порядковый номер агента в MixVel в диапазоне: [1..99999] (от 1 до 99999 включительно).

Уникальный идентификатор Подразделения: набор латинских букв от A до Z, без буквы O, может содержать цифры от 0-9.

Пример:

12345_MNPQR

Порядок получения и управления логина приложения описан в разделе

Структура сообщения

Рисунок 36

Аутентификация по JWT токену¶

Для работы со всеми методами веб-сервиса MixVel агент передает в заголовке HTTP-запроса полученный через метод Auth JWT-токен.

Веб-сервис осуществляет валидацию JWT-токена и либо авторизует операцию, либо возвращает соответствующую ошибку.

Эталонные сообщения¶

Запрос¶

<?xml version="1.0" encoding="UTF-8"?>
<MixEnv:Envelope xmlns:MixEnv="https://www.mixvel.com/API/XSD/mixvel_envelope/1_06">
    <Header/>
    <Body id="ID1">
        <MessageInfo MessageId="0d92db5d-e830-46ff-8af0-9eb4bae192a9" TimeSent="2021-04-27T14:17:48Z"/>
        <AppData>
            <a:Auth xmlns:a="https://www.mixvel.com/API/XSD/mixvel_auth/1_01">
                <Login>testUser.auth@mixvel.com</Login>
                <Password>passWord1!</Password>
                <StructureUnitID>12036_ALPHA</StructureUnitID>
            </a:Auth>
        </AppData>
    </Body>
</MixEnv:Envelope>

Ответ¶

<?xml version="1.0" encoding="UTF-8"?>
<MixEnv:Envelope xmlns:MixEnv="https://www.mixvel.com/API/XSD/mixvel_envelope/1_06">
    <Header/>
    <Body id="ID1">
        <MessageInfo MessageId="703423d1-595c-49f5-98c2-5dcabe950276" ReplyTo="79b67a26-6fc3-41e3-8ac4-14e0ac0245c8" TimeSent="2020-11-25T13:37:48Z"/>
        <AppData>
            <auth:AuthResponse xmlns:auth="https://www.mixvel.com/API/XSD/mixvel_auth/1_01">
                <Token>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlRlc3QgQWdlbnQiLCJleHAiOjE2MDYzMTI4MDAsImlhdCI6MTYwNjMwOTIwMH0.xTPifj6i5Bf_Wl6sw6nOLL3jHDk-DeRozjv3YeuMFUphbkA9-NVqiPEs_7frD_ZVPEoXnoBNgBEc9sr8S53o5w</Token>
            </auth:AuthResponse>
        </AppData>
    </Body>
</MixEnv:Envelope>