MixVel API General Description
Web Service Message Structure¶
General Provisions¶
The MixVel API methods are based on IATA NDC version 20.2 standards.
The functions inherent in the message formats of the IATA NDC 20.2 standards, but not supported in the current version of Mixvel, are excluded from the Mixvel formats.
(XSDs for Mixvel methods are included in the documentation kit)
Hereinafter: MixVel NDC
Interaction of the client system with the Mixvel Web Service is performed via the HTTPS protocol supporting encryption with the SSL and TLS cryptographic protocols.
Messages are sent as a standard HTTP request by the POST method.
Messages are sent in XML 1.0 format and UTF-8 encoded.
<?xml version='1.0' encoding='UTF-8\'?>
Schemes and Methods Names¶
All method names are in the form "Mixvel_" + NDC method name + Request type (RQ/RS).
Example: Mixvel_AirShoppingRQ, Mixvel_OrderCreateRQ.
Namespaces¶
Each projected scheme must belong strictly to its unique namespace, indicating the message scheme version number.
The namespace has the following naming structure:
http://www.mixvel.com/API/XSD/%scheme name%/%scheme version%
Example: XSD Mixvel_AirShoppingRQ/1_00
ElementFormDefault is set to unqualified in all schemes.
Message Structure¶
An electronic message consists of the following blocks:
Figure 20
Note:
XSD Scheme¶
The Mixvel_Envelop XSD scheme is included in the Documents Kit.
Figure 21
XML Message Sample¶
<?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>
Web Service Usage Scenario¶
MixVel API Methods¶
No. | Method | Purpose | ||
---|---|---|---|---|
1. | AirlineProfileRQ / AirlineProfileRS | Request for the routes operated by the carrier. | ||
2. | Mixvel_AirShoppingRQ / Mixvel_AirShoppingRS | Search for Offers. | ||
3. | Mixvel_ServiceListRQ / Mixvel_ServiceListRS | Request for Offers for available additional services (except for seat selection). | ||
4. | Mixvel_SeatAvailabilityRQ / Mixvel_SeatAvailabilityRS | Request for Offers for the seat selection on the flight. | ||
5. | Mixvel_OfferPriceRQ / Mixvel_OfferPriceRS | Request for obtaining precise price of a commercial offer cost/receipt of the target Offer and alternative Offers. | ||
6. | Mixvel_OrderRulesRQ / Mixvel_OrderRulesRS | Fare application rules request. | ||
7. | Mixvel_InvGuaranteeRQ / Mixvel_InvGuaranteeRS | Order to reserve the seats. | ||
8. | Mixvel_InvReleaseNotifRQ / Mixvel_Acknowledgement | Order to cancel the reservation of the seats. | ||
9. | Mixvel_OrderCreateRQ / Mixvel_OrderViewRS | Order creation. | ||
10. | Mixvel_OrderCancelRQ / Mixvel_OrderCancelRS | Order cancellation and electronic documents void request. | ||
11. | Mixvel_OrderChangeRQ / Mixvel_OrderViewRS | Order change request: changing information in the Order, adding/removing services to/from the Order, primary payment for the Order, secondary operation with the Order, including fines and penalties payment. | ||
12. | Mixvel_OrderReshopRQ / Mixvel_OrderReshopRS | Reception of Offers for a secondary operation. | ||
13. | Mixvel_OrderRetrieveRQ / Mixvel_OrderViewRS | Display of the MixOrder current state. | ||
14. | Mixvel_OrderImportRQ / Mixvel_OrderImportRS | Import of an existing Order/creating an Order copy in MixVel. |
Processes Supported by Mixvel¶
-
Search and assessment of transportation options and ancillary services.
-
Airline-content booking.
-
Booking administration (viewing, changing, canceling).
-
Ticketing.
-
Ticket cancellation.
-
Ticket refund.
Basic Scenario¶
Figure 22
Description of Operations¶
1. AirlineProfileRQ / RS — Request for Directions from a Carrier
-
AirShoppingRQ / RS — Request for Offer
-
ServiceListRQ / RS — Additional Services List Request
-
SeatAvailabilityRQ / RS — Seat map request
-
OrderRulesRQ / RS — Request for Fare Application Rules
-
OrderCreateRQ / OrderViewRS — Order/Booking creation
-
OrderChangeRQ / OrderViewRS — Order/Booking Payment
-
OrderRetrieveRQ / OrderViewRS — Order/Booking status review
-
OrderReshopRQ / RS — Secondary Operations
-
OrderImportRQ / RS — rder/Booking Import
Offers Structure¶
Definitions and Designations:¶
Offer — a commercial offer generated in Mixvel Gate based on offers and/or transportation evalution options/services received from external providers.
Travel Content — (in the context of NDC — Service) — any service related to the movement, placement, or provision of a service. Ticket, hotel accommodation, insurance, baggage packing.
Associated Service
By logic and meaning — a service that is logically related to another, parental service not available for purchase separately from the parent.
(Example: the seat selection service cannot be purchased separately from the airline ticket).
By pricing — a service commercially related to another service, the cost of which depends on the fact of purchasing the related service.
(Example: a discount for a lounge when purchasing a ticket in business class service).
Non — Associated Service
Separate (independent) service, not tied to the parental service.
(Example: accommodation in the hotel, excursion, etc.).
The AirShoppingRQ is used for a commercial offer request.
Services¶
Figure 23
Commercial offer¶
Figure 24
Common Classes¶
OwnerCode and Provider attribute¶
OwnerCode is the information about the session from which the offer was received and an explicit indication of whose stock and terms will be used in the issuance of a service.
Provider refers to a specific provider (NDC service provider or other party to the API) that provides the Offer, the issuance of which will be made either directly on the stock of the session owner, or with the participation of the owner’s stock and additional issuance of the original provider document.
OriginDest¶
The point of departure and the destination on a specific date or date range within which the search is made or Offers are provided.
Multiple OriginDests may be used to form a complex route.
PaxJourney¶
An entity that includes a segment (PaxSegment) or an array of segments.
PaxJourney is a unique combination of PaxSegment within a request or response that satisfies the agency’s search request on a specific OriginDest.
PaxSegment¶
Structure with information on the segment within the response, which consists of the legs (DatedOperatingLeg), showing information within a specific segment regarding the toponyms / airports of departure and arrival, date and time of departure and arrival, type of an aircraft, provided on each of the legs, marketing and operating carrier and other information.
Offering Transportation Services¶
Offer¶
Final Offer related to the service of transportation (flight), having a life cycle inside the platform. Offer is provided from a specific source (OwnerCode and OwnerCode specific Provider).
Offer must fully meet the conditions that were set by the service user when searching (OriginDest).
Offer is presented on the platform via a unique OfferID and consists of OfferItems that exposes its content. Each Offer consists of at least one OfferItem.
By specifying OfferID and OfferItemID in the corresponding queries, the user can request additional services from both the provider who formed the offer and third-party providers, to specify the precise price of the Offer (if the original value was obtained using the provider cache) and request for alternative offers (for example, in different brands).
Offer is converted into Order when booking.
OfferItem¶
OfferItem is formed for passengers group (usually one category of passengers (PTC)), which have common cost and other commercial conditions on a segment or a number of segments.
According to OfferItem, a separate OrderItem will be formed for each passenger, which is a document prototype to be processed after the payment operation.
OfferItem is presented on the platform via a unique OfferItemID.
The nested Service structure specifies the information about the validating party, as well as the segment (PaxSegment) or the segment group (PaxSegment, PaxJourney, or PaxJourney array) that will be executed by the Validating party.
For example, on the route DME – TJM – DME for 2 ADT and 2 CNN in the classical scheme a user will be offered 2 OfferItems for each of the categories of passengers:
OfferItem 1: 2 ADT / DME – TJM, TJM – DME (2 PaxJourneys in Service);
OfferItem 2: 2 CNN / DME – TJM, TJM – DME (2 PaxJourneys in Service).
OfferItem can also display a multiblank case. In case of multiblank on the requested OriginDest Mixvel will create several OfferItems, which cover the entire route through the Service references to a PaxJourney, a PaxSegment, or a PaxSegment array. In case of multiblank case it is allowed to have several Validating parties within the same Offer and issuance of several separate documents.
For example, on the route LED – S7 – DME – U6 – SVX – U6 – DME – S7 – LED Mixvel formed a proposal with two Validating parties, which are offered for issuance on different documents for 2 ADT and 2 CNN.
OfferItem 1: 2 ADT / LED – DME, DME – LED / S7 (2 PaxSegment in Service);
OfferItem 2: 2 CNN/ LED – DME, DME – LED / S7 (2 PaxSegment in Service);
OfferItem 3: 2 ADT / DME – SVX, SVX – DME / U6 (2 PaxSegment in Service);
OfferItem 4: 2 CNN / DME – SVX, SVX – DME / U6 (2 PaxSegment in Service).
Service (OfferItem)¶
Service is a nested OfferItem structure.
Provides the user with information about the Validating party and the segment (PaxSegment) or group of segments (PaxSegment array, PaxJourney, PaxJourney array) to which the specific OfferItem belongs.
Ancillary Services:¶
ALaCarteOffer¶
A set of offers of ancillary services (associated and non-associated) of various Providers (OwnerCode and OwnerCode specific Provider), thematically grouped through ServiceCategory according to RFISC or SSR type.
These ancillary services are offered in the context of an existing Order created through Mixvel or an Order imported by the user to Mixvel.
ALaCarteOffer is identified on the platform by a unique OfferID and must contain at least one ALaCarteOfferItem.
ALaCarteOfferItem¶
Represents a specific unit of ancillary service that refer to a specific segment (PaxSegment), an array of segments or the Offer through the EligibilityFlightAssociations structure.
When receiving offers of ancillary services, a separate ALaCarteOfferItem is created for each individual passenger of the Offer / Order.
Through the Service ALaCarteOfferItem structure, it discloses information by referring to the description of a specific service unit in ServiceDefinition and specifies the Validating party.
ALaCarteOfferItem is presented on the platform via a unique OfferItemID.
Order¶
MixOrder¶
MixOrder MixOrder is a shopping cart of Orders created by sending a Mixvel_OrderCreate request based on one or more Offers.
Order¶
Equivalent of the provider’s booking included in a MixOrder.
OrderItem¶
Equivalent of a document for a service (air transportation or ancillary service), which refers to a specific passenger. It is created for a specific passenger on the basis of OfferItem or OfferItem group, which relates to the passenger within the framework of the Offer.
Service (OrderItem)¶
In case of transportation service defines a specific segment that will be / placed on the coupon of the document of the validating party.
When referring to the allowance of checked baggage or carry-on baggage for each type of baggage defined in BaggageAllowance and additional services placed on separate documents (EMD) a separate Service is created with reference to the parent Service specifying a concrete segment (PaxSegment) or an array of segments within OrderItem.
Objects Identification Rules¶
All the entities transmitted in responses to the agent are divided into 2 categories:
-
The first ones have identifiers with through uniqueness.
-
The latter are unique only as part of a specific message and serve to link entities within one message.
End — to — End Identification¶
Offer — guid.
OfferItem — guid.
ALaCarteOffer — guid.
ALaCarteOfferItem — guid.
MixvelOrder — a string, to be formed by a mask.
Order — a string, to be formed by a mask.
End — to — End Identifiers Mask¶
-
The identifier must be mnemonic for simple:
-
verbal transmission to employees of Mixvel and TCH services;
-
user input from the keyboard;
-
visual search through the identifiers list and visual decoding of the identifier.
-
Maximum length of the identifier string must not exceed 20 characters.
-
Allowed characters for the identifier:
Numbers: 0 1 2 3 4 5 6 7 8 9
Letters: E T Y O P A H K X C B M
Symbols: -
Mask¶
%Agent code%-%Date%-%Entity type%%Order number%, in detail:
Agent code: sequence (Agent number) in Mixvel in the range: [1..99999] (from 1 to 99999 inclusive).
Date: Date (GMT) of the identified entity creation in Mixvel in the YYMMDD format (2-digit - year, 2-digit - month, 2-digit - day).
Entity type: M - MixVel Order, O - Order.
Order number: Order number: 2 string characters from the list of allowed ones, 4 - numeric ones.
For example:
00001-200211-MAC1234
Identification within the Message¶
Requirements apply to the entities:
-
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
Identification is performed using the following mask:
%Entity name%-%ordinal number within the message from 1 to N%
Examples:
PaxJourney-1
BaggageAllowance-26
Authorization¶
General Provisions¶
Endpoint: /api/Accounts/login
JWT standard (rfc7519) is used for agent authorization.
The agent contacts the authorization service to obtain a JWT token.
The JWT token has a limited lifetime and is valid for 24 hours, after which the JWT token is requested again.
Note:
The JWT token lifetime may actually be less than the scheduled time in the event of a revocation (blocking) of the token.
Obtaining a Token¶
To obtain a token, use the Auth method described in the XSD scheme Mixvel_Auth.xsd (included in the documentation kit).
The following parameters are transmitted in the request:
-
Login
-
Password
-
StructureUnitId (identifier of the structural unit, set in the Mixvel Web Agency) on the basis of which the agent is to be identified.
An agent can work simultaneously with several different Login credentials.
StructureUnitId is obtained from the Mixvel Web Agency Application from the Structure Unit settings with the tab «Data» and has the following format:
%Agent code%_% Structure unit unique identifier %, in detail:
Agent code: sequence (Agent number) in Mixvel in the range: [1..99999] (from 1 to 99999 inclusive).
Division unique identifier: a set of Latin letters from A to Z, without the letter O.
For example:
12345_MNPQR
The procedure for the application login obtaining and managing is described in the section.
Message structure¶
Figure 25
Authentication by JWT Token¶
So as to work with all the methods of the Mixvel Web Service, the agent passes the JWT token received using the Auth method in the HTTP request header.
The Web Service validates the JWT token and either authorizes the operation or returns a corresponding error.
Reference Messages¶
Request¶
<?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>
Response¶
<?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>