{{ wiki:www.travanto.de.png}}
\\
\\
\\
\\
====== Bookings ======

It is possible to retrieve all information about bookings that have been made by our system. This ranges from the status of the booking, the travel dates, prices, guest and payment information and many more. 

<WRAP center round tip 100%>
There is two main use cases for this service: 
    * Retrieving information for a new, modified, closed or cancelled booking after a notification has been sent to your system (see [[api:services:push|Push notification service]] for further details)
    * Periodically verify bookings in your system and double checking them with the information we provide.
</WRAP>

The general URL of this service is https://connect.travanto.de/service/bookings. <wrap em>GET</wrap> is the only available method in this case.
\\
----
===== Scheme =====
The basic response scheme for the bookings service provide you with a sound idea of its output.

[schemata https://connect.travanto.de/schemata/response/BookingsService.json]

\\
-----
===== Authorization & Provided data =====
There are two ways to authorize in order to fetch information about bookings.
  - You can use your existing API key enabling you to receive booking information or
  - If you also use the [[api:services:push|Push notification service]] we provide you with a token that can be used to retreive all bookings for the property concerned.

\\
<WRAP center round important 100%>
Whenever you fetch data about bookings using this service, you are being presented the data as it is present in our system. The response to your request will always be of the same structure, only the containing data might have changed. 
In case you want to get data after a modification of a booking, you will get the same response with altered data so that you will have to identify the changed elements yourself.
</WRAP>

\\
----


===== Retrieving Booking information =====
After a booking has been made (or at any other point in time), you are able to retrieve all neccessary information using <wrap em>GET</wrap> method. You can either fetch information about one specific booking, for all bookings for an entire property or all bookings for properties authorized through your API key.

^ Method     ^ URL      ^ Description          ^ Authorization ^
| GET |/​service/​bookings/​ | Get booking information for all bookings ​related to your API key     | API key only |
| GET |/​service/​bookings/?​object_id=$object_id | Get booking information for one entire property ​   ​| API key & Token | 
| GET |/​service/​bookings/​$booking_id | Get booking information for one specific booking ​   ​| API Key & Token |

----
\\
===== Examples response =====
The following example will give you an idea about the possible responses you can expect using this service. Since responses do only differ in "state", the different responses are not being dealt with separately. The structure of the responses is always the same. 

<WRAP center round tip 100%>
  * Please be aware of the fact that we do not provide comprehensive guest information until payment has been received and the booking has been closed.
  * If the landlord is using our extra package "Reichweite+", which enables him to be present on 40+ different vacation rental platforms, all basic prices are subject to a surcharge. This includes all rental prices as well as additional services. If a booking has been made including a surcharge, the response will contain both prices, the basic and the surcharged ones.
  * We are currently not providing the exact canellation fees in case a booking has been cancelled. This feature will be developed in the future.
</WRAP>
\\

[json]
{
  "OK": 1,
  "Request": {
    "Method": "GET",
    "Path": "/service/bookings/221486"
  },
  "BookingsServiceResult": [
    {
      "booking_id": 221486,
      "object_id": 1014407,
      "stamp": "2017-05-22T20:24:32+02:00",
      "state": "open",
      "source": "travanto.de",
      "stay": {
        "arrival": "2017-08-05",
        "departure": "2017-08-11",
        "nights": 6,
        "persons": 4,
        "children": 0,
        "services": [
          {
            "type": "final cleaning",
            "amount": 1
          },
          {
            "type": "laundry package",
            "amount": 4,
            "frequency": "per person"
          }
        ]
      },
      "guest": {
        "language": "DE",
        "salutation": "male",
        "first_name": "Tim",
        "last_name": "Hochmuth",
        "street": "Holzbrücke 7",
        "zip": "20459",
        "city": "Hamburg",
        "country": "Deutschland",
        "phone": "0157 1234567",
        "email": "t.hochmuth@travanto.de"
      },
      "prices": {
        "normal": {
          "per_night": 107,
          "rental": 642,
          "services": {
            "final cleaning": 64,
            "laundry package": 64
          },
          "total": 770
        },
        "surcharged": {
          "per_night": 125,
          "rental": 750,
          "services": {
            "final cleaning": 75,
            "laundry package": 76
          },
          "total": 901
        },
        "surcharge": 131,
        "final_payment": 630.7,
        "final_payment_due": "2017-07-22",
        "pre_payment": 270.3,
        "pre_payment_due": "2017-06-01"
      }
    }
  ]
}
[/json]

----
\\