Travanto API Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{ wiki:www.travanto.de.png}}
\\
\\
\\
\\
====== PUSH service / Notifications ======

We would like you to be up to date about bookings or enquiries of all your connected properties. This is why we are able to push a notification to a predefined URL of yours. You will then be able to fetch all relevant information using our [[api:services:bookings|bookings]] or [[api:services:enquiries|enquiries]] service.

  * For a directly bookable property we are able to send notifications for a new booking, a modification, a closed booking (payment has been received) or a cancellation.
  * For properties that run in enquiry mode we can send notifications when a new enquiry has been made.
  * Authorization to subsequently fetch booking or enquiry information can be done in two different ways:
    * For each notification we will provide you with a token that authorizes you to fetch bookings or enquiries related to this specific property. You will be able to fetch all bookings or enquiries for this property, so please keep and reuse this token if you for example want to collect data for previous bookings/enquiries, too.
    * If you have an existing API key or would like to have and use a new one for authorization, you will be able to do so. API keys are user-related, you will need one unique key per user.

<WRAP center round tip 100%>
**Before you are going to develop, please follow the next steps:**

  - Please provide us with an URL we can send the notification to. Each unique notification will be send every five minutes up to three times in case we do not register the retrieval of the related information over our services.
  - Please also provide us with an e-mail address we can send these information to in case your URL cannot be reached or you are unable to fetch booking information within 30 minutes after notification.
  - In order to map bookings and enquiries to the correct accommodation, you will have to have a mapping table which translates our object_id to yours. In some cases the mapping might already be included within the notifications. Please contact your account manager for further information.
</WRAP>


\\
----

===== Structure of the URL & Parameters=====

The structure of the URL and the used parameters might look as follows:

^Booking type ^ Example structure of the URL ^
|Instant Booking | https://propertymanagementsystem.com/push?event=new&booking_id=123456&object_id=987654 |
|Enquiry | https://propertymanagementsystem.com/push?event=new&enquiry_id=123456&object_id=987654 |

We append these parameters to the URL automatically. Parameters that are included in the URL you provided us with will be kept, unless they have the same name as one of our parameters, in which case their value will be overwritten.

\\
----
===== Possible events and parameters =====

^ Event ^ Property mode ^ Parameters      ^ Description          ^
| Booking  | Instantly bookable  |?event=new&booking_id=123456&object_id=987654 | Sent when a binding booking has been made.  |
| Modification | Instantly bookable |?event=update&booking_id=123456&object_id=987654 | Sent when booking information has been changed. You can retrieve the new booking information using the [[api:services:bookings|bookings service]]. Please note that you have to identify the diff at your end or simply overwrite information.  |
| Closure | Instantly bookable |?event=done&booking_id=123456&object_id=987654 | Sent when payment for the booking has been received and booking has been closed  |
| Cancellation | Instantly bookable |?event=cancel&booking_id=123456&object_id=987654 | Sent when a booking has been cancelled |
| Inquiry | Inquiry mode |?event=new&enquiry_id=223344&object_id=555444 | Sent when a new inquiry has been made. This is the only event for properties in inquiry mode  |
\\
----
===== Scheme =====

The //Push service notification scheme// for the push service provides you with a sound idea of how the notifications are being structured.

[schemata https://connect.travanto.de/schemata/push/notification.json]
\\
----

===== Example Push Notification - New booking=====

The example represents a notification for a new booking that has been made. In case this booking will be changed, closed or cancelled, a new notification will be generated, where the body content will be different for event.type and the stamps.

Included in the example is a token key granting access to the all the bookings of the entire property. If you use an API key, the token section will be omitted. The key can be used by sending it as an "X-Token" HTTP-Header in your requests to the [[api:services:bookings|bookings]] or [[api:services:enquiries|enquiries]] services.

==== Header ====

=== HTTP ===
<code http>
POST /push?event=new&booking_id=6563&object_id=1001539 HTTP/1.1
Host: propertymanagementsystem.com
User-Agent: connect.travanto.de
Accept: */*
Referer: https://connect.travanto.de/service/push/
Content-Type: application/json; charset=utf-8
Content-Length: 494
</code>

=== E-Mail ===
<code>
To: your_email@domain.tld
Subject: Travanto Push Notification
From: noreply@travanto.de
MIME-Version: 1.0
Content-type: text/json; charset=us-ascii
Content-Transfer-Encoding: 7bit
Message-Id: <20170314124801.ABC123D4@vermieter.travanto.de>
Date: Tue, 14 Mar 2017 13:48:01 +0100 (CET)
</code>

==== Body ====

[json indentation=2]
{
    "notification": {
        "stamp": "2017-03-14T13:48:01+01:00",
        "event": {
            "type": "new",
            "stamp": "2017-03-14T13:37:34+01:00"
        },
        "entity": {
            "type": "booking",
            "id": 6563,
            "url": "https:\/\/connect.travanto.de\/service\/bookings\/6563\/",
            "object_id": 1001539,
            "user_id": 1000543
        },
        "mapping": {
            "object_id": "your_ID_123456",
            "user_id": "your_user_ID_987654"
        },
        "token": {
            "access": "object",
            "key": "M8hiM0EY0FKM5SMExv4Ey0weBOLe8v5e2BTF48okgB3FA6p46o"
        },
        "json_schema": "http:\/\/connect.travanto.de\/schemata\/push\/notification.json"
    }
}
[/json]

----
\\