Supply version 1.5.1
1. Introduction
Because of a new IT landscape within TUI the whole XML G7 flow was reviewed. The conclusion was to upgrade to "TravelMessage v3.1". Accordingly, for Supply was chosen to reuse the custom 1.5 version. Because of differences between the old and new system the 1.5 version is slightly changed to version 1.5.1. For example, not all fields are mandatory anymore.
The TUI supply is being delivered to third parties via xml files. The xml is based upon the TUI xml Supply standard and the G7 standard. It combines to a custom Supply message version 1.5.1.
Files are placed on a local directory on a server from which third parties can retrieve them via SFTP download.
From patch 6 onwards, there are two workflows available:
- Full loads: This means that every day one file for each package will be available with the status at that moment. (current flow).
- Delta loads: This means every day a file for each package will be available with the status at that moment, but besides that, changes will be delivered during the day in cycles (initial: 2 hours).
The two flows cannot be combined. The full loads can still be used while developing delta flow. At a certain time, each OTA needs to switch to delta loads for a more accurate price and availability status during the day. And also because the full load will be switched off in the future.
Each file contains information about a package and for this package content, carrier and accommodation info were seen. Besides that, the following prices are for each:
- Departure date
- Duration (Nights)
- Transport (Route)
- Unit
- Board
- Occupation (based on adults) is added.
Availability and price information from a newer version file, replaces any previously supplied information for that respective package.
2. XML message explanation
2.1 Supply
The main XML-tag in the XML message is "Supply". The Supply contains a "Control" group and "SupplyResponse", of which control is standard in the G7 and "SupplyResponse" is tailor-made.
2.2 Control
The "Control" is a standard G7 XML-tag. It contains processing data like SessionID's, Date and Time, MessageSequence and so on. But for now, the full load is important to always use the latest file and in the future the MessageSequence could be predominant and to be incremental once all the files are being processed.
2.3 SupplyResponse
The SupplyResponse is divided into four sections, described below:
-
General information of the package, like packageID and "ProductInfo".
-
Transport information containing the different available routes in "SupplyTransportInfo".
-
Accommodation information, including units in "SupplyAccoInfo".
-
Availability information contains available dates and prices in "SupplyPriceAvailabilityInfo".
2.4 ProductInfo
ProductInfo group contains general information of the package.
This is a description, publication period, content location etc. It also contains facility codes for extra information
about the package and also a commission group.
The structure of the commission group is like this:
<CommissionGroup>
<Commission>
<CommissionCategory>C</CommissionCategory>
<TravelPeriod>
<StartDate>2022-10-01</StartDate>
<EndDate>2024-03-31</EndDate>
</TravelPeriod>
<BookPeriod>
<StartDate>2022-10-01</StartDate>
<EndDate>2024-03-31</EndDate>
</Book Period>
</Commission>
</CommissionGroup>
It is possible to have more commissions depending on the departure date of the trip and the creation date of the booking. But for one departure date and one book date, there should always be just one commission. If the book period is not present in the XML then the commission is for the whole travel period.
2.5 SupplyTransportInfo
Supply Transport Info contains different Routes that are available for the package. It contains a unique "RouteID" and a departure and arrival point. The "RouteID" reoccurs in the "SupplyPriceAvailability" as a key Referencing back to "SupplyTransportInfo".
2.6. SupplyAccoInfo
Supply Acco Info contains Accommodation information and Unit information. For each Available Unit within this accommodation there will be "UnitID", Occupancy information and Board information. And the UnitID reoccurred in the "SupplyPriceAvailability" as a key.
At unit/occupation level occupancy rules, restrictions and period are added (See
Occupation xml example). For this unit it means that general occupancy is between 1-4
persons. This should always be one or more adults (age 13-200 - rule 1)
and could have children between 0-3 (age 2-12 - rule 2). Infants (age
0-1-rule 3) can be added up to 4. Normally all persons are count for
occupancy or the rule must have the "OccupancyIncluded" property set to
no ("nee"). In this case, the infants are not counted for occupancy.
In this example also a restriction rule is applied for 3 adults and 1 child. This combination,
situation 5 is therefore not allowed. Restriction rules are optional.
<Occupation>
<MinOccupancy>1</MinOccupancy>
<MaxOccupancy>4</MaxOccupancy>
<OccupancyRules PaxType="Adult" >
<MinOccupancy>1</MinOccupancy>
<MaxOccupancy>3</MaxOccupancy>
<AgeCondition AgeType="MIN">13</AgeCondition>
<AgeCondition AgeType="MAX">200</AgeCondition>
</OccupancyRules>
<OccupancyRules PaxType="Child" >
<MinOccupancy>0</MinOccupancy>
<MaxOccupancy>3</MaxOccupancy>
<AgeCondition AgeType="MIN">2</AgeCondition>
<AgeCondition AgeType="MAX">12</AgeCondition>
</OccupancyRules>
<OccupancyRules PaxType="Infant" OccupancyIncluded="nee">
<MinOccupancy>0</MinOccupancy>
<MaxOccupancy>4</MaxOccupancy>
<AgeCondition AgeType="MIN">0</AgeCondition>
<AgeCondition AgeType="MAX">1</AgeCondition>
</OccupancyRules>
<OccupancyRestrictions>
<Adult>3</Adult>
<Child>1</Child>
</OccupancyRestrictions>
<OccupancyPeriod>
<StartDate>2024-05-16</StartDate>
<EndDate>2024-10-31</EndDate>
</OccupancyPeriod>
</Occupation>
Examples:
| Situation | Adults (rule 1) | Children (rule 2) | Infants (rule3) | Total Occupancy |
|---|---|---|---|---|
| 1 | 1,2 or 3 | 0 | 0 | 1,2 or 3 |
| 2 | 1 | 3 | 0 | 4 |
| 3 | 2 | 2 | 0 | 4 |
| 4 | 2 | 2 | 2 (not count) | 4 |
| 5 | 3 | 1 | 0 | Not allowed |
Because of the Occupancy period it is possible to have changes in the rules over time. The occupation group will then be repeated in the xml.
2.7 SupplTransferInfo
Supply Transfer Info contains different Transfer possibilities for the package. It contains a unique "TransferID" and a departure and arrival point. The "TransferID" reoccurs in the "SupplyPriceAvailability" as a key Referencing back to "SupplyTransportInfo".
Remarks:
TUI decided that standard (bus)transfer is not included in the price anymore.
But because certain OTA's want to show a standard (bus)transfer in the price,
the transfers are added in the supply. This means they can show a price in their
pricegrid including the standard (bus)transfer if available. This also means they
have to add a transfer component in the bookflow. For other OTA's it is not needed, but
they can choose to add an update possibility for transfer in their bookflow.
2.8 SupplyPriceAvailabilityInfo
Supply price availability info contains one to many "SupplyPriceAvailability" for each combination of departure date, duration, route, unit, board and occupation. So, if a package has departures every week with 3 durations with 2 routes and 2 different board types then there are already 52*3*2*2 = 624 combinations possible for each unit. So, if the unit has "MaxOccupancy" of 3 then 624 * 3 = 1872 prices could be available as part of it. And also each "SupplyPriceAvailability" is always with one route and one Unit.
In the supply the duration will be given in nights of stay in the accommodation. Most of the time the duration in days is duration of nights + 1. But when a flight crosses a date (let's call it "flightnight"), theoretically the duration of days can be + 2.
Consider this actual example for the same trip, same out flight but with another return flight.
Trip 1 : Flight: AMS - HER, Accommodation: with 3 nights stay, Flight: HER - AMS
Trip 2 : Flight: AMS - HER, Accommodation: with 3 nights stay, Flight: HER - AMS (+1)
Because of the late departure time of the second possibility the duration in days would theoretically be 5.
| Trip | Departure date | Arrival date | Stay (nights) | Departure date | Arrival date | Duration (days) |
|---|---|---|---|---|---|---|
| 1 | 08-08-2023 17:30 | 08-08-2023 22:20 | 3 | 11-08-2023 13:00 | 11-08-2023 16:10 | 4 |
| 2 | 08-08-2023 17:30 | 08-08-2023 22:20 | 3 | 11-08-2023 23:40 | 12-08-2023 02:35 | 5 |
For TUI supply both possibilities are treated as one. Because in Supply there is no flight definition, only a route for AMS-HER and HER-AMS. As of patch 5 the TripDuration is added to the xml to add the duration in days. Watch out; this field is only for information, when using Availability use the Duration (in nights) to get the right package. Depending on available flights, tripduration may vary.
<SupplyPriceAvailability/>
<DepartureDate>2023-08-08</DepartureDate>
<Duration DurationType="nachten">3</Duration>
<TripDuration>4</TripDuration> or <TripDuration>5</TripDuration>
...
There is also the possibility that a flight-night is part of the journey. In that case the duration in days is
duration in nights +2. With the same possibility of a late flight as already shown it could be even +3.
consider these actual examples:
Trip 3 : Flight: AMS - CUR, Accommodation: with 7 nights stay, Flight: CUR-AMS(+1)
Trip 4 : Flight: AMS - HKT(+1), Accommodation: with 7 nights stay, Flight: HKT-AMS (+1)
| Trip | Departure date | Arrival date | Stay(nights) | Departure date | Arrival date | Duration (days) |
|---|---|---|---|---|---|---|
| 3 | 16-06-2023 12:25 | 16-06-2023 16:50 | 7 | 23-06-2023 16:50 | 24-06-2023 10:20 | 9 |
| 4 | 16-06-2023 21:50 | 17-06-2023 20:00 | 7 | 24-06-2023 20:10 | 25-06-2023 09:20 | 10 |
In supply both examples 1 and 2 have duration 7 but tripduration is different.
<SupplyPriceAvailability/>
<DepartureDate>2023-06-16</DepartureDate>
<Duration DurationType="nachten">7</Duration>
<TripDuration>9</TripDuration> or <TripDuration>10</TripDuration>
...
In the "AvailabilityRequest" this values must be used to get detailed information.
2.9 Content
In the ProductInfo group there is a reference to additional content/images named "TextLocation". Information
about the json structure is available in the "OTA content api" description.
This additional information contains for the accommodation and rooms in the trip Dutch descriptions, image locations and
so on.
For the units, field "roomtypeCode" is used. But that ID is within TUI an internalID which relates to the unit content.
That why there is a second ID "UnitContentID" included in the SupplyUnitGroup. So the content for the actual unit can
be found.
If there is no availability in the SupplyMessage (SupplyPriceAvailability), then the content of accommodation is also not available in the content api.
3. Code Tables
3.1 MutationType
| Type | Description |
|---|---|
| New | New items/prices added |
| Mutation | Package/prices updated |
| Deletion | Package/prices deleted |
| Reset | Whole package and prices needs reset |
3.1 OfferType
| Code | Description |
|---|---|
| 1 | Regular |
3.2 Category
| Code | Description |
|---|---|
| 1 | City trips |
| 2 | Sun & Beach |
3.3 DurationType
| Code | Description |
|---|---|
| dagen | Days |
| nachten | Nights |
3.4 AgeType
| Code | Description |
|---|---|
| min,MIN | Minimum |
| max,MAX | Maximum |
3.5 PriceType
| Code | Description |
|---|---|
| OFF | Offer |
3.6 Facility
| Code | Description |
|---|---|
| 91 | With transfer |
| 92 | Without transfer |
| 94 | TUI Exclusive |
| 90 | Blocked for XML Booking |
Facilities like swimming pool, Sports facility and so on are exposed in the content file.
3.7 PaxType
| Code | Description |
|---|---|
| Adult | Adult |
| Child | Child |
| Infant | Infant (0-1 years) |
3.8 Others
For Accommodation, Unit, Board, TransportType and PricePer are available as G7 v3.1 types.
Most used
-
Accommodation: HOT = Hotel
-
Unit: xPK = 1PK, 2PK, 3PK = 1,2 of 3-person room
-
Board: LG,LO = Logies, Breakfast
For TUI 3 extra board types are defined:
PH - Half board plus
PV - Full board plus
PA - All inclusive plus
These board types are an extension of the normal half and full board and the all-inclusive. It could mean something like an extra drink with each meal. -
TransportType: VL = flight
-
PricePer: PA=Price for Person
4. Processing of XML files
Like mentioned before two workflows will be available to get availability and prices.
How to handle the full load will be described in paragraph 4.1.
The delta flow will be described in paragraph 4.2
4.1 Full Load
4.1.1 Filenames
Contains of :
- Country: NL
- Date and Time: 20240212
- Category: FLYANDSTAY
- Accommodation code: A0017191
- PackageCategory: SUNANDBEACH
- Accommodationcode+PackageID: A001719130153e3a-0061-4f12-b29e-f19cc623d97e
Format example:
NL_20240212_FLYANDSTAY_A0017191_SUNANDBEACH_A001719130153e3a-0061-4f12-b29e-f19cc623d97e.xml
4.1.2 Processing
Every file contains a full load of a package. A full load means that all existing data should be replaced with new data.
4.1.3 Delivery
For each run of the supply export process, a single zip file will be provided on the SFTP server containing all the supply files for that export. Since every day a full set of data will be provided, the zip files will be automatically removed after five days. They can also be removed by the OTA once they have retrieved the file.
4.2 Delta files
For delta flow there will be, just as with Full Load, for each available package a supply file which contains all the data. This data replaces all data sent before. For OTA, processing the file should be the same as for Full Load. The mutationType "Reset" means replace all. This file will be generated once a day (usually at night). This file will be, every day the new starting point for the next delta files. So it is needed to process this delta full load every day. The difference with full load is that for each package there will be a separate zip file containing the supply xml file. If in the TUI system during the day a (new) package is available for the G7 load, it will be delivered as a Full Load.
After Full Load there will be updates generated depending on price and availability changes, stop-sales, etc. in the TUI system during the day.
4.2.1 Filenames
Files will be placed on the ftp server in a different folder named "delta".
Delta full load : "2024_02_12_02_01_00_full_A0476319_5dc86d92-4de8-4394-aac7-c3dee7702c09_new.xml"
Delta files: "2024_02_12_03_15_57_delta_A0476319_5dc86d92-4de8-4394-aac7-c3dee7702c09_offerPriceDeleted.xml"
- Timestamp: yyyy_mm_dd_hh_mm_ss (example 2024_02_12_03_15_57)
- Prefix: delta
- Accommodation code: like A0476319
- PackageId: Guid (example 5dc86d92-4de8-4394-aac7-c3dee7702c09)
- Mutation: offerPriceAdded, offerPriceUpdated, offerPriceDeleted or Deleted (whole package)
4.2.2 Processing
The updates will be delivered in 2-hour cycles. These files will also be a zip file containing the supply xml file. In the cycle for each package, there could be six situations.
-
A new package becomes available for G7.
The xml content is the same as with the current full load. All prices need to be replaced with the new values. MutationType is "Reset". -
No files in a cycle for a certain package. This means for a package availability and prices are not added, changed or deleted.
-
Files with new Data
These files have "offerPriceAdded" in the name and the xml file itself has the mutationType "New". For example, a new room is added to the package, and all prices and availability are calculated for this room, or new departure dates and duration are made available. See code example.<SupplyResponse> <SupplyPackage> <MutationType>New</MutationType> <OfferType>1</OfferType> <Brand>TUI_NL</Brand> <PackageID>30153e3a-0061-4f12-b29e-f19cc623d97e</PackageID> <ProductInfo>...</ProductInfo> <SupplyTransportInfo>...</SupplyTransportInfo> <SupplyAccoInfo>...</SupplyAccoInfo> <SupplyPriceAvailabilityInfo> <SupplyPriceAvailability> <DepartureDate>2024-11-01</DepartureDate> <Duration DurationType="nachten">3</Duration> <TripDuration>4</TripDuration> <TransportAvailability> <Route RouteID="97782845-eee8-3bfb-8086-a0a9f9091434"> <PriceNote>0</PriceNote> </Route> </TransportAvailability> <UnitGroup> <Unit> <UnitID>5745ef4c-acb4-470b-9c68-43298d679292</UnitID> <Status>OK</Status> <BoardPrice> <BoardType>LG</BoardType> <Price Currency="EUR" Occupation="1" PricePer="PA" PriceType="OFF">139700</Price> <Price Currency="EUR" Occupation="2" PricePer="PA" PriceType="OFF">123900</Price> </BoardPrice> </Unit> </UnitGroup> <TransferAvailability>...</TransferAvailability> </SupplyPriceAvailability> </SupplyPriceAvailabilityInfo> </SupplyPackage> </SupplyResponse> -
Files with Deleted data (ex. rooms, prices)
These files have "offerPriceDeleted" in the name and the xml file itself has the mutationType "Deletion". For example
a room is blocked due to stop-sales. In the SupplyPriceAvailability group, prices are no longer there. This means remove all the prices for this Package, departure date, duration, route, unit and board. See code example.<SupplyResponse> <SupplyPackage> <MutationType>Deletion</MutationType> <OfferType>1</OfferType> <Brand>TUI_NL</Brand> <PackageID>a4e4a31c-b656-456d-8ff0-948e69766244</PackageID> <ProductInfo>...</ProductInfo> <SupplyTransportInfo>...</SupplyTransportInfo> <SupplyAccoInfo>...</SupplyUnitInfo> </SupplyAccoInfo> <SupplyPriceAvailabilityInfo> <SupplyPriceAvailability> <DepartureDate>2024-05-04</DepartureDate> <Duration DurationType="nachten">30</Duration> <TripDuration>31</TripDuration> <TransportAvailability> <Route RouteID="4ccfdf0e-157f-39ff-aff0-17c57616865a"> <PriceNote>0</PriceNote> </Route> </TransportAvailability> <UnitGroup> <Unit> <UnitID>4945d24e-4368-4ea1-b289-39c190aabad2</UnitID> <Status>OK</Status> <BoardPrice> <BoardType>AI</BoardType> </BoardPrice> </Unit> </UnitGroup> <TransferAvailability>...</TransferAvailability> </SupplyPriceAvailability> </SupplyPriceAvailabilityInfo> </SupplyPackage> </SupplyResponse> -
Files with updates These files have "offerPriceUpdate" in the name and the xml file itself has the mutationType "Mutation". For example prices or availability is changed. See code example.
<SupplyResponse> <SupplyPackage> <MutationType>Mutation</MutationType> <OfferType>1</OfferType> <Brand>TUI_NL</Brand> <PackageID>3fab0c91-9aff-4f9b-8ca8-6d6203231e44</PackageID> <ProductInfo>...</ProductInfo> <SupplyTransportInfo>...</SupplyTransportInfo> <SupplyAccoInfo>...</SupplyAccoInfo> <SupplyPriceAvailabilityInfo> <SupplyPriceAvailability> <DepartureDate>2024-02-28</DepartureDate> <Duration DurationType="nachten">3</Duration> <TripDuration>4</TripDuration> <TransportAvailability> <Route RouteID="070b3766-b119-3715-96b6-5e18055c8458"> <PriceNote>0</PriceNote> </Route> </TransportAvailability> <UnitGroup> <Unit> <UnitID>9840df67-e17e-4564-8615-030cc4edef90</UnitID> <Status>OK</Status> <BoardPrice> <BoardType>LO</BoardType> <Price Currency="EUR" Occupation="1" PricePer="PA" PriceType="OFF">116160</Price> <Price Currency="EUR" Occupation="2" PricePer="PA" PriceType="OFF">84060</Price> </BoardPrice> </Unit> </UnitGroup> <TransferAvailability>...</TransferAvailability> </SupplyPriceAvailability> </SupplyPriceAvailabilityInfo> </SupplyPackage> </SupplyResponse>
Variation: If a room has prices for occupation of 1 to 4 passengers, it could be possible that due to allotment in transport, the price for 3 and 4 passengers are no longer available. In that case a "offerPriceUpdated" will be sent which contains prices for 1 and 2 passengers. So for OTA prices for 3 and 4 passengers should be deleted. In this case there is no "offerPriceDeleted" send.
- Files with a deletion of a whole package
These files have "deleted" in the name and the xml file itself has the mutationType "Deletion". For example TUI has
removed a whole package for sale. See code example.
<SupplyResponse> <SupplyPackage> <MutationType>Deletion</MutationType> <OfferType>1</OfferType> <Brand>TUI_NL</Brand> <PackageID>5faa3d1f-4e7c-4714-91cf-b80439846fcd</PackageID> </SupplyPackage> </SupplyResponse>
4.2.2 Delivery
Files will be placed in a separate folder on the SFTP server named "delta". In this folder there will be subfolders for each day. Zip files will be automatically deleted after 5 days. They can also be removed by the OTA once they have retrieved the file. Important is that files with the same packageID are be processed in timestamp order (which is in the filename).
4.4 SFTP authentication / Applying for a G7 Supply SFTP account
SFTP authentication is done through a combination of a username and a SSH key pair.
In order to obtain an SFTP account, you will need to create a SSH encryption key pair and provide us with the public key of that pair.
We will attach the public key to your account and provide you with a username. Upon login, you will need to provide the username and public key which we will match to our local copy of the key attached to your account.
4.4.1 How to create a SSH key pair
The method of creating a SSH key pair depends on the platform that is being used. The webpage linked below describes how to create a key for either Windows or Linux and also describes which algorithm types are supported.
The key generator tool creates a private key file (
For each environment, a key pair needs to be created, so one key pair for Playground and one for Production.
Send the public key files to us at b2bota.g7.support@tui.nl. We will create the corresponding accounts and provide a login name for the SFTP server. Never send us the private key, this is only for use at your side of the transaction and sharing it will result in a security breach.
https://docs.aws.amazon.com/transfer/latest/userguide/key-management.html
4.4.2 Using the SSH key pair
How to use the key pair to connect to the SFTP server depends on the FTP client used, but generally you provide the username and the location of the private key file to the FTP client. The private key will not be transferred over to the server, but will only be used to verify that the public key we have registered is valid and belongs to the account that is making the connection.
Some examples of how FTP clients are called:
PuTTY (Windows):
psftp -i <directory i.e. .ssh>/<key_name>.ppk <username>@<server address>
Unix:
sftp -i ~/.ssh/<key_name> <username>@<server address>
