External Integrations Help
Overview
The External Integrations tab lets you connect a site controller (property management system) to UnlockOS to automatically import reservations and optionally push door PIN codes back to the provider. Currently the Neppan provider is supported.
What you can do on this tab:
- Register your site controller API credentials
- Choose a sync mode: import-only (1-way) or import plus PIN push (2-way)
- Map external provider rooms to UnlockOS rooms
- Monitor sync status and last sync time
- Trigger an immediate manual sync
- Review the sync log history
- Delete the integration
This tab is only accessible to Platform Admin users (controlled by the
tab_integrationsfeature flag).
How to Access
Connection Settings → External Integrations tab
Features
Feature 1: Provider Selection
When no integration has been configured, a provider selection card is shown. Currently supported providers:
| Provider | Description |
|---|---|
| Neppan | Property management / site controller system for Japanese ryokan and hotels |
Click the provider card to open the configuration form.
Feature 2: API Credentials
After selecting a provider, the configuration form appears.
Neppan Configuration Fields
| Field | Description | Example |
|---|---|---|
| API Domain | The Neppan server domain prefix | www48 (resolves to https://www48.neppan.net) |
| User ID | Login user ID | - |
| Password | Login password | - |
| User Code | Neppan user code | - |
| Accommodation Code | Neppan accommodation code | - |
| Master User Code | User code for the master account used to push PINs | - |
| Master User Password | Password for the master account | - |
When updating an existing configuration: If the User ID and Password fields are left blank, the previously saved encrypted credentials are preserved. Only fill them in when you need to change the credentials.
Enabled Checkbox
Checking Enabled activates the recurring automatic sync schedule. The first time you enable the integration, a green banner appears guiding you to the Check-in tab in Booking Management, where you can copy the guest-facing check-in URL to share with guests.
Manual sync is available even when this is unchecked.
Save and Test Connection
| Button | Description |
|---|---|
| Save | Saves the configuration. User ID and Password are required for a new integration |
| Test Connection | Verifies connectivity to the API using the saved credentials (available after saving) |
Feature 3: Sync Mode
| Mode | Description |
|---|---|
| 1-Way (Import only) | Imports reservation data from Neppan into UnlockOS |
| 2-Way (Import + PIN push) | Imports reservations and automatically sends the UnlockOS door PIN back to Neppan |
2-Way mode requires the Master User Code and Master User Password to be configured.
Feature 4: Sync Status
Once a configuration is saved, the Sync Status card appears.
| Field | Description |
|---|---|
| Last Sync | Timestamp of the most recent sync |
| Status | Sync result: success, error, or not yet run |
| Sync Now | Button to trigger an immediate manual sync |
If an error occurred during the last sync, the error details are shown below the status card.
Feature 5: Room Mappings
Map rooms from the external provider to UnlockOS rooms. Only reservations for mapped rooms will be imported.
Fetching Rooms from the Provider
- Click Fetch Rooms from Provider.
- Room master data is retrieved from Neppan and listed in the table.
- For each external room, select the corresponding UnlockOS room from the dropdown.
- Click Save Mappings to confirm.
Guest Form ON/OFF
At the top of the Room Mappings section is a Guest Form toggle. This controls whether guests using this integration must fill out the guest form during self check-in.
| State | Description |
|---|---|
| ON (green) | Guests must fill out the guest form (passport, name, address, etc.) during self check-in |
| OFF (grey) | Guests can skip the guest form and check in without filling it out |
The default is ON. Accommodation providers are generally required by law to verify guest identity — keep this ON unless you have a specific reason to disable it.
Room Mapping Table Columns
| Column | Description |
|---|---|
| External Room | The room name or ID from Neppan |
| Type | The room type name from Neppan |
| UnlockOS Room | The matching UnlockOS room (select from dropdown) |
Only rooms that are active in Facility Settings appear in the UnlockOS room dropdown.
Feature 6: Sync Log
The most recent 10 sync records are shown in the sync log. Both scheduled and manual syncs are recorded.
| Column | Description |
|---|---|
| Time | When the sync ran |
| Type | Sync type (scheduled, manual, etc.) |
| Status | Success (green) or error (red) |
| Created | Number of reservations created in this sync |
| Updated | Number of reservations updated in this sync |
| Cancelled | Number of reservations cancelled in this sync |
Feature 7: Delete Integration
Click the Delete button in the top-right of the configuration card. A confirmation dialog appears before the integration is permanently removed.
Deleting the integration does not remove reservations that were already imported. They remain in your Reservations list and Calendar.
Frequently Asked Questions
Q: The connection test fails
Check the following:
- The API domain is correct (refer to your Neppan contract details)
- The User ID and Password are entered correctly
- The User Code and Accommodation Code are correct
- API access is enabled on the Neppan side
Q: The sync status shows "error"
Review the error message shown below the Sync Status card. Common causes:
- Expired or changed credentials (update and re-save the configuration)
- Connection timeout to the Neppan server (wait a few minutes and try manual sync again)
- Room mappings not configured (click "Fetch Rooms from Provider" and set up mappings)
Q: Reservations are not being imported
- Verify that room mappings are configured correctly.
- Confirm the Enabled checkbox is checked.
- Click Sync Now to run a manual sync and review the sync log.
- Confirm that reservations exist on the Neppan side.
Q: PINs are not being pushed in 2-Way mode
2-Way sync requires both Master User Code and Master User Password to be set. If these fields are empty, PIN delivery will not occur.
Q: No rooms appear in the UnlockOS room dropdown
Rooms must be created and set as active in Facility Settings before they appear here. Add or activate rooms in the Facility Settings first.
Q: Clicking "Fetch Rooms from Provider" shows nothing
Either there are no room records in Neppan, or the configured credentials have a problem. Run the connection test to verify the credentials are correct.
Q: Where do I find the guest-facing check-in URL after setup?
In the Booking Management dashboard, open the Check-in tab. When the Neppan integration is enabled, a URL card for the integration appears there. Click the copy button to copy the URL and share it with your guests.
Q: How do I stop requiring the guest form for guests checking in through this integration?
Turn off the Guest Form toggle in the Room Mappings section. Guests using this integration will then be able to skip the guest form during self check-in. Note that accommodation regulations typically require guest identity verification, so keep it ON unless there is a specific reason to disable it.