{{ wiki:www.travanto.de.png}}
\\
\\
\\
\\
====== 2. General Concepts ======
\\
===== 0. Revision history =====
^ Date ^ Author ^ Description ^
| 2019/01/10 | t.hochmuth | Added documentation of object service to create new properties from scratch |
| 2017/04/02 | t.hochmuth | Added push notifications, bookings and enquiry services |
| 2016/12/28 | t.hochmuth | Added description and amenities services |
| 2016/11/10 | t.hochmuth | Added picture service |
| 2016/09/26 | t.hochmuth | First working API version supporting prices and availibilities |
===== A. Integration possibilities and use of API =====
Our API is a standard REST-style API exclusively accepting requests and providing data in JSON format. There is no corresponding XML version. Authentication with the API is possible using the provided API-Key; username and password are not necessary as API key usage is restricted to one host only. If you have not yet received your key, please contact your account manager or send an e-mail to [[schnittstelle@travanto.de]].
\\
==== HTTP methods ====
* Our API is designed to keep traffic and load as low as possible. So please use it responsibly and make use of the different HTTP methods that are at your disposal.
* Every service offers up to four different HTTP methods
- POST Used to create new sets of information
- PUT Used for full updates or replacing sets of information
- GET Used to retrieve certain sets of information
- DELETE Used to delete sets of information
\\
==== Headers and authentication ====
The most important header is the **Authorization** header. It delivers a API-key for the API so that the target user and his objects can be accessed. In addition the access to all the service actions depends on this token, too.
For requests that contain a body (always a JSON document) we recommend to set a matching **Content-Length** header. It delivers the length of the content so that the API knows how much data it can expect. This applies to most if not all POST and PUT requests. We also recommend to send the **Content-Type** header with the value //application/json// in these cases.
\\
==== HTTP Request Examples ====
GET /service/occupancies/1/ HTTP/1.1
Host: connect.travanto.de
Authorization: insert_apikey_here
DELETE /service/occupancies/1/ HTTP/1.1
Host: connect.travanto.de
Authorization: insert_apikey_here
POST /service/occupancies/ HTTP/1.1
Host: connect.travanto.de
Authorization: insert_apikey_here
Content-Type: application/json
Content-Length: 81
{"occupancies":[{"object_id":1,"date_from":"2016-01-01","date_to":"2016-01-10"}]}
PUT /service/occupancies/1/ HTTP/1.1
Host: connect.travanto.de
Authorization: insert_apikey_here
Content-Type: application/json
Content-Length: 98
{"occupancies":[{"occupancy_id":1,"object_id":1,"date_from":"2016-02-01","date_to":"2016-02-10"}]}
\\
==== HTTP Result Examples ====
You can expect the response of all HTTP methods to carry a JSON document containing either the requested result or some details on what went wrong. Besides that a proper HTTP status code will be given. The following examples are for the case of a GET request to an occupancy with success and error response.
[json]
{"OK": 1,"Request": {"Method": "GET","Path": "/service/occupancies/1"},"OccupanciesServiceResult": [{"occupancy_id": 1,"object_id": 1,"date_from": "2016-04-01","date_to": "2016-04-10","guest_name": "","guest_amount": 0,"comment": ""}]}
[/json]
[json]
{"OK": 0,"Request": {"Method": "GET","Path": "/service/occupancies/2"},"Errors": {"code": 10152,"msg": "Permission Error: This api key doesn't have access to all involved objects."}}
[/json]
\\
\\
----
===== B. Data structure and logic =====
Using our system, you need to be aware of the property structure and the different bookings models Travanto offers. We also give a useful perspective of hwo to look at the different types of information.
\\
==== Booking models ====
There are three different models available your properties could be advertised to guest to. For the time being, these models do not have any influence on the way information has to be sent to our system. It is meant to provide a better understanding.
//**Directly / Instantly bookable**//\\
If you have chosen this model, your properties can be booked right away on our platform without anyone having to confirm. The entire booking including payment is being handled by Travanto.
//**Direct owner contact**//\\
If you have chosen the classical approach, no online booking of the property is possible. Rather, the guest sends an unbinding request to the landlord via mail or contacts him via phone. Both parties settle the deal independently from Travanto.
The different models do not influence the way you connect to our system or send information. It merely serves as a better understanding of Travantos system. That is, whatever model you use, service request are equal.
\\
==== Property scheme/hierarchy ====
Travanto's focus lies on vacation rentals and holiday homes. Hotels or bed & breakfasts cannot be found on our sites. Accordingly, our scheme is a unit based scheme handling each property as a single and independent instance. There is no parent-child dependency that needs to be followed. If, for example, you offer multiple apartments in one big complex, you have to create the exact amount of properties in our system with all the information that are needed for every single one of them. Neither is it possible to create only one apartment and set a counter for the amount of identical properties nor is it allowed to mention the amount of different units anywhere in the description section.
This hierarchy will be important if you want to use our property service and create entirely new properties using the API. The service is however still being developed. =)
\\
==== Date logic ====
Assuming we have a reservation from with an arrival on the 24th and a departure on the 31st of August, the corresponding occupied period will be from the 24th to the 31st and not to the 30th. The last day of a period is therefore the departure day and not the last night.
\\
==== Information perspective ====
For the sake of a better understanding and an easier integration, our data can logically be divided into three groups.
* **Static property information**
Generally need to be provided once or change less frequently than dynamic information
* [[api:services:property|Property information / Building a property]] (Hard facts)
* [[api:services:pictures|Pictures]]
* [[api:services:amenities|Amenities]]
* [[api:services:descriptions|Descriptions]]
\\
* **Dynamic property information**
Dynamic property information comprise [[api:services:occupancies|availibilities/occupancies]] as well as [[api:services:prices|prices]] and regularly change on a daily or weekly basis. Moreover, they necessarily need to be up-to-date at each point in time to avoid double bookings or bookings/requests with incorrect prices.
\\
* **Agent information**
All information concerning a user/agent (landlord, agency) will not be available for synchronization. This concerns the name, address, phone number, e-mail address as well as bank account information and other sensitive data. The neccessary information need to be provided to your account manager. Likewise, changes to this information can only be made by your account manager.
\\
----
===== C. Testing =====
Before you synchronize your live properties in our system, you will have the possibility to test your programming using test properties within your regular account. If your account manager has not created a property for you, you can do it yourself in your backend and start testing right away.
If you want to test whether or not you have provided correct pricing information, you can do so using an extra request which returns the final price for a specific date range. It is being developed at the moment.
\\
----