Getting Started
- Gabriel Körner
Activation of Functionalities
At the start of the partnership, use cases for the integration will be defined. According to that the partner profile will be enabled with the necessary functionalities by hotelkit. If a functionality is not enabled for the partner, a 404 Response will be sent. Please reach out to your contact, if this is the case.
Access to Testsystem
In order to develop & test the integration independently, every partner will be granted a test environment. The API will be enabled for this system by default. This system is supposed to be a test customer so the partner can see the integration from start to end.
There will be personal accounts for the involved people & the users can be extended anytime, if necessary.
Webhook of the API
Each request has to be sent to https://api.hotelkit.net. The payload MUST be json according to the corresponding endpoint.
Getting the Private Key
To ensure that requests are indeed sent by the partner, a secret only known to the partner will be used for generating the signature. This secret will be called private key.
The private key will not be changed during the partnership unless it is leaked. It is recommended that the implementation is done in a way, that the private key can be changed for all customers. As soon as a new private key needs to be deployed, the old private key will be invalid.
Setting of Header
To be able to send requests to the API, the partner has to send different headers with the request. Those headers are used to identify the sending partner, the customer and the version of the API.
x-hotelkit-api-customer-key
Will identify the customer that the request is for. As soon as the API is enabled for a customer, the customer-key will be provided.
The header must not be sent in requests that are used for the partner instead of a specific customer.
The customer-key is a string of a length up to 50 UTF8 encoded chars.
x-hotelkit-api-nonce
The nonce is a (pseudo)random string, that will be unique for each request. It will ensure that the signature is different for every request sent to hotelkit. As every nonce must be used only for one request it also prevents replay attacks. If a request is sent with a duplicate nonce header it will get a 403 response.
In the Functionality – Security section is a more detailed description of how to sign the requests correctly.
To ensure that the header only consists of ASCII chars (as defined in RFC822) the header should be base64 encoded.
A simple implementation of the nonce is to concatenate the current timestamp and some random chars. Some examples are listed below:
PHP
/**
* creating random string
* @see http://stackoverflow.com/questions/4356289/php-random-string-generator/31107425#31107425
*/
protected static function getRandomString($length)
{
$string = "";
$keyspace = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'; //pool of possible chars
$max = mb_strlen($keyspace, '8bit') - 1;
for ($i = 0; $i < $length; ++$i) {
$string .= $keyspace[random_int(0, $max)];
}
return $string;
}
$nonce = base64_encode(time().static::getRandomString(15));Ruby on Rails
Ruby on Rails
require 'rack'
Rack::Auth::Digest::Nonce.new.to_s
x-hotelkit-api-public-key
The public-key will be used for identifying the requesting partner and for getting the correct private-key.
It is constant for every request and will not be changed during the partnership.
It will be provided to the partner as soon as the functionality is granted.
x-hotelkit-api-version
The common version of the api is 3.0. Some parts (User Synchronization) are on version 3.1. Please check this seperately in the Swagger-files.
x-hotelkit-api-signature
The signature is a security mechanic based on the previously mentioned headers. How it’s generated will be described in Security.