neppan! Integration Help
Overview
neppan! is a site controller (property management system) for Japanese ryokan and hotels. By connecting it to UnlockOS, reservations from neppan! are automatically imported and guests can use self check-in.
What you can do on this page:
- Register or update neppan! API credentials
- Choose a sync mode: import-only (1-way) or import plus door PIN push (2-way)
- Map neppan! rooms to UnlockOS rooms
- Monitor sync status and trigger manual syncs
- Review sync log history
- Delete the integration
This page is only accessible to Facility Owners, Organization Owners, and Platform Admins (controlled by the
tab_integrationsfeature flag).
How to access
Connection Settings → External Integrations → click the neppan! card
A breadcrumb navigation bar at the top of the page shows External Integrations / neppan!.
Page layout
Sections appear in order as your configuration progresses:
- Settings form card — connection info, credentials, sync mode, enable toggle (always shown)
- Sync Status card — last sync time, status badge, and Sync Now button (shown after saving)
- Room Mappings card — map neppan! rooms to UnlockOS rooms (shown after saving)
- Sync Log card — timeline of sync history (shown when sync records exist)
Settings form
Connection group
| Field | Description | Example |
|---|---|---|
| API Domain | The neppan! server domain prefix | www48 (used as https://www48.neppan.net) |
| Sync Mode | Direction of synchronization (see below) | 1Way or 2Way |
The API Domain is listed in your neppan! contract details. Only enter the domain part (e.g. www48) — https:// is added automatically.
Credentials group
| Field | Description |
|---|---|
| User ID | neppan! login user ID |
| Password | neppan! login password |
| User Code | neppan! user code |
| Accommodation Code | neppan! accommodation code |
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 credentials. A field showing
(saved)indicates an existing value is active.
Master credentials group
| Field | Description |
|---|---|
| Master User Code | User code for the master account used to push PINs |
| Master User Password | Password for the master account |
Master credentials are only required for 2-Way sync mode to send door PINs back to neppan!. They are not needed for 1-Way mode, but it is recommended to configure them in advance if you plan to switch to 2-Way later.
Sync mode
| Mode | Description | Use when |
|---|---|---|
1Way (Import only) |
Import reservations from neppan! into UnlockOS | Managing keys only through UnlockOS check-in URL |
2Way (Import + PIN push) |
Import reservations and automatically push the UnlockOS door PIN back to neppan! | neppan! should also display or deliver key PIN information |
2-Way mode requires Master User Code and Master User Password to be configured.
One account per facility: A single neppan! account (same accommodation code) can only be connected to one UnlockOS facility at a time. If the same account is already active in another facility, an error will appear when you try to save.
Enable toggle
Turning on the "Enabled" toggle activates the recurring automatic sync schedule.
- ON: Sync runs automatically on a background schedule
- OFF: Automatic sync stops; you can still run a manual sync with the "Sync Now" button
First-time enable: A green banner appears after the integration is enabled. Click the "Go to Check-in Tab" button in the banner — or the persistent link in the settings form — to navigate to the Check-in tab in Booking Management, where you can copy the guest-facing check-in URL.
Buttons
| Button | Description | Notes |
|---|---|---|
| Save | Save the configuration | User ID and Password are required for a new integration |
| Test Connection | Verify connectivity to neppan! API using saved credentials | Only available after saving (grayed out otherwise) |
| Delete | Delete the integration (top-right of the card) | Already-imported reservations are not removed |
Sync Status card
Once the configuration is saved, the Sync Status card appears below the settings form.
| Field | Description |
|---|---|
| Last Sync | Timestamp of the most recent completed sync |
| Status | Result badge (see table below) |
| Sync Now button | Immediately trigger a reservation import (and PIN push in 2-Way mode) |
Status badge values
| Badge | Meaning |
|---|---|
success (green) |
The previous sync completed successfully |
error (red) |
The sync encountered an error |
partial (yellow) |
Some operations succeeded but others failed |
pending (grey) |
Sync has not run yet |
When status is error or partial, an error message appears below the card. Multiple errors are collapsed by default and can be expanded with the "Show details" button.
Room Mappings card
Map neppan! rooms to UnlockOS rooms. Only reservations for mapped rooms will be imported.
Guest Form toggle
At the top of the Room Mappings section is a Guest Form toggle.
| State | Description |
|---|---|
| ON (green) | Guests checking in through this integration 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.
Fetching and mapping rooms
- Click "Fetch Rooms from Provider"
- Room master data is retrieved from neppan! and displayed in the table
- For each neppan! room, select the matching UnlockOS room from the dropdown
- Click "Save Mappings" to confirm
After changing dropdown selections, always click "Save Mappings." Changes are not saved automatically.
Room mapping table columns
| Column | Description |
|---|---|
| External Room | Room name (or ID) from neppan! |
| Type | Room type name from neppan! (external_room_type_name) |
| UnlockOS Room | Select the matching UnlockOS room from the dropdown |
Only rooms that are active in Facility Settings appear in the UnlockOS room dropdown. If no rooms appear, add and activate rooms in Facility Settings first.
On mobile, mappings are shown as individual cards instead of a table. The controls work the same way.
Sync Log card
The sync history is displayed in a timeline format. The 10 most recent sync records are shown (both scheduled and manual syncs are recorded).
Log entry fields
| Field | Description |
|---|---|
| Sync type | reservation_pull (reservation import) or master_sync (room master data fetch) |
| Status | success, error, or partial |
| Created | Reservations created in this sync |
| Updated | Reservations updated in this sync |
| Cancelled | Reservations cancelled in this sync |
| Error | Expandable error details if an error occurred |
How it works
Automatic sync schedule
A pg_cron (database scheduler) job runs every 5 minutes and calls the integration-sync Edge Function. The function checks the sync_interval_minutes value for each facility (default: 15 minutes). If less than that interval has passed since the last sync, the run is skipped.
This means changes in neppan! appear in UnlockOS within up to 15 minutes (based on the default setting).
What gets synced
- New reservations (
reservations_created) - Updated reservations (
reservations_updated) - Cancelled reservations (
reservations_cancelled) - Door PIN push to neppan! (
pins_pushed, 2-Way mode only)
Credential storage
User ID, Password, and Master credentials are encrypted using pgsodium (AES-GCM) before being stored in the database (credentials_encrypted column). API Domain, User Code, and Accommodation Code are non-sensitive and stored as plain JSONB (config column).
Duplicate import prevention
Each neppan! reservation has a unique identifier (external_event_uid). The database prevents the same reservation from being imported twice using a unique index.
Deleting the integration
Click the "Delete" button in the top-right of the settings card. A confirmation dialog appears before anything is deleted. Upon confirmation:
- The integration configuration (
integration_connectionsrecord) is deleted - Room mappings are deleted (cascade)
- Sync log entries are deleted (cascade)
Reservations that were already imported are not deleted. They remain in your Reservations list and Calendar.
Troubleshooting
The connection test fails
Check the following in order:
- Is the API domain correct? — Verify the domain in your neppan! contract (e.g.
www48) - Are the User ID and Password correct? — Check for accidental whitespace or full-width characters
- Are the User Code and Accommodation Code correct? — Verify them in the neppan! admin panel
- Is API access enabled on the neppan! side? — Contact neppan! support if unsure
Sync status shows error or partial
Review the error message shown below the Sync Status card. Common causes:
- Expired or changed credentials: Re-enter and save the credentials in the settings form
- Connection timeout to neppan! server: Wait a few minutes and try manual sync again
- Room mappings not configured: Click "Fetch Rooms from Provider" and set up mappings
Reservations are not being imported
- Confirm the "Enabled" toggle is ON
- Verify that room mappings are configured correctly (UnlockOS room is selected for each external room)
- Click "Sync Now" to trigger a manual sync and check the sync log for errors
- Confirm that reservations actually exist on the neppan! side
- If nothing appears after 5–15 minutes, contact support
PINs are not being pushed in 2-Way mode
Verify that Master User Code and Master User Password are both configured. If either field is empty, PIN delivery will not occur. Save the settings and click "Sync Now" to test.
No rooms appear in the UnlockOS room dropdown
No active rooms are registered under this facility. Go to Facility Settings and add or activate rooms before returning here.
Clicking "Fetch Rooms from Provider" shows nothing
Either there are no room records in neppan!, or the credentials have a problem. Run the connection test first to verify the credentials are valid.
Error: "The same account is already active in another facility"
A single neppan! account (accommodation code) can only connect to one UnlockOS facility at a time. Disable or delete the integration in the other facility, then retry.
FAQ
Q: When should I use 1-Way vs 2-Way?
A: Use 2-Way if you want neppan! to also display or deliver the door PIN to guests. If you manage access entirely through the UnlockOS self check-in URL, 1-Way is sufficient. 2-Way requires master credentials to be configured.
Q: Can each facility use a different neppan! account?
A: Yes. Each facility has its own independent integration. However, one neppan! account (accommodation code) can only be connected to one facility at a time.
Q: How are neppan!-imported reservations different from reservations created directly in UnlockOS?
A: Imported reservations have an integration_connection_id set, which identifies their source. You can still modify, cancel, or manage them within UnlockOS.
Q: Is it safe to turn off the Guest Form?
A: Accommodation regulations often require identity verification of guests. Review the applicable laws and regulations before disabling the Guest Form.
Q: How frequently does automatic sync run?
A: The background job runs every 5 minutes, but actual sync frequency depends on the facility's sync_interval_minutes setting (default: 15 minutes). Sync runs only when that interval has elapsed since the last successful sync.
Q: Can I reconnect after deleting the integration?
A: Yes. You can reconfigure the integration at any time. Note that room mappings are also deleted, so you will need to set them up again after reconnecting.
Q: Where do I find the guest-facing check-in URL?
A: In the Booking Management dashboard, open the Check-in tab. A URL card for the neppan! integration appears there when the integration is enabled. Use the copy button to copy the URL and share it with guests. You can also navigate there directly from the link in the settings form.