Introduction
This is a step-by-step guide to help Online Travel Agents (OTAs) integrate their booking system with TuriTop via API.
The portal developers.turitop.com displays in a general way all the available API methods available to third-party developers. When your request is approved, along with the documentation, you will receive the credentials needed to start using the API in the production environment: short_id and secret_key.
Phases
The integration process is divided into the following phases: Development, Live Testing, and Production.
Development
In this phase, which can take up to 30 days, you should test all the following actions:
- Authentication
- Getting product data info including pricing, pick-ups, and custom questions.
- Checking the availability
- Transfers
- CRUD Bookings
These first tests will be done in a different environment (https://app.turitopsandbox.com/v1). Therefore you must create an account in our Sandbox test environment by accessing https://app.turitopsandbox.com/admin/login and clicking on "Don’t have an account? Sign Up":
Once you have created the account make sure to get in touch with our support team at help@turitop.com to provide them with the Company ID (the alphanumeric code in the top-right corner of your panel). Then they will provide this account with the necessary access to work with the API:
You will have different API credentials depending on the environment.
Keep in mind you will need to create test services and bookings within this account so you have some data to work with during the integration. If you have any queries while creating these items or need assistance to get a provider account to perform resale tests, don’t hesitate to contact our support team.
If you are making tests from the "Try it out" button in our API Documentation, make sure to use the right environment. You can download the full API specification (for using Postman, Insomnia, or any other similar software) from this link.
During this phase, you will have access to our API team to answer your questions and you may also request a first meeting with them, if needed, by writing to our support team at help@turitop.com.
Authorization
Our API uses the standard OAUTH 2.0 for the authentication and requires two parameters to identify your company:
- Company short ID ("short_id")
API key ("secret_key")
Both can be found on your TuriTop control panel by navigating to Company >>> Components/Integrations >>> TuriTop API.
The company short_id is a fixed value composed of an uppercase character followed by a number used to identify your company in our system. You can also find it in the top-right corner of your TuriTop admin panel.
Be aware that anyone with your short_id and secret_key can do actions on behalf of your company, so make sure you store the API key safely and generate a new one when in doubt.
-Grant
Use the 'Grant' endpoint (/authorization/grant) to obtain the access_token and refresh_token.
Store the access token locally, without using the grant more than necessary. The access_token expires after 1 hour and the refresh_token after 90 days. When the access token is about to expire, use the refresh token to generate a new access token.
| POST {{url}}/authorization/grant |
||||
|
Parameters |
||||
|
{ "short_id": "company short ID", example: T444 "secret_key": "API secret key" example: mfzOyh=1O3M6T34ev0EA1fC9lyJUAFgSBRxt_1 } |
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Wrong credentials | |||
Examples
-Refresh
Use the 'Refresh' endpoint (/authorization/refresh) to get a new access token after the former is about to expire or has already expired.
| POST {{url}} /authorization/refresh |
||||
|
Parameters |
||||
|
{ "refresh_token": "refresh token" example: eyJhbGciJzaGEyNTYiLCJ222... } |
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Wrong credentials | |||
Examples
The access token is encoded using industry-standard JWT (RFC 7519)2. The recorded data is divided into 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. On the JWT website, there is a tool available to enter the token to decode it and get this information.
Product data
-Get products
To get the complete array of products available in your TuriTop account, use the 'Get products' endpoint (/product/getproducts).
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.
| POST {{url}} /product/getproducts |
||||
|
Parameters |
||||
|
{ example: eyJhbGciJzaGEyNTYiLCJ222... example: en example: T000 |
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Invalid access token | |||
Examples
Type (type) vs. Category (company_categories): In our system, suppliers can assign a “Type” to a product, which are generic labels defined by TuriTop. However, “Categories” are created by the suppliers. Not all suppliers create nor name categories practically for the OTAs, so generally speaking, the “Type” field may be more useful for an OTA since it forces all suppliers to choose one from a fixed list.
Once you have obtained the IDs of each product ('product_short_id'), you can use them in the following endpoints to get additional information about each one:
-Get (tickets)
The 'Get' endpoint (/tickets/get) in the "Tickets" module will help you retrieve the details of the available ticket options for the consulted product.
| POST {{url}} /tickets/get |
||||
|
Parameters |
||||
|
{ example: eyJhbGciJzaGEyNTYiLCJ222... example: P1 "language_code": "language code" example: en } |
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Invalid access token | |||
| 400 Bad Request | Invalid short_id or parameters | |||
Examples
In TuriTop, for each product, the suppliers can create as many pricing options as they want, and we call them tickets. Therefore, to get the product pricing you need to use this endpoint.
Suppliers will usually type things like “Adult” or “Child”, but they have total freedom on how to call the tickets/pricing options (e.g. Adult resident, VIP, Group, Senior, General ticket, etc).
Also, the supplier is responsible for adding the translations. For example, for "language_code": "en" a ticket might be called “Adult” and for the "language_code": "es" it will be “Adulto”. 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 from the supplier (currently there is no support from the API to obtain that).
-Get client form
The 'Get client Form' endpoint (/product/getclientform) in the "Product" module retrieves the fields a customer must fill in when making a booking for a product.
| POST {{url}} /product/getclientform |
||||
|
Parameters |
||||
|
{ example: eyJhbGciJzaGEyNTYiLCJ222... example: P1 example: en |
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Invalid access token | |||
| 400 Bad Request | Invalid product_short_id or parameters | |||
Examples
Regarding the fields in the booking form, suppliers in TuriTop can choose per service, from a wide range of fields provided by TuriTop or by creating their own fields, what information they require from a customer to make a booking, and what fields are mandatory. As with the tickets, they will need to translate the custom questions they may create.
Transfer
This is needed when the providers use the Transfer functionality.
TuriTop has an advanced functionality to help suppliers manage their pick-up services. It works as follows: the suppliers can create a list of pick-up points, and each pick-up point can have its own list of hotels. Then, when the end-users make a booking, they can choose a hotel, and the system will return the corresponding pick-up point and time of pick-up.
To check if any of the products you are reselling use this functionality, use the 'Get Hotels by Event Time' endpoint (/product/transfer/gethotelsbyevent) to obtain the list of hotels available for each event.
| POST {{url}} /product/transfer/gethotelsbyevent |
||||
|
Parameters |
||||
|
{ "access_token":"access_token", example: eyJhbGciJzaGEyNTYiLCJ222... "data": { "product_short_id": "product short ID", example: P1 "date_event": "event time in Epoch format", example: 1709202347
|
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Invalid access token | |||
| 400 Bad Request | Invalid product_short_id or parameters | |||
Examples
- If the call returns an empty result, it means the product does not require a transfer/pick-up point for its booking.
- If you get results, include the hotel selection in the 'Reserve Tour' endpoint (/booking/tour/reserve), as explained later in this article, to associate the corresponding pick-up point to the booking.
If you have any questions about implementing the Transfer functionality in the booking flow, feel free to contact us at help@turitop.com.
Availability
Two main endpoints will allow you to fetch the availability of the products and their status:
- Open: You can insert bookings (min. 1 PAX).
- Closed: It means an event exists with that specific date and time, but it is no longer accepting bookings because it’s full or has been canceled.
Closed events codes:
1000 - Event is full
2000 - Event was autoclosed
3000 - Event already started
4000 - Too late for online sales
5000 - Maintenance or out of season
6000 - Event closed during the entire month
7000 - All events closed during the entire month
8000 - Single event closed
9000 - Entire day closed
To optimize the user experience and reduce API consumption, store availability results in an internal cache. Most OTAs store the results for 12 hours or more to avoid excessive API calls. This ensures efficient information management and a quicker response for your users.
For the event dates and times, we use the Epoch Standard. If you request the 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.
-Get (events)
We advise you to retrieve the available events for each product using the 'Get event' endpoint (/product/tour/getevents).
This API call provides a quick response, allowing you to view and print the availability of each event in your booking calendar. Therefore, it's advised for larger date range searches.
| POST {{url}} /product/tour/getevents |
||||
|
Parameters |
||||
|
{ example: eyJhbGciJzaGEyNTYiLCJ222... example: P1 example: 1602590400 example: 1602590600 example: en |
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Invalid access token | |||
| 400 Bad Request | Invalid product_short_id or parameters | |||
Examples
-Get available by tour
Later, to recover detailed information about each event, such as remaining capacity, specific ticket availability, prices, etc., use the 'Get available by tour' endpoint (/product/tour/getavailable). You can use this endpoint either to check a specific event or a date range.
| POST {{url}} /product/tour/getavailable |
||||
|
Parameters |
||||
|
{ example: eyJhbGciJzaGEyNTYiLCJ222... example: P1 example: 1602590400 example: 1602590600 example: en example: "293123": 0 example: true example: true example: promo50 |
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Invalid access token | |||
| 400 Bad Request | Invalid product_short_id or parameters | |||
Examples
CRUD Bookings
In this section, you can find the different endpoints and actions you can perform as part of the booking workflow.
-Booking Reservation
To hold a seat and register a provisional booking while awaiting confirmation, use the 'Reserve Tour' endpoint (/booking/tour/reserve). This endpoint allows you to secure the availability of the tour or service while the confirmation process takes place.
We strongly advise you to include in the "notes" parameter the following clarification: "notes": "This is a pre-booking - Your Company Name", as to warn the provider where this "Pending" booking is coming from.
TuriTop will only allow you to insert a provisional booking if there are enough places at that time. If places are no longer available, we suggest you clear your cache for that particular product and show a message for the customer to search again (this should be very uncommon even with 12-hour caching).
This endpoint has a parameter called 'expires_in' that will allow you to specify how long you want to retain these seats (for example, 300 seconds). If the booking is not confirmed before the specified expiration date in 'expires_in', TuriTop will automatically delete the booking and release the seats. Confirmed bookings are not auto-deleted.
| POST {{url}} /booking/tour/reserve |
||||
|
Parameters |
||||
|
{ "access_token":"access_token", example: eyJhbGciJzaGEyNTYiLCJ222... "data": { "product_short_id": "product short ID", example: P1 "booking": { "language_code": "language code", example: en "event_start": start date and time in Epoch format, example: 1567416600 "hotel": hotel pick-up point code, example: 59872 "ticket_type_count": { " ticket identifier ": ticket quantity example: "33849": 1 }, example: 300 example: 14852 example: This is a pre-booking |
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Invalid access token | |||
| 400 Bad Request | Invalid product_short_id or parameters | |||
Examples
-Booking Confirmation
After confirming payment through your payment gateway, use the 'Edit Tour' endpoint (/booking/tour/edit) to confirm the booking. Edit the status from "Pending" to "Confirmed".
We strongly advise setting the "send_booking_email_copies" parameter as true, so the provider receives a confirmation email from TuriTop with booking details. They may not review emails from all OTAs, but they do review emails from TuriTop since that's where they've centralized reservations. And, also, to include the booking ID for your platform in the "notes" parameter.
| POST {{url}} /booking/tour/edit |
||||
|
Parameters |
||||
|
{ "access_token":"access_token", example: eyJhbGciJzaGEyNTYiLCJ222... "data": { example: T000-250124-17 "override_client_data": true or false value, example: true example: en "event_start": start date and time in Epoch format, example: 1567416600 "ticket_type_count": { " ticket identifier ": ticket quantity example: "33849": 1 }, "total_price": total price for booking, example: 149 "payment_partial": partial payment for booking, example: 50 "status": "booking status", example: "paid" "gift_certificate": true or false value, example: true "gift_details": { example: "Lois Griffin" "gift_email_date": date to send the email in Epoch format, example: 1567416600 "email_of_beneficiary": "beneficiary's email address", example: "lois_griffin@hotmail.com" "dedicatory": "buyer's dedicatory" example: "From your towel boy!" }, "payment_gateway": "payment gateway used", example: "stripe" "client_data": { example: "Peter Griffin" example: "Peter Griffin" example: "+3454681208" example: "+3454681208" "nationalid": "identity document", example: "787775426821X" example: "11/01/1981" example: "37" example: "English" example: "USA" example: "Texas" example: "I need a size XXXL for the life jacket" example: "Tenerife Palace" example: "Suite A23" example: "31 Spooner Street" example: "47616" example: 1 example: 1 "customtext": "custom form response" "customtext2": "custom form response" "customtext3": "custom form response" "customtext4": "custom form response" "customtext5": "custom form response" "customtext6": "custom form response" "customtextarea": "custom form response" "customtextarea2": "custom form response" "customcheck": acceptance (1) or refusal (0) value example: 1 "customcheck2": acceptance (1) or refusal (0) value "customcheck3": acceptance (1) or refusal (0) value "custom": "custom form response" "custom2": "custom form response" "custom3": "custom form response" "custom4": "custom form response" "custom5": "custom form response" }, "comments": "customer's comments", example: "I need the XXXL size" "notes": "internal notes for the booking", example: "The customer has XXXL size" "hotel": hotel pick-up point code, example: 59872 "send_booking_email": true or false value example: true (send email to customer) "send_booking_email_copies": true or false value example: true (send email to company) "user_id": user id code, example: 14852 "reseller_company_short_id": reseller company id code, example: R000 "short_id_seat": "seat in auditorium services", example: "F_PP_1_24" } |
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Invalid access token | |||
| 400 Bad Request | Invalid short_id or parameters | |||
Examples
Take this opportunity to insert the data collected in the booking form built through 'Client Form' (/product/getclientform). You can remember how that endpoint worked in the section above.
Finally, if the payment is unsuccessful, release the occupied seats using the 'Delete' endpoint (/booking/delete), as explained in the Booking Cancellation section below, to avoid retaining them longer than necessary.
Possible status values for OTAs:
- pending
- confirmed
- canceled
-Booking Edition
Whenever you need to make changes to a booking after confirming it, use the 'Edit Tour' endpoint (/booking/tour/edit), as explained in the section above.
Additionally, we strongly advise sending the 'send_booking_email_copies' parameter as true again. This ensures that the provider receives an updated confirmation email from TuriTop with the details of the edited booking. And, also, to include the booking ID for your platform in the "notes" parameter.
-Booking Cancellation
If you need to cancel a booking, please, follow these steps:
Edit Booking: Use the 'Edit Tour' endpoint (/booking/tour/edit), explained in the section above, to modify the booking you want to cancel. Change the status of the booking to 'Canceled.' This marks the booking as canceled and is a necessary step before deletion.
Delete Booking: After editing, use the 'Delete' endpoint (/booking/delete) to release the occupied seats and delete the booking.
| POST {{url}} /booking/delete |
||||
|
Parameters |
||||
|
{ "access_token":"access_token", example: eyJhbGciJzaGEyNTYiLCJ222... "data": { example: T000-231123-1 } |
||||
| Responses |
||||
| 200 OK | Success | |||
| 401 Unauthorized | Invalid access token | |||
| 400 Bad Request | Invalid short_id or parameters | |||
Examples
Live Testing
In this phase, you will begin making operations in the production environment (https://app.turitop.com/v1). However, you will be required first to achieve our certification:
1. TuriTop API OTA Certification: perform all the actions outlined below, while reselling the services of our test account (L797 - Live Testing Account) and following the guidelines of the Development section.
A. Initiate a booking and allow the system to automatically delete it upon expiration.
B. Create a booking, process payment, and formally confirm the booking through TuriTop.
C. Create a booking, process payment, confirm the booking via TuriTop, subsequently cancel the booking, and release the associated seats.
D. Create a booking with an included transfer option.
To connect your panel with our test account and resell its services, you must find its products via the Marketplace and make a resale request:
Reach out to help@turitop.com so we can approve the resale request.
2. Hold a validation meeting with our API support team.
To request a validation meeting with our team, please, email the TuriTop Booking IDs corresponding to each scenario to our support team (help@turitop.com). Additionally, include the API requests executed during steps 1, 3, and 4 for assessment purposes.
Once your application can handle all the scenarios and you attend the validation meeting, most of the development job will be done and you will be able to start working in the production environment with real suppliers.
Production
The final step will be sending invitations to the suppliers for reselling their products through the Marketplace. They will need to accept this request for you to insert bookings for them. Furthermore, it’s advised to start with max. 10 products of suppliers that have a close relationship with you, informing them in advance that they will be beta testers, and then progressively start reselling more activities.
TuriTop doesn’t need to know the commission 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.
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.
Tips & General Notes
- At https://developers.turitop.com you can click on the “Model” tab to view a full description of all the accepted parameters per endpoint and their data type.
- Please, reach out to our support team (help@turitop.com) when you are ready to start Live Testing in case you need further assistance.
Comments
0 comments
Please sign in to leave a comment.