Table of Contents
Occupancies / Availabilities
Keeping availabilities and occupied periods up to date is one of the most crucial aspects for every property in order to avoid double bookings and provide correct information to your guest. Information should therefore be as current as possible and sent right at the time of change. We have collected several hints and tips for you to develop this part hassle-free. We also provide the basic request scheme and the four request methods together with the corresponding responses.
The general URL of this service is https://connect.travanto.de/service/occupancies. Use GET, POST, PUT and DELETE methods to show, create, change or delete one or more occupied periods.
Schemes
The basic request and response schemes for the occupancy service provide you with a sound idea of how to use it.
We are running an occupancy service already using XML and will continue to do so for some while. If you, however, already use this service and send occupancy information into our system, you now have the possibility to send single occupancies instead of always sending all occupancies for an entire object! All you have to do is adapt your programming to the new JSON scheme and use the methods accordingly. Your API does have the same rights in the new environment.
Creating occupancies
| Method | URL | Description |
|---|---|---|
| POST | /service/occupancies/?object_id=$object_id | Create one or more occupancies for a specific property |
Example request:
{
"occupancies": [
{
"object_id": 1010397,
"date_from": "2018-02-01",
"date_to": "2018-02-10",
"guest_name": "Tim Hochmuth",
"guest_amount": 3,
"comment": "Early arrival"
},
{
"object_id": 1010397,
"date_from": "2018-03-01",
"date_to": "2018-03-10",
"guest_name": "Another guest",
"guest_amount": 4,
"comment": "Dog"
}
]
}
Example response:
{
"OK": 1,
"Request": {
"Method": "POST",
"Path": "/service/occupancies/"
},
"OccupanciesServiceResult": [
{
"occupancy_id": 1643064492,
"object_id": 1010397,
"date_from": "2018-02-01",
"date_to": "2018-02-10",
"guest_name": "Tim Hochmuth",
"guest_amount": 3,
"comment": "Early arrival"
},
{
"occupancy_id": 1643064493,
"object_id": 1010397,
"date_from": "2018-03-01",
"date_to": "2018-03-10",
"guest_name": "Another guest",
"guest_amount": 4,
"comment": "Dog"
}
]
}
TIPS
- Creating new occupanncies does not require an “occupancy_id” as it is being created internally and returned to you within the response. Please use this ID for all further actions concernings this booking, e.g. show, update, delete.
- Sending new occupied periods as quickly as possible is highly important. Please try to send new occupancies as they are being made or as quickly as possible afterwards.
- Even though you define the property ID in the URL you still have to send the ID for every period.
Showing occupancies
Use this service to show current occupancies for an entire property or only one specific occupancy and to check correctness of previously transfered periods.
| Method | URL | Description |
|---|---|---|
| GET | /service/occupancies/$occupancy_id | Show one specific occupancy |
| GET | /service/occupancies/?object_id=$object_id | Show all occupancies for a specific property |
| GET | /service/occupancies/?object_id=$object_id&date_past=1 | Show all occupancies for a specific property including the ones in the past |
| GET | /service/occupancies/?object_id=$object_id&bookings=1 | Show all occupancies for a specific property including bookings made by Travanto |
| GET | /service/occupancies/?object_id=$object_id&date_min=$date&date_max=$date | Show all occupancies later than or before a specific date or within a date range |
Example response:
{
"OK": 1,
"Request": {
"Method": "GET",
"Path": "/service/occupancies/",
"Query": "object_id=1010397&bookings=1"
},
"OccupanciesServiceResult": [
{
"occupancy_id": 1512183152,
"object_id": 1010397,
"date_from": "2016-08-16",
"date_to": "2016-08-21",
"guest_name": "fdfd",
"guest_amount": 0,
"comment": ""
},
{
"object_id": 1010397,
"date_from": "2016-08-06",
"date_to": "2016-08-13",
"guest_name": "",
"guest_amount": 2,
"comment": "",
"booking_type": "online_booking",
"booking_id": 46619
},
{
"object_id": 1010397,
"date_from": "2016-10-01",
"date_to": "2016-10-08",
"guest_name": "",
"guest_amount": 2,
"comment": "",
"booking_type": "online_booking",
"booking_id": 46627
}
]
}
TIPS
- If you also want to include bookings having been made by Travanto add parameter &bookings=1 to your request. You will also be shown the booking ID and the booking type.
- Responses only contain occupied periods of which at least one night is in the future. Add parameter &date_past=1 for past periods.
Updating occupancies
| Method | URL | Description |
|---|---|---|
| PUT | /service/occupancies/$occupancy_id | Change one specific occupancy |
| PUT | /service/occupancies/ | Change one or more occupancies for one or more properties |
Example request (related to the occupancies created above):
{
"occupancies": [
{
"occupancy_id": 1643064492,
"object_id": 1010397,
"date_from": "2018-02-01",
"date_to": "2018-02-12",
"guest_name": "Tim Hochmuth",
"guest_amount": 3,
"comment": "Early arrival"
},
{
"occupancy_id": 1643064493,
"object_id": 1010397,
"date_from": "2018-03-01",
"date_to": "2018-03-10",
"guest_name": "Another guest",
"guest_amount": 5,
"comment": "Dog"
}
]
}
Example response:
{
"OK": 1,
"Request": {
"Method": "PUT",
"Path": "/service/occupancies/"
},
"OccupanciesServiceResult": [
{
"occupancy_id": 1643064492,
"object_id": 1010397,
"date_from": "2018-02-01",
"date_to": "2018-02-12",
"guest_name": "Tim Hochmuth",
"guest_amount": 3,
"comment": "Early arrival"
},
{
"occupancy_id": 1643064493,
"object_id": 1010397,
"date_from": "2018-03-01",
"date_to": "2018-03-10",
"guest_name": "Another guest",
"guest_amount": 5,
"comment": "Dog"
}
]
}
TIPS:
- Please use this method to update booking information ranging from altering date ranges to changing persons.
- Please make sure to use the correct occupancy_id and to send all informationen even if they haven't changed. Sending no comment in the updating request would for example delete the previous comment.
- Be aware that bookings made through Travanto cannot be manipulated. Change or deletion is not possible. If you need to change a booking, contact our customer support.
Deleting occupancies
| Method | URL | Description |
|---|---|---|
| DELETE | /service/occupancies/$occupancy_id | Delete an occupancy |
| DELETE | /service/occupancies/?object_id=$object_id | Delete all occupancies for an entire property |
Example request:
/service/occupancies/1643064493
Example response:
{
"OK": 1,
"Request": {
"Method": "DELETE",
"Path": "/service/occupancies/1643064493"
},
"OccupanciesServiceResult": [
{
"occupancy_id": 1643064493,
"object_id": 1010397,
"date_from": "2018-03-01",
"date_to": "2018-03-10",
"guest_name": "Another guest",
"guest_amount": 5,
"comment": "Dog"
}
]
}
TIPS
- Please be very careful with deleting occupancies. Chances of double booking will be present.
Error Codes
\\ApiInputException 10239 - if the to min date is specified but not a valid date
\\ApiInputException 10239 - if the to max date is specified but not a valid date
\\ApiInputException 10239 - if the to min date and to max date are specified but max is before min
\\ApiJsonException 10241 - if the HTTP body contains invalid JSON
\\ApiJsonException 10249 - if the JSON data is violating the JSON Schema of this Service
\\ApiInputException 10238 - if there is an occupancy_id in the URL and there are more than one occupancies in the JSON data.
\\ApiJsonException 10249 - if the JSON data does not contain occupancy_id fields
\\ApiInputException 10239 - if there is an occupancy_id in the URL and it does not match the occupancy_id in the JSON data.
\\ApiInputException 10281 - if the JSON data contains the same occupancy_id more than once
\\ApiInputException 10227 - if the to date is not after the from date
\\ApiInputException 10226 - if the to date is in the past
\\OccupanciesServiceException 13021 - if the whole period of time is already covered by another occupancy
\\PermissionException 10152 - if the api key isn't allowed to access the objects for these occupied periods
\\PermissionException 10159 - if the api key isn't allowed to update occupied periods for all objects in the request
\\PermissionException 10159 - if the object_id is changing and the api key isn't allowed to update occupied periods for the former objects
\\PermissionException 10159 - if the object_id is changing and the api key isn't allowed to update occupied periods for the requested objects
\\ApiInputException 10280 - if an occupancy_id doesn't exist
\\ApiMethodException 10056 - if the URL contains an occupancy_id
\\ApiInputException 10291 - a filter must be set for another filter to work
\\ApiException 10701 - if the flood protection time is still active
\\PermissionException 10159 - if the api key isn't allowed to create occupied periods for all objects in the request
\\PermissionException 10159 - if the api key isn't allowed to delete the occupied periods for their objects