Using the Nuki electronic door lock with SuperSaaS

One of the many ways SuperSaaS can be used is for renting out houses, rooms or apartments. Because it’s a hassle to hand over a physical key to a customer and get it returned, a lot of these business have started using electronic locks. Installing an electronic lock is no longer a major investment as they can be easily installed, and in the case of Nuki doesn’t even require replacing the existing lock. Now the next level of convenience can be to automatically create and send the access information to your customers as soon as a reservation has been completed.

Using an electronic lock in combination with SuperSaaS can also be used for purposes other than rental, such as time-based access to a meeting room, computer lab, or a sports facility.

This tutorial is for customers that have a Nuki door lock, because Nuki is one of the most popular brands and several customers have asked us if it was possible to use their Nuki lock with SuperSaaS. Other brands offer similar functionality and this tutorial may help with those locks too.

The concept:

Each time a new appointment is created on a SuperSaaS schedule, a code is generated and stored in a specific Nuki keypad, with a time frame for which it’s valid. The code is sent automatically to the customer in the confirmation email. If you’re concerned about the security aspect of sending the door access code you can configure an appointment approval step prior to this code being sent.

Prerequisites:

• You have a Nuki lock, a Nuki Keypad and a Nuki Bridge or built-in WiFi (e.g. Smart Lock 3.0 Pro or higher).
• You have created a ‘resource schedule’ in SuperSaaS for the house, apartment or room you want to rent out.
• You have a paid SuperSaaS subscription (required for so called ‘custom webhooks’ that are used).
• You have activated free access to Nuki Web via the Nuki app (under Features & Configuration).

Note: other schedule types than ‘resource’ will work too, but a ‘resource schedule’ is probably what you’ll need for this particular use case.

Current limitations:

• There is a maximum of 100 codes for the Nuki Keypad and 200 codes for the Nuki Keypad 2.0 (with fingerprint reader).
• Expired codes have to be deleted manually via the app or the web portal. If you delete a code via the app it will only disappear from the portal a day later. If you delete it via the portal it will immediately be removed from the app and the keypad.

Overview of steps:

1. Activate the API at the Nuki Web Portal.
2. Identify the lock ID.
3. Configure a webhook in SuperSaaS (to stores a random code with a validity period in the keypad via the API from Nuki).
4. Set the timing of the webhook to update the keypad shortly before the rental period.
5. Add the code to the automatic reminder email from SuperSaaS.

Note: these steps may sound a bit technical, but it’s actually quite simple and again, no programming knowledge is required!

Step 1: activating the API at the Nuki Web Portal

Go to the Nuki Web Portal

Under API, choose Activate Nuki Web API, accept the Terms and Conditions and click Activate Nuki Web API.

Click ‘Generate API token’.

Enter a random name for API token name and select all checkboxes for the access rights.

After pressing ‘Save’ copy the code that you see there (by selecting the code and then right click to copy). Save this code somewhere for later on. If you forgot, you can easily create a new one.

Step 2: identifying the lock ID

Getting the lock ID from Nuki can be done in two ways and it can be a bit confusing. Option 2 is a bit quicker but a bit more technical.

Option 1:

• In the Nuki app go to Features & Configuration, then General. Copy the Device ID (e.g. 34FDAF45)
• Convert this ‘hexadecimal’ number to a decimal number via this website but first add a ‘4’ in front of the number (see example image). The decimal number is the smartlockId you need in the next step.

Option 2:

• Execute the following command in a Terminal window (on a Mac) curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 72f6740dc9653f287e9368eee30afa142cea5caae3949bafb32' 'https://api.nuki.io/smartlock' where you replace the code after Bearer with the code you copied at the Nuki Web Portal earlier.
• In the response that you get the smartlockId is mentioned as the first number.

Step 3: configure the webhook at SuperSaaS

On your SuperSaaS Dashboard, click ‘Integrations’ and then choose ‘Webhooks’. Find more information about the use of webhooks here, although not needed for this tutorial.

Enter the following information:

• Trigger: choose ‘Reminder’
• Schedule: choose the schedule for which you want to configure a keypad
• Target URL: https://bearer:API-TOKEN@api.nuki.io/smartlock/SMARTLOCK-ID/auth?_method=put

Note: Choose ‘Reminder’ instead of ‘New appointment’ even if you choose to send the code as part of the confirmation email with the creation of the new appointment. This has the benefit that the code will be stored in the keypad when there’s minimal chance of the reservation being canceled or changed.

The target URL will then look like this: https://bearer:72f6740dc965eea5caae3949bafb31@api.nuki.io/smartlock/18068913969/auth?_method=put

Press ‘Create Webhook’.

Behind ‘Payload’ select ‘Custom’. Note: If this option isn’t available you need to get a paid subscription first.

Copy and paste the following information in the text field:

{
"name": "$start",
"allowedFromDate": "$start_utc",
"allowedUntilDate": "$finish_utc",
"allowedWeekDays": 0,
"type": 13,
"code": "$doorcode"
}

Press ‘Update webhook’

You can now press ‘Test webhook’ and press ‘Post payload now’.

Important: each code can only be entered once, so if you use the “Test webhook” facility to create a code for an appointment, executing the webhook for the reminder email later may fail if the same code is used. To prevent this from happening, update the code each time you test the webhook to a different number with 6 digits (and no zeros in the number or 12 at the beginning).

If successful, a new entry with a code should be created for the device after a few seconds. Find it under ‘Keypad’ on the Nuki portal and in the app (you may need to refresh the page if you’re on it).

By using $start the entries in the keypad will be displayed with the start date as the name in the app (see image).

This makes it easy to find the code in order to provide it to the customer in case they forgot it. It also makes it easier to remove expired codes. Alternatively, replace $start by $id. You can then enable displaying the reservation ID on the reservation and the list view to easily find the ID.

Note: It’s not advisable to use the name of the customer, as the keypad has a limitation of 30 characters for the name. If the name of the customer is longer, storing the code will fail.

Step 4: configure the timing of the webhook and the email

On the tab ‘Process’ under the option ‘Should we send a reminder or follow-up for the reservation?’ select ‘Trigger a webhook an hour in advance’. By doing this, the code is deliberately sent to the keypad as late as possible, which prevents issues with canceled reservations or changed reservation dates.

In order to trigger sending the reminder e-mail select ‘Send a follow-up email’ and change the value to ‘-1 days’.

Step 5: add the code to the automatic email to the customer

Simply add $doorcode to the reminder email that is sent to the customer (on the tab ‘Layout’) shortly before the rental period. Optionally, you can also include the code in the confirmation email.

That’s it!

Final remarks

For multiple rooms and locks, repeat these steps with a different schedule and a different lock ID (the API token from the Web Portal is connected to your Nuki account and will be the same for each lock).

The reason this tutorial is for a lock in combination with a keypad is because this allows your customer to use the lock through a code shared by email, with no need to install the Nuki app on their phone. With some modifications, the same principle can be used to automatically create access to the Nuki app for a lock instead.

As mentioned above, if you’re concerned about the security aspect you can configure an approval step before this code is sent or simply require payment upfront.

This tutorial fulfills the basic need of using the Nuki lock in combination with SuperSaaS. More advanced needs can be accommodated by using a service such as Make, which has an integration with SuperSaaS. Think of scenarios such as allowing the lock to be opened an hour before the rental period. It’s also possible to remove expired codes automatically as the Nuki API allows it, but this requires significantly more effort.

This tutorial is based on the following information from Nuki: https://developer.nuki.io/t/web-api-example-manage-pin-codes-for-your-nuki-keypad/54