1 Business Context

OPERA Cloud provides an API operation POST RoomKeysExternal that manages requests for guest room keys from external systems.

This operation allows external systems, such as but not limited to Check-In Terminals or applications supporting mobile room keys, to send a request to create room keys or mobile room keys through the API to OHIP, which forwards it to OPERA Cloud. From there, the request is transmitted to a connected Door Lock System using the OPERA Outbound Systems Door Lock API (postRoomKeysOutbound).

The postRoomKeysExternal API operation supports all possible room key requests to be executed by the connected Door Lock system (DLS). Different types of key actions (such as New Key, Duplicate Key, and Delete Key requests) and Modify and Room move requests (for online key systems) are available for requesting physical room keys as well as mobile/digital keys or Pin codes.

This implementation guide provides guidance and explains the workflows for the typical handling of guest room keys requested by external systems connected with OHIP.

This guide covers the following use cases for mobile room key requests and also use cases for plastic key or Pin code requests from an external system.

Table 1-1 Business Use Cases

	Use Case	Description
1	Request from an external system to create/activate a Mobile Key for an existing guest room reservation.	An external system sends a request for a mobile key to OHIP/OPERA Cloud PMS at the time of reservation check-in or at any time prior to or after guest check-in. This can be a request for the first mobile room key to become active.
2	Request from an external system to delete/remove active room key(s).	An external system sends a request to delete all active room keys or Pin Codes for a reservation at the time of a check-out of the hotel guest through the external system or at any time during the guest stay (initiated by the user of the external system). A request to delete specific room keys is not available.
3	Request from an external system to encode a physical room key (plastic key or wristband) or create a Pin Code for an existing guest room reservation.	An external system sends a request for creating/activating a physical room key (for example, a plastic card or wristband) or a Pin Code to OHIP/OPERA Cloud PMS at the time of reservation check-in or at any time prior or after guest check-in.
4	Request from an external system to encode additional physical room key(s) (plastic key or wristband) or create a Pin Code for an existing guest room reservation.	An external system sends a request for creating/activating an additional physical room key (for example, a plastic card or wristband) or another Pin Code to OHIP/OPERA Cloud PMS at the time of reservation check-in or at any time prior or after guest check-in.

Table 1-2 Workflow Diagram: Guest Journey Mobile Room Key

Journey: Guest arrival Hotel guest receives notification from Hotel that his reservation is ready for Check-In and that guest can request his mobile key now. Guest requests the mobile key via external system (e.g. Hotel Mobile App or Website). The external system sends the request to OHIP using the postRoomKeysExternal API operation. OHIP passes the request to OPERA Cloud. OPERA Cloud then sends out a request for a mobile key to the connected Door Lock system using the Outbound API postRoomKeysOutbound. The Door Lock system processes the request and sends back related response (request successful or not) to OPERA Cloud including the necessary mobile key data. OPERA Cloud passes back the mobile key request response data to OHIP which sends it back to the external System. In case of successful response from the Door Lock system the external system sends the mobile key information to the guest facing app or website. With check in of the reservation in OPERA Cloud the guest is now able to use the mobile key to open the guest room. Journey: Guest departure Check-Out via Guest app: When the hotel guest checks out from the hotel via his app, the external system has the option to send out a check out request and a Remove Room Key request to OPERA Cloud. The external system sends the request to OHIP using the postRoomKeysExternal API operation. OHIP passes the request to OPERA Cloud. OPERA Cloud then sends a Remove Key request to the connected Door Lock System using the Outbound API postRoomKeysOutbound. The Door Lock system will delete all active room keys for this room/reservation and responds back to OPERA Cloud. OPERA Cloud passes the response back to the external system which will then remove the mobile key from the guest app. Guest is no longer able to open his guest room. Check-Out at Hotel Front desk: When the guest checks out at the Hotel Front desk OPERA Cloud will send a Remove Key request to the connected Door Lock System. The Door Lock system will delete all active room keys for this room/reservation and responds back to OPERA Cloud. In this scenario OPERA Cloud will not send a remove key request to the external system by default. The external system needs to handle the removal of the mobile key based on the received mobile key validity or subscribe to receive Check-Out Business Event via OHIP.