File integration with Koala
Introduction
The classic and most efficient way of interacting with Koala is to call our Partner API directly from your applications. It provides many features to cover the full life-cycle of a product, from sells to claims.
The file integration is another way to integrate with Koala that provides a more basic set of features. Currently, the supported features are:
- creating subscriptions for Koala products
The concept of the file integration is to report every operation you made in a file containing the data needed to perform those operations. Then, you transfer this file to Koala which is able to process the data of the file to perform the adequate operations.
File formats
The files containing the operations data must match an expected format. If the data in the file does not match the expected format, Koala will not be able to process the operations.
File extension
The files must have an .xlsx extension. This is the file format generated by Excel and many other spreadsheet tools
are also capable of producing it.
File structure
A single file can contain data for multiple types of operations. However, data for different operations must be located in different spreadsheets of a file.
The structure of the file also changes depending on the type of operation contained in the spreadsheet and the type of product sold. It means that depending on those two variables, the columns expected to be present in the file are different.
File structure of a file containing subscriptions for products covering stays
Columns of the file
The file must contain the following columns:
| Column name | Description of the content | Example value |
|---|---|---|
| Customer First Name | The last name of the customer paying for the booking. | John |
| Customer Last Name | The first name of the customer paying for the booking. | Doe |
| Customer Email | The email address of the customer paying for the booking. | john.doe@gmail.com |
| Customer Language | The language of the customer paying for the booking. It must be a valid language code like en-GB, fr-FR , de-DE . | en-GB |
| Traveller First Name | The first name of the traveller. Note that one row per traveler must appear in the file. | Kevin |
| Traveller Last Name | The last name of the traveller. Note that one row per traveler must appear in the file. | Doe |
| Booking Number | The booking number of the booking in your system. | ABC123 |
| Booking Date | The date at which the booking was booked, in a YYYY-MM-DD format. | 2024-01-27 |
| Booking Price (excluding product price) | The price of the booking without considering the price of the Koala product that was sold. It must be a number without the currency symbol. | 550 |
| Product | The name of the Koala product that was sold. | Flex - 90% |
| Product Price | The price of the Koala product that was sold. It must be a number without the currency symbol. | 13,75 |
| Currency | The currency in which prices are expressed. It must be a valid ISO 4217 code. | EUR |
| Experience Name | The name of the experience booked by the travellers. | Tour of the Ardennes vineyards |
| Country Code | The country code of the country where the experience takes place. It must be a valid ISO 3166-1-alpha-2 code. | FR |
| Start Date | The start date of the experience, in a YYYY-MM-DD format. | 2024-04-13 |
| End Date | The end date of the experience, in a YYYY-MM-DD format. | 2024-04-17 |
A line must appear in the file for each passenger in each booking. On each of these lines, all the information for the booking must appear and must be consistent. The only differences between the lines corresponding to travellers from the same booking must be in the columns specific to travellers, i.e. the ‘Traveller First Name’ and ‘Traveller Last Name’ columns.
Below is an example that contains two bookings: the first booking was made by a family of 3 people while the second booking was made by a single person.
In the first case, there are 3 lines, each representing one traveller of the booking and containing the exact same information except in the “Traveller First Name” and "Traveller Last Name" columns.
In the second case, there is only one row which corresponds to the only traveller of this booking.
In each case, the customer is one of the travellers of the booking. However, the customer may not appear amongst the travellers. But the customer information must be the exact same for each traveller of a single booking.
| Customer First Name | Customer Last Name | Customer Email | Customer Language | Traveller First Name | Traveller Last Name | Booking Number | Booking Date | Booking Price (excluding product price) | Product | Product Price | Currency | Experience Name | Country Code | Start Date | End Date |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Thierry | Parmentier | thierryparmentier@yahoo.fr | fr-FR | Thierry | Parmentier | 654321 | 2024-01-27 | 550 | Flex - 90% | 13,75 | EUR | Tour of the Ardennes vineyards | FR | 2024-04-13 | 2024-04-17 |
| Thierry | Parmentier | thierryparmentier@yahoo.fr | fr-FR | Joanna | Parmentier | 654321 | 2024-01-27 | 550 | Flex - 90% | 13,75 | EUR | Tour of the Ardennes vineyards | FR | 2024-04-13 | 2024-04-17 |
| Thierry | Parmentier | thierryparmentier@yahoo.fr | fr-FR | Marc | Parmentier | 654321 | 2024-01-27 | 550 | Flex - 90% | 13,75 | EUR | Tour of the Ardennes vineyards | FR | 2024-04-13 | 2024-04-17 |
| John | Doe | john.doe@yahoo.fr | en-GB | John | Doe | 123456 | 2024-01-27 | 600 | Flex - 90% | 15,00 | EUR | French riviera tour | FR | 2024-04-13 | 2024-04-17 |