Characteristics
Sending salary documents includes the following main characteristics:
User will be managed from the partner
Documents must be sent to specific user only
Documents will be imported as files
The sent data is personal data. As hotelkit does not need the information itself, it is to be made sure, that the documents are encrypted before imported to hotelkit.
Functionality
push user
As the user data is managed within the partner system and it must be ensured that the user is available in hotelkit, the partner will be granted the functionality push_userto suggest new user in hotelkit.
list user
The partner needs to know the available user from hotelkit to send them their information.
message_import
This is the functionality to import the documents. For each recipient an individual message will be created to make sure documents are only available for the intended persons.
Request Types
It is suggested to create an individual request type for every type of document, the partner wants to import. This way the customer is enabled to set custom settings within hotelkit for each document type.
The structure of each request type could be this:
attachements
title
sendRecipients
sendCreater
{
"type":"salary",
"labelForCustomer":{
"de_DE":"Lohndokument",
"en_US":"Salary document"
},
"content":false,
"referenceID":false,
"attachements":true,
"enabledByDefault":false,
"title":true,
"text":false,
"link":false,
"sendRecipients":true,
"hasActions":false
}
Enable Request
Before sending requests to a client, the requestType must be enabled for the respective client.
PUT /setup/customer
{
"enabledRequests":["salary"]
}
User Syncronization
Setup
As the identifer of a user from the partner (clientID) can also be inserted by the customer, the partner must be able to limit the format of valid identifier. This will be done with a regular expression:
PUT /setup/partner
{
"userSync":{
"regEx":"^(\d{3}_\d*)(,\d{3}_\d*)*$",
"examples":[
"123_00025","123_12345,045_58975"
],
"errorMessage":{
"de_DE":"Personalnummern müssen dem Format XXX_XXXXX entsprechen",
"en_US":"personnel numbers must be given in the format XXX_XXXXX"
}
}
}
Daily Routine
Before updating & making suggestions for users in hotelkit, clearly a partner has to load the available users from hotelkit. If the customer is new, the partner should check whether there is another customer-key that is better suited for getting all information about the users.
This step is optional as a warning will be returned in the listing if there is a more suitable customer-key available.
GET /setup/customer
> 200
{
"customerForUserGET":"demo1"
}
After that the partner requests the available user for the customer:
Header x-hotelkit-customer-key: demo1
GET /users
> 200
[
{ //complete data set + vowels in name
"ID": "16",
"clientID": "123_01425",
"givenName": "Hans Peter",
"surName": "Müller",
"loginName": "u12345",
"birthDate": "24.12.2019",
"email": "user@example.com",
"customerList": ["demo1","demo2"]
},
{ //only required information + vowels in name
"givenName":"Hans Peter",
"surName":"M\00DCller",
"customerList":["demo1"]
}
]
Now the partner should match the available user with their user. First priority should be on the given clientID.
As there is no clientID given for user 16, the partner should update this user. Either the user can be matched – the user then will be sent at resolved, or the matching is unclear, and the user is listed as unresolved: The clientID will be validated against the inserted regular expression before set to the user.
PUT /users/16
{
"ID": "16"
"clientID":"123_258"
.... //more fields
}
Request Import
POST https://api.hotelkit.net/requests?type=salary
{
"title":"June 2022",
"recipientList":[
"16" //user.ID
],
"attachements":[
{
"fileName":"test.txt",
"mimeType":"text/plain",
"base64":"TW9pbiBNb2luIQ=="
}
]
}