Available for plans: VIP | Enterprise
Introduction
This is a step by step guide to help Online Travel Agents (OTAs) integrate their own booking system with TuriTop via API.
With this document you will also receive a TuriTop account containing an API with test products and test bookings, so you have some data to work with during the integration.
The portal developers.turitop.com explains in a generic way all the available API methods available to third party developers. We will be making references to that portal for all code samples.
Phases
The integration process is divided into the following phases: Development, Live Testing and Production.
Development: This phase starts when we have the first meeting and can take up to 30 days. During this phase, you will have free access to our API team, who will answer your questions.
During this phase you will only work with the test products we have created for you, completing all the following actions:
● Authentications
● Get product data info including pricing, pick-ups and custom questions
● Availability
● CRUD Bookings
● Pick-ups (optional)
Live Testing: This section starts when all the development work has concluded to the best of your knowledge and testing skills.
You have to select the first beta testing products (up to 10) from all the suppliers that use TuriTop. Furthermore, it’s important to start with suppliers that have a close relationship with you, informing them in advance that they will be beta testers.
Suppliers must authorize you to consult availability for their product. Therefore, you need to log in to your TuriTop account, click on the “marketplace” tab, select the desired product and send a resell invitation1.
Production: This section starts when you have successfully connected 10 products and start gradually adding more products.
Development
Authentication
Our API uses the standard OAUTH 2.0 for authentication. We require two parameters to identify your company: The company short_id and the API.
The company short_id is how we identify your company in our system and it never changes. You can find it in the upper right corner of your TuriTop admin panel (an uppercase character followed by a number).
The API Key is visible in your TuriTop account under the Company tab >> Components/integrations >> TuriTop API. In this section you will also find the short_id of your company.
Be aware that anyone with your short_id and API key can do actions on behalf of your company, so make sure you store the API key safely and generate a new one when you think is appropriate.
Once you have your short_id and API key, use grant from the Authorization Module to obtain the access token and refresh token (the access token expires after 1 hour and refresh token after 90 days).
Important: store the access token locally, without using the grant more than necessary. When the access token is about to expire, use the refresh token to generate a new access token.
Moreover, access token is encoded using industry standard JWT (RFC 7519)2 . The decoded data is divided in three sections: header, payload and signature. You will just need to check the payload part of the token to obtain the iat and the expiration date. Please, keep in mind that these dates are expressed in Epoch format.
1 TuriTop doesn’t need to know the commision agreement between the OTA and the supplier. Therefore, when making the resell petition you can type 0% as commission and handle it all outside TuriTop.
2 In the JWT website, there is a tool available to enter the token to decode it and get this information
Product data
Use the get products module to retrieve the array of products that your company contains. During the development phase, you will only have a few products you own, but in the future your product list will grow to include all the real products that you will resell from suppliers using TuriTop.
Note: the Get products module has a parameter called “supplier_company_short_id” that will let you filter by supplier id. During the development phase, you own all the products and have no suppliers, so remove the parameter from the call, otherwise you may get an empty array of products.
In TuriTop, for each product the supplier can type as many pricing options as they want, and we call them tickets. Therefore, to get the product pricing you need to use Get tickets module.
Suppliers usually type things like “Adult” or “Child” as pricing options, but they have total freedom about how to call those tickets (e.g. Adult resident, Adult VIP, Group, Senior, etc).
They also add the translations for those ticket names. For example, for "language_code": "en" a ticket might be called “Adult” and if "language_code": "es" it will be “Adulto”. The supplier is the one adding the translation, so if a string is not translated, it means the supplier hasn’t translated it. Do not confuse this language with the language in which the activity is offered. That should be part of the product description and you should receive it directly by the supplier (currently there is no support from the API to obtain that).
Regarding the fields in the booking form, suppliers in TuriTop can choose per product what information they require from a customer at the time of booking. Use Get client form to the array of fields required by the supplier per product, such as customer name, phone, hotel, etc.
Each supplier can choose between a wide range of fields provided by TuriTop, or write their own questions. They can also define what fields are required, which ones are optional and translate the custom questions written by them.
Once you map all products, tickets and client form fields, your can start working on availability.
Product type vs Category: In our system, suppliers can assign a “type” to a product, which are generic labels defined by TuriTop. However, “Categories” are created by suppliers. Not all suppliers create categories nor name them in a useful way for OTAs, so generally speaking, “type” may be more useful for an OTA since it forces all suppliers to choose one from the same list of types.
Availability
Use Get event to fetch the array of events (sessions) in which a product can be booked. Events have two statuses: Open and closed.
● Open: You can insert bookings, at least 1 person
● Closed: It means an event was with that specific date and time, but it is no longer receiving booking, because it’s full or has been cancelled.
For dates we use the epoch standard. If you ask availability for a certain range, e.g. 1 month, and you get no events in the response, it means no events have been enabled by the supplier for that period.
Use Get event for large date ranges because it has the fastest response time. Then, when you need more information, like the availability per ticket (pricing option), use Get available by tour.
You are expected to store availability results in an internal cache to improve user experience and avoid excessive API calls. Most OTAs store availability results for 12 hours or more.
CRUD Bookings
To avoid overbooking when caching availability, use Reserve Tour to make a provisional booking before loading the payment gateway to your customers. TuriTop will only allow you to insert a provisional booking if there are sufficient places at that time. If places are no longer available, we suggest you clear your cache for that particular product and show a message to the customer to search again (this should be very uncommon even with 12 hours caching).
Reserve Tour has an optional parameter that will let you specify for how long you want to hold those places (e.g. 15 min). Then, if the booking is not confirmed before the expiration date, TuriTop will auto-delete that booking, releasing the taken seats.
In addition, once you received confirmation from your payment gateway that the payment was successful, use Edit Tour to change the status from “pending” to “confirmed” (confirmed bookings are not auto-deleted).
If your payment gateway gives you an unsuccessful response, we would appreciate if you make the extra effort of using Delete to release places immediately, to avoid holding them longer than necessary.
Pick-ups
Note: You can skip this part if none of your suppliers use our pick-up functionality.
TuriTop has an advanced functionality to help suppliers manage their pick-up services. It works as follows: The supplier can create its own list of pick-up points, and each pick-up point can have it’s own list of hotels. Then, when the end-customer is going to make a booking, she/he chooses a hotel and the system returns the corresponding pick-up point and time of pick-up.
If you encounter a supplier that uses the pick-up functionality, use Get hotels by event time to fetch the list of all available hotels. Then, include one of those hotels in the Reserve Tour so that the corresponding pick-up point is associated.
Live testing
Once your application is able to handle all the scenarios outlined above, most of the development job will be done.
The next step will be sending invitations through the marketplace to supplier for reselling their products, which they need to accept before you are able to insert bookings for them.
Use Get Suppliers to obtain the array of suppliers that agreed to resell your products. Then, when using Get Product, you can use the parameter supplier_company_short_id to filter and get the products of one particular supplier.
Please reach our support team (help@turitop.com) when you are ready to start Live testing and we will give further assistance.
Tips & general notes
- At https://developers.turitop.com click on the “model” link to view a full description of all the accepted parameters per end point.
Comments
0 comments
Please sign in to leave a comment.