5. char pmslink KEYCARD API
15/11/2021.
Added NCARDS parameters in calls to direct function of key creation.
10/05/2021.
New version of specification’s document.
Description
For the recording of key cards for guest access to rooms and other hotel locations, directly done from the PMS user interface:
- Makes the work easier at the reception desk and reduces the processing time.
- It reduces the waiting time of the guest when the recording of the key card is necessary.
The key card access systems already have their own connection interfaces and APIs, so the PMS systems can directly carry out this integration, assuming the development, maintenance, and the solution to the different casuistic and difficulties that may arise:
- The key card access system servers are local to the hotel and the access to them can be complex for the PMS, due to their architecture or limitations and restrictions in the hotel’s own systems, e.g. CLOUD PMS
- In cases where it is necessary or simply desirable to use third party encoders that may involve additional development for the PMS, e.g., card dispensers that perform encoding and printing on the key cards.
- In cases where a hotel has several different access systems and/or providers.
- New versions of the API of the access system, due to evolution or new functionalities, that requires additional development work for the PMS. For example, digital key management for mobile devices.
- The PMS is in the obligation to create new interfaces for new access systems that may appear on the market. Certification, initial development, and maintenance.
- As the PMS is one of the main elements, it is understood that it assumes responsibility for integration, which implies being the first element of technical support in the event of incidents.
char pmslink keycard facilitates the integration between the hotel PMS and the keycard access system, making it transparent for the PMS, and therefore assuming these situations and casuistic.
Cases:
Cases where pmslink keycard provides specific solutions:
- CLOUD PMS that does NOT have its own UI for key card recording.
- CLOUD PMS with its own UI for key card recording but must link with the Hotel local server for the key access system.
- PMS with its own UI for key card recording and its own or third-party API and must integrate with a new access system through a new specific API.
- PMS with its own UI for key card recording, integrated with the access system and which also requires the management of digital keys on mobile devices.
1. CLOUD PMS that does NOT have its own UI for keycard recording
Through the API: pmslink keycard interface integrated in PMS UI.
- The PMS will be able to display user’s UI for key card recording through the link with pmslink keycard.
- This UI will have a common design and ergonomics in all cases, only providing, if necessary, particular options to the access system involved.
- pmslink keycard, based on the presented UI, will carry out the processes against the server of the access system, recorders, additional, etc., that are necessary in each case in an autonomous and transparent way for the PMS.
2. CLOUD PMS with its own UI for key card recording but must link to the Hotel local server for the key access system.
Through the API: Direct request to pmslink keycard endpoint for keycard recording.
- The PMS will launch an http request to the key card recording endpoint with the necessary parameters for pmslink keycard to carry out the process against the access system server, additional recorders, and other elements involved and that are necessary in each case, autonomously and transparently for the PMS, returning the result synchronously to each request.
3. PMS with its own UI for key card recording and its own or third-party API and must integrate with a new access system through a new specific API.
Through the API: Link with pmslink keycard middleware interface
- pmslink keycard will adapt to the available API in the PMS, acting as an intelligent middleware, linking with the elements of the access system involved that are necessary in a transparent way for the PMS.
4. PMS with its own UI for key card recording, with integration with the access system and which also requires the management of digital keys on mobile devices.
Through the API: Direct requirement to endpoint pmslink keycard for keycard recording.
- Additionally, the key card recording requirement may include this possibility, so that it can be carried out the necessary processes for the creation of the digital key on the guest’s mobile terminal, in cases where the access system offers this possibility.
API Keycard
pmslink keycard interface integrated in PMS UI
The PMS user is provided with an integrated web interface as an iFrame of the PMS with all necessary controls and elements for the recording of cards for the booking / guest involved.
For the activation of this functionality pmslink keycard will record the process via a specific function implemented by the PMS. This will involve:
- That the PMS will activate button/menu option or any other type of control, in the necessary windows at its discretion based on the registered function.
- That the PMS will call the pre-registered URL that will show the appropriate user UI for card recording and according to the parameters included in the call.
Registration / activation
pmslink keycard > PMS
At the moment of the activation the service, pmslink keycard will register and activate the service in the PMS through a request to a specific endpoint developed by the PMS for this purpose.
Basically, the registration will consist of a request addressed to a specific hotel in which the following will be indicated:
- Identifier of the function to be registered, agreed with the PMS. In this case it would be of the type ‘keycard’. Based on this function, the PMS will activate the necessary controls, in the places it deems appropriate, for the user to access the card recording UI. The text to be presented in the controls will be determined by the PMS in each case and language.
- URL to be launched by the PMS when the user accesses the control associated with the registered function. This URL shall be unique for each installation.
The PMS must implement the logging function, and since it is part of its API, it can be done:
- Under its own specifications and requirements according to its API.
- According to the standard pmslink keycard specifications.
Registration function under PMS specifications:
pmslink keycard will develop the logging function according to the specifications provided by the PMS: Type of Link, data format, authentication, responses, etc.
The PMS in this function must facilitate the reception of the necessary data:
- Mode of identifying the hotel to which the registration is addressed. This can be done by specific url, as a parameter, as data in the content of the request, etc.
- Identifier of the function to be registered.
- URL to be displayed in the iFrame associated to the function.
Standard pmslink keycard logging function:
Based on HTTP request:
| Method | POST |
| Authentication | Basic, based on username and password provided by the PMS. |
| Data | JSON |
| Action | Registration action identifier: “register”. |
| Function | Id of function associated to the card recording provided by the PMS. |
| Chain | Id of the chain to which the hotel is associated, provided by the PMS. NULL if it is not required. |
| Property | Id of the hotel for which the registration is made, provided by the PMS. |
| url | URL to be displayed in the iFrame associated to the function. |
Example
{
"action": "register",
"function": "keycard-tab",
"chain": "CHI",
"property": "HDI",
"URL": https://char-pmslink/keycard/chi/hdi
}Response
| HTTP Code | 200 for all responses related to the received data |
| Data | JSON |
| Code | Code associated with the response: 0 = Ok. 1 = Error: Functionality not activated. 2 = Error: Invalid string or invalid hotel. 3 = Error: Function already registered. 4 = Error: Function not supported. 5 = Error: Invalid URLOther = Errors defined by the PMS |
| Description | Description associated with the result as an extension of the code sent |
Example
{
"code": 0,
"description": "successful"
}Call to the URL associated with the function
PMS > pmslink keycard
The call to the previously registered URL will contain the necessary parameters to customize the keycard recording UI and related processes.
Two formats are considered:
SIMPLE:
The PMS sends as parameters the basic data for key creation:
| room | Room for which key cards are needed to be created. |
| arrival | Arrival Date-Time of occupants in format YYYYMMDDTHHMMSS |
| departure | Departure Date-Time of occupants in format YYYYMMDDTHHMMSS |
| pax | (OPTIONAL) number of occupants of the room for which the card will be created. |
| lang | (OPTIONAL) ISO CODE of the language in which the card recording interface is to be displayed. If this is not indicated, the language of the navigator used will be assigned. |
This formula eliminates the need for an additional reservation query to the PMS for key recording, reducing the processing time. Example (https://char-pmslink/keycard/chi/hdi?room=123&arrival=20200212T150000&departure=20200215T120000&pax=2&lan=en).
STANDARD:
The PMS sends as parameters:
| Booking | Booking ID on which the key card recording is performed. The PMS must have a specific method for pmslink keycard to consult its data |
| Lang | (OPTIONAL) ISO CODE of the language in which the card recording interface is to be displayed. If this is not indicated, the language of the navigator used will be assigned. |
This formula involves additional query/s to the PMS to get the necessary data for the key card recording, this may increase the processing time very slightly, but it simplifies the call by the PMS and allows more functionality (e.g., displaying the occupants in the recording UI). Example (https://char-pmslink/keycard/chi/hdi?chain=UHB&property=HPA&booking=1234567890&ncards=2&lan=en).
Deactivation
pmslink keycard > PMS
Allows to deactivate the key card recording function and thus the registration of the associated function.
This can be done as a definitive deactivation of the service or to modify a previous registration (in the sequence (deactivate – register).
The PMS shall develop and provide the endpoint for this function.
Basically, the deactivation will consist of a request addressed to a specific hotel in which it will be indicated:
- Identifiers of the function to be deactivated previously registered. The PMS will deactivate / hide the associated controls.
The PMS must implement the deactivation function, and since it is part of its API, it can be done:
- Under its own specifications and requirements according to its API.
- According to the standard pmslink keycard specifications.
Deactivation function according to PMS specifications:
pmslink keycard will develop the logging function according to the specifications provided by the PMS: Type of Link, data format, authentication, responses, etc.
The PMS in this function must facilitate the reception of the necessary data:
- Way to identify the hotel to which the record is directed. This can be done through a specific url, as a parameter, as data in the content of the request, etc.
- Identifier of the function to be deactivated.
pmslink keycard > PMS
Based on HTTP request:
| Method | POST |
| Authentication | Basic, based on username and password provided by the PMS |
| Data | JSON |
| Action | Registration action identifier: “unregister”. |
| Function | Id of function associated to the card recording provided by the PMS. |
| Chain | Id of the chain to which the hotel is associated, provided by the PMS. NULL if it is not required. |
| Property | Id of the hotel for which the registration is made, provided by the PMS. |
Example
{
"action": "unregister",
"function": "keycard-tab",
"chain": "CHI",
"property": "HDI",
}Response
| HTTP Code | 200 for all responses related to the received data |
| Data | JSON |
| Code | Code associated with the response: 0 = Ok. 1 = Error: Functionality not activated. 2 = Error: Invalid chain or invalid hotel. 3 = Error: Function not registered. Other = Errors defined by the PMS |
| Description | Description associated with the result as an extension of the code sent |
Example
{
"code": 0,
"description": "successful"
}Direct request to pmslink keycard endpoint for card recording
This working mode would be assumed by a PMS that has a specific UI for card recording and requires pmslink keycard to:
- Record of key cards from unsupported providers or unsupported interfaces, adopting the standard pmslink keycard API and unify communication with the different providers.
- Activate keys on the guest mobile devices in cases where the necessary elements are available.
- Record of key cards and/or print data on them using a third-party encoder.
The PMS displays its own UI for key recording, with the necessary data for it, and performs recording request of each key to function defined in pmslink keycard for this purpose:
Based on HTTP request to endpoint provided by pmslink keycard:
| Method | POST |
| Authentication | Basic, based on username and password provided by the PMS. |
| Data | JSON |
| action | Recording action identifier: “createkey” |
| chain | Id of the chain to which the hotel is associated, provided by the PMS. NULL if not required. |
| property | Hotel ID on which the registration is made, provided by the PMS. |
| room | Room on which the key cards will be recorded |
| extra_access | Array of identifiers of additional rooms to which access will be allowed. |
| arrival | Date – Time of occupant’s check-in in YYYYYMMDDTHHMMSS format |
| departure | Date – Time of occupant departure in format YYYYYYMMDDDTHHMMSS |
| ncards | (OPTIONAL) Number of cards to be recorded in the petition. By default 1. |
| name | (OPTIONAL) Identifier of the key created for information recording purposes |
| encoder | (OPTIONAL) Id of the physical encoder to be used for key card recording according to identifiers provided by pmslink keycard. NULL will be used as the default recorder. |
| key_type | (OPTIONAL) Type of key:”K” = Card”M” = Digital key for mobile terminal access.NULL is assumed as card.This possibility is subject to specific elements not available for all access system providers and may require additional functions |
| maincard | (OPTIONAL) Indicates whether it is a new or a duplicate card. true: new card false: duplicate card If the data is not sent, it applies the internal logic to identify whether it is a new or a duplicate card. |
Example
{
"action": "createkey",
"chain": "CHI",
"property": "HDI",
"room": "125",
"extra_access": ["gym","parking"],
"arrival": "20200213T150000",
"departure": "20200215T120000",
"ncards": 2,
"name": "John Doe",
"encoder": "ENC1",
"maincard": true
}Response
| HTTP Code | 200 for all responses related to the received data |
| Data | JSON |
| Code | Code associated with the response: 0 = Ok. 1 = Error: Functionality not activated. 2 = Error: Invalid chain or hotel. 3 = Error: Unknown room. 4 = Error: Error in arrival or departure dates. 5 = Error: Unknown encoder. 6 = Error: Key type not supported. 7 = Error: Error in recording. Description contains details of the error. Others = Errors defined by pmslink keycard and detailed in its description. |
| Description | Description associated with the result as an extension of the code sent |
Example
{
"code": 0,
"description": "successful"
}Link with pmslink keycard middleware interface.
pmslink keycard emulates interfaces of different access systems.
This allows the PMS to be linked transparently to these interfaces already implemented without having to assume development work in the case of:
- Integration with new access systems.
- New functionalities and versions of access systems already integrated by the PMS but not compatible with the interfaces already developed.
In these cases, pmslink keycard acts as an intelligent middleware, converting links, protocols, formats and whatever else is necessary for the conversion.