Characteristics
Sending salary documents includes the following main characteristics:
Documents must be sent to specific user only
Documents will be imported as files
preferred: User will be managed from the partner
The sent data is personal data. As hotelkit does not need the information itself, it has to be ensured, that the documents are encrypted before imported to hotelkit.
Functionality
list user
The partner needs to know the available users 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.
optional: 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 userPush to suggest new user in hotelkit.
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
The routine will be described with the preffered option that the partner manages the users.
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
[
{
"ID": "16",
"clientID": null,
"givenName": "Hans Peter",
"surName": "Müller",
"loginName": "u12345",
"birthDate": "24.12.2019",
"email": "user@example.com",
"customerList": ["demo1","demo2"]
}
]
Now the partner should match the available user with their user. First priority should be on the given clientID.
when the partner manages the users:
As there is no clientID given for user 16, the partner should update this user. Either the user can be matched – the user will be sent via PUT /users/{ID}, or the matching is unclear and no action is taken fromt he partner.
In hotelkit 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
}
If the partner does not manage the users and uses only functionality userList, he can not address unmatched users in hotelkit.
Request Import
When a user could be matched between both systems he can be adressed in the message 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=="
}
]
}