Key Terminology

RoomKeysExternal Room Key Types	Description
"HardKey"	A plastic key card (RFID or Magstripe), a wristband, or other device used to store room key data.
"MobileKey"	A virtual key or mobile key (not a wallet key as this will have a separate type). The Door Lock System sends back a mobile key string.
"PinCode"	A numeric pin code used to open the room door that has a number pad installed.
"KeyPayload"	Request from an external system to retrieve an image of a previously created room key. This is dependant on the door lock system supporting such requests.

Room Keys Request Types "keyType"	Description
New	A request to create a new key for a reservation. It is expected that all previous active keys for the reservation or room become invalid.
Duplicate	A request to create an additional key for a reservation that already has active keys. It is expected that existing active keys for this reservation or room remain active.
Remove	A request to delete active key(s) for a reservation or room. It is expected that with this request all active keys for the reservation or room become inactive or invalid, so they will be unable to open the room after the defined validityEnd time. There is no support for deleting specific room keys.
ModifyStay	(For Online Door Lock Systems) a request to adjust room key data when a guest changes length of stay (validityEnd) without the need for the guest to go to the reception for re-encoding the room key(s). It depends on the connected Door Lock system if this method of updating active room key data is supported. For details, refer to the "Offline" and "Online" Door Lock System section.
RoomMove	(For Online Door Lock Systems) a request to adjust Room key data when the guest performs a room move without the need for the guest to go to the reception for re-encoding the room key(s). It depends on the connected Door Lock system if this method of updating active keys is supported. For details, refer to the "Offline" and "Online" Door Lock System section.

"Offline" and "Online" Door Lock System
Question	Answer
What is the Offline Door Lock System?	OPERA Cloud considers an "Offline Door Lock System" a system where the information necessary to allow access to a door is stored on the room Key (or similar media) that the related door Lock will read.
What is the Online Door Lock System?	OPERA Cloud considers an "Online Door Lock System" a system where the information necessary to allow access to a door is stored in the System's database despite being stored on the room key (or similar media). Such systems typically have the Door Lock being wired with the Door Lock System's database.
Room Move handling with offline Door Lock System	OPERA Cloud handles Room move requests in different ways depending on whether it is connected to an Offline or Online Door Lock System. When connected to an "Offline Door Lock System," OPERA Cloud sends a "Remove" Key request for the old room number to inactivate current active keys and then sends a Request for "New" (and "Duplicate") keys for the new room number. It is required that the Hotel guest must visit the Front Desk to get the new room key(s).
Room Move handling with Online Door Lock System	When connected to an "Online Door Lock System," OPERA Cloud sends requests with different message types in case relevant data of a reservation changes. For example, upon "Room move" of a reservation (guest moves to another room), OPERA Cloud sends a request with keyType "RoomMove" containing information of the old room and the new room number, so the Door Lock System would only need to change the data in its database. Therefore, the guest does not need to have the room key re-encoded at the Front Desk.
Reservation data change with offline Door Lock System	When connected to an "Offline Door Lock System" and the reservation's check out date changes, OPERA Cloud sends a "Remove" Key request for the reservation or room number to inactivate the current active keys and then sends a Request for "New" (and "Duplicate") keys for the reservation or room number with the updated check out date (here the keyValidityEnd). It is then required that the Hotel guest visits the Front Desk to get the new room key(s).
Reservation data change with Online Door Lock System	When connected to an "Online Door Lock System" and the reservation's checkout date or time changes, OPERA Cloud sends a request message with keyType "ModifyStay" containing the updated checkout date (here the keyValidityEnd). The updated information is stored in the Door Lock System's database.

RoomKeysExternal Body Fields

Description

responseCode

responseText

Each response message for a corresponding request message must have a "responseCode": value. This code indicates if the request has been successfully processed. Specific codes indicate a reason for why a request has failed.

The following "responseCode": values are supported:

"OK" = Successful - sent when the request for the related action was successful on the Door lock system.

"BY" = Encoder Busy - sent when the related Key Encoder of the connected Door lock system was unable to process the request.

"UR" = Unprocessable Request - sent when the Door Lock system is unable to process the request due to incorrect or missing information received in the request.

"RY" = Retry - sent by the Door lock system for an unsuccessful request.

OPERA Cloud treats all response codes other than "OK" as "unsuccessful" and sends related "400" response message back to the external system when receiving these response codes from the connected Door Lock System.

The roomKeysExternal response messages (201 / 400) also supports transmitting a response text from the connected Door Lock System. It is recommended to handle this text and display it to the user (if available).

8 Key Terminology