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.
Available Functionalities
messageImport
The messageImport allows a partner to create messages in hotelkit. For each request type recipients can be defined & therefore information is sent transparent & efficiently to the respective users. There are several use cases for this, for example:
Replacement of E-Mail
If you are currently sending E-mails to notify hotel employees about certain topics, actions, to-do’s etc. this can now be done with a new notification channel – hotelkit. Further, also attachements (pdf, xml, excel, csv..) can be imported. Therefore, with using this functionality you can replace the email inbox & centralize notifications for the employees.Handling of Tasks
Even whole processes can be sent to hotelkit, as a result, employees can stick to the well-known processes of the partner software, which can be displayed in hotelkit. In combination with has_actions (2.) the partner can send pending actions to the responsible user. The naming & workflow can be defined as used in the partner system. That way the necessary actions can be documented & the status of each task can be tracked & synchronised between the two tools.Import of Personal Data
Information and documents can be sent to specific users without needing a professional email address. For instance, the roster can be sent to the respective person instead of printing it on paper. This is best used in combination with user_list (3.).
Besides shift rosters also other messages like holiday requests, sick notices etc. can be imported. Lastly, even sending a payslip is possible & secure within hotelkit. Keeping in mind the user synchronisation, a payslip will be sent only to the designated person in a private handover, only this person has access to.
hasActions
With that the partner can send pending actions to the customer. Like this, imports are then handled as tasks by the users. For details see section “webhook”. The webhook must be set up for hotelkit being able to send the actions back to the partner.
userList
Whenever the partner needs the list of available users in hotelkit, this functionality is enabled. Only then the partner can send information to specific user or start the push_user functionality.
userPush
The partner is enabled to update user data in hotelkit and suggest new users to a customer. This is enabled whenever the partner manages all employee in his system and needs to make sure those employees are available within hotelkit. Therefore, the partner will be the single point of truth & leading system in employee data. The customer does not need to maintain user data in two systems anymore, which results in less administrative work.
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 current version of the api is 3.0
As the API is in constant development features are added and expected data may change. By sending the api version it is defined what data and structure is expected.
Each endpoint has the made changes documented.1