9 FAQ

Q. What is the maximum time for an external system to wait for response on a POSTroomKeysExternal request message?

  • It is suggested to set a solid timeout on the external system that sends the request for activating a room key, a mobile key, or a pin code.

    For the connected Door Lock system, the maximum time to respond to a POST roomKeysOutbound request message from OPERA Cloud is 20 seconds. This is related to the maximum allowed call timeout within the OPERA Cloud Outbound service.

    A recommended timeout to wait for the response from OPERA Cloud/OHIP is 30 seconds before cancelling the request internally and displaying an unsuccessful request to the user.

Q. The external system wants to have 3 room keys encoded/activated for the reservation. Will there be one API call sent with numberOfKeys = "3" ?

  • The post RoomKeysExternal API call mandates to send out one API request call per room key to encode/activate. The related "numberOfKeys" value must always be "1."

Q. If the encoding/activation of a room key fails on the Door Lock System side, will the response be a common HTTP client error response (4xx)?

  • If the Request for a room key is unsuccessful on the Door Lock System side, the related response to the External system is sent as a "400" response message.

    Within the body of this message a responseText is sent describing the reason for failure. The external system should display this response text to the user.

Q. Is it possible to send multiple roomKeysExternal requests with different key EncoderIds to the Door Lock system at the same time?

  • Yes, it is expected that simultaneous roomKeysExternal requests with different key EncoderIds can be handled by the external system and by the connected Door Lock System.

Q. Does the Door Lock API include sending Guest or Reservation details, such as Guest Names?

  • The Door Lock API roomKeysExternal only includes the necessary information needed to create a room key. It contains the reservationId but no further guest or reservation information/details.

    To retrieve such additional information beside the room key information exchanged with this API, the external system can consume related guest profile or reservation APIs.

Q. What are the keyTrack sub tags used for?

  • keyTrack1: The keyTrack1 tag can be used for a specific data string to be sent from OPERA Cloud to the connected Door Lock System in case OPERA Cloud and the connected Door Lock System support the requested data. This could be room or guest specific information which the Door Lock System requests.

    Note that OPERA Cloud does not store incoming keyTrack1 data but only passes the data through to external systems.

  • keyTrack2:

    The keyTrack / keyTrack2 tag contains a unique ID that can either be:
    • created by OPERA Cloud and sent with the roomKeysOutbound request (as to let the door lock system store it on the key device) OR
    • sent by the door lock system in the related response message

    It was common that the keyTrack2 was sent by OPERA Cloud in the request so it was written onto the Mag stripe of the door key card. Today it is more common that the Door Lock System sends the UDID of a key in the response message.

    In both cases, the keyTrack2 value will be stored in OPERA Cloud and is linked to the reservation so a guest can be identified by reading the door key “track2” value on another system and send an inquiry to the PMS. This is usually used by Restaurant POS Systems.

  • keyTrack3: The keyTrack3 tag contains the unique pin code provided by the Door Lock System that uses number pads on the guest room lock to enter a pin to open the door. The pin code is stored in OPERA Cloud to enable the user to display and print the pin code and hand it out to the guest.

    To enable Pin code handling in OPERA Cloud, the related configuration parameter must be set in OPERA Cloud Interface configuration.