| |
Description
|
Sample Call
|
| 1 |
An External system (for example, a Kiosk check-in terminal) sends a request for a
"MobileKey" to OHIP using the POST roomKeysExternal operation. |
MobileRoomKeyRequest
POST {{HostName}}/fof/v1/hotels/{{HotelId}}/roomKeysExternal
{
"keyType": "New",
"encoderTerminal": "",
"encoderId": "",
"roomKeyType": "MobileKey",
"keyUserType": "Guest",
"keyRequestTime": "2024-02-26T16:16:10.295Z",
"roomId": "101",
"oldRoomId": "",
"noOfKeys": "1",
"reservationIdList": [
{
"id": "{{ReservationId}}",
"type": "Reservation"
},
{
"id": "2468024",
"type": "Confirmation"
}
],
"guestShareFlag": "N",
"keyValidityStart": "2024-02-26T11:16:16.000Z",
"keyValidityEnd": "2024-02-27T12:00:00.000Z",
"additionalRooms": [
"",
""
],
"userId": "ExternalUser",
"keyOptions": [
{
"keyOptionsCode": "SAU",
"keyOptionDescription": "Sauna"
},
{
"keyOptionsCode": "ELEV",
"keyOptionDescription": "Elevator"
}
]
}
|
| 2 |
OHIP sends the request over to OPERA Cloud. |
| 3 |
OPERA Cloud sends out the request to the connected Door Lock System using the
POST roomKeysOutbound operation. |
Mobile Key Outbound Request
POST {{HostName}}/fof/v1/hotels/{{HotelId}}/roomKeysOutbound
{
"keyType": "New",
"encoderTerminal": "TERM1",
"encoderId": "",
"roomKeyType": "MobileKey",
"keyUserType": "Guest",
"keyRequestTime": "2024-02-26T16:16:10.295Z",
"roomId": "101",
"oldRoomId": "",
"noOfKeys": 1,
"reservationIdList": [
{
"id": "{{ReservationId}}",
"type": "Reservation"
},
{
"id": "2468024",
"type": "Confirmation"
}
],
"guestShareFlag": "false",
"OldGuestShareFlag": "",
"keyValidityStart": "2024-02-26T11:16:16.000Z",
"keyValidityEnd": "2024-02-27T12:00:00.000Z",
"additionalRooms": [
"",
""
],
"userId": "ExternalUser",
"keyOptions": [
{
"keyOptionsCode": "SAU",
"keyOptionDescription": "Sauna"
},
{
"keyOptionsCode": "ELEV",
"keyOptionDescription": "Elevator"
}
]
}
|
| 4 |
The door lock system responds to OPERA Cloud within 20 seconds with a "201"
status message containing the mobile key data or (in case of unsuccessful request)
with a "201" response containing information on why the request could not be
processed. |
Mobile Key Outbound Response
Response on POST {{HostName}}/fof/v1/hotels/{{HotelId}}/roomKeysOutbound
{
"roomId": "101",
"responseCode": "OK",
"encoderTerminal": "",
"roomKeyType": "MobileKey",
"keyUserType": "Guest",
"keyValidityStart": "2024-02-26T11:16:16.000Z",
"keyValidityEnd": "2024-02-27T12:00:00.000Z",
"keyCreationTime": "2024-02-26T16:16:16.138Z",
"noOfKeys": "1",
"encoderId": "",
"reservationIdList": [
{
"id": "{{ReservationId}}",
"type": "Reservation"
},
{
"id": "2468024",
"type": "Confirmation"
}
],
"responseText": "Mobile Key successfully created",
"additionalRooms": [
"",
""
],
"keyOptions": [
{
"keyOptionsCode": "SAU",
"keyOptionDescription": "Sauna",
"isEnabled": "true",
"default": "false"
},
{
"keyOptionsCode": "ELEV",
"keyOptionDescription": "Elevator",
"isEnabled": "true",
"default": "false"
},
{
"keyOptionsCode": "MAIN",
"keyOptionDescription": "MainEntrance",
"isEnabled": "true",
"default": "true"
}
],
"userId": "ExternalUser",
"digitalKeyData": "674569445729451535dgrth345342535ttrhtzjtz7684ugweg5544345756756zrgewrgq43t5z5z",
"keyImage": "",
"cardSerialNumber": ""
}
Mobile Key Outbound Response
{
"roomId": "101",
"responseCode": "UR",
"encoderTerminal": "TERM1",
"roomKeyType": "MobileKey",
"keyUserType": "Guest",
"keyValidityStart": "2024-09-30T10:16:10.000Z",
"keyValidityEnd": "2024-09-30T18:00:00.000Z",
"keyCreationTime": "2024-09-30T11:21:15.290Z",
"encoderId": "1",
"responseText": "Room not found.",
"additionalRooms": [],
"userId": "External"
}
|
| 5 |
OPERA Cloud sends the response back to OHIP. |
| 6 |
OHIP sends back the 201 response to the external system that requested the mobile
key containing the mobile key data.
The external system should display the related "responseText" value so the user
who requested the key will be aware that the request was successful.
In case of an unsuccessful request to create/activate a room key OHIP will respond
to the external system with a "400" message containing the response information text
from the Door Lock system.
The external system should display the related "responseText" value so the user
who requested the key will be aware of why a request was not successful.
|
Mobile Key Response External
Response on POST {{HostName}}/fof/v1/hotels/{{HotelId}}/roomKeysExternal
{
"roomId": "101",
"responseCode": "OK",
"encoderTerminal": "",
"roomKeyType": "MobileKey",
"keyUserType": "Guest",
"keyValidityStart": "2024-02-26T11:16:16.000Z",
"keyValidityEnd": "2024-02-27T12:00:00.000Z",
"keyCreationTime": "2024-02-26T16:16:16.138Z",
"noOfKeys": "1",
"encoderId": "",
"reservationIdList": [
{
"id": "{{ReservationId}}",
"type": "Reservation"
},
{
"id": "2468024",
"type": "Confirmation"
}
],
"responseText": "Mobile Key successfully created",
"additionalRooms": [
"",
""
],
"keyOptions": [
{
"keyOptionsCode": "SAU",
"keyOptionDescription": "Sauna",
"isEnabled": "true",
"default": "false"
},
{
"keyOptionsCode": "ELEV",
"keyOptionDescription": "Elevator",
"isEnabled": "true",
"default": "false"
},
{
"keyOptionsCode": "MAIN",
"keyOptionDescription": "MainEntrance",
"isEnabled": "true",
"default": "true"
}
],
"userId": "ExternalUser",
"digitalKeyData": "674569445729451535dgrth345342535ttrhtzjtz7684ugweg5544345756756zrgewrgq43t5z5z",
"keyImage": "",
"cardSerialNumber": ""
}
Unsuccessful Response External System (referring to above "Unsuccesful response
Outbound")
{
"type": "Bad Request",
"title": "Unable to generate a room key for reservation. Key encoder status: Room not found.",
"status": "NotProcessed",
"detail": "Unable to generate a room key for reservation. Key encoder status: Room not found.",
"o:errorCode": "OPERAWS-FOF00200",
"language": "en"
}
|
