# ねっぱん! 連携 ヘルプ ## 概要 ねっぱん! は旅館・ホテル向けのサイトコントローラー（宿泊管理システム）です。UnlockOS と連携することで、ねっぱん! 上の予約を自動でインポートし、ゲストのセルフチェックインを実現します。 このページでできること： - ねっぱん! の API 資格情報を登録・更新する - 同期モード（予約インポートのみ / 予約インポート + 鍵 PIN 配信）を選択する - ねっぱん! の客室を UnlockOS の部屋にマッピングする - 同期ステータスの確認と手動同期の実行 - 同期ログ履歴の確認 - 連携設定の削除 > このページにアクセスできるのは施設オーナー・組織オーナーのみです（`tab_integrations` フィーチャーフラグで制御）。 --- ## アクセス方法 接続設定 → **外部連携** → **ねっぱん!** カードをクリック ページ上部には `外部連携 / ねっぱん!` のパンくずナビゲーションが表示されます。 --- ## ページの構成 このページは設定の進捗に応じて以下のセクションが順番に表示されます： 1. **設定フォームカード** — 接続情報・資格情報・同期モード・有効化トグル（常時表示） 2. **同期ステータスカード** — 最終同期日時・ステータス・「今すぐ同期」ボタン（設定保存後に表示） 3. **部屋マッピングカード** — ねっぱん! 客室と UnlockOS 部屋の対応付け（設定保存後に表示） 4. **同期ログカード** — タイムライン形式の同期履歴（同期実績がある場合に表示） --- ## 設定フォーム ### 接続情報グループ | フィールド | 説明 | 入力例 | |-----------|------|--------| | API ドメイン | ねっぱん! サーバーのドメイン名 | `www48`（`https://www48.neppan.net` として使用される） | | 同期モード | 連携の方向性（後述） | `1Way` または `2Way` | API ドメインはねっぱん! の契約情報に記載されています。`https://` は自動で付加されるため、ドメイン部分（例: `www48`）のみ入力してください。 ### 資格情報グループ | フィールド | 説明 | |-----------|------| | ユーザー ID | ねっぱん! のログイン用ユーザー ID | | パスワード | ねっぱん! のログイン用パスワード | | ユーザーコード | ねっぱん! のユーザーコード | | 宿泊施設コード | ねっぱん! の宿泊施設コード | > **既存設定の更新時**: ユーザー ID・パスワードのフィールドが空の場合、保存済みの暗号化された認証情報がそのまま保持されます。認証情報を変更する場合のみ入力してください。フィールドに `(saved)` と表示されている場合は既存の値が有効です。 ### マスター資格情報グループ | フィールド | 説明 | |-----------|------| | マスターユーザーコード | PIN 配信に使用するマスターアカウントのユーザーコード | | マスターユーザーパスワード | マスターアカウントのパスワード | マスター資格情報は **2Way 同期モード** で鍵 PIN をねっぱん! に送信するために使用します。1Way モードでは不要ですが、将来的に 2Way に切り替える場合に備えて設定しておくことを推奨します。 ### 同期モードの選択 | モード | 説明 | 用途 | |--------|------|------| | `1Way`（インポートのみ） | ねっぱん! から予約データを UnlockOS にインポートする | 鍵管理は UnlockOS 側のみで完結する場合 | | `2Way`（インポート + PIN 配信） | インポートに加え、UnlockOS で発行した鍵 PIN をねっぱん! に自動送信する | ねっぱん! 側でも鍵情報を管理したい場合 | 2Way モードには **マスターユーザーコード** と **マスターユーザーパスワード** の設定が必須です。 > **1 施設 × 1 アカウント制約**: 同じねっぱん! アカウント（同一の宿泊施設コード）は、UnlockOS 内の 1 施設にのみ接続できます。既に他の施設で同じアカウントが有効化されている場合、保存時にエラーが表示されます。 ### 有効化トグル 「有効化」トグルをオンにすると定期自動同期が開始されます。 - **ON**: 5 分ごとの自動同期バッチが実行されます - **OFF**: 自動同期は停止しますが、「今すぐ同期」ボタンで手動同期は実行できます **初回有効化時**: 連携設定が完了すると緑のバナーが表示されます。バナー内の「チェックインタブへ」ボタン、または設定フォーム内のリンクから、予約管理ダッシュボードの**チェックインタブ**に移動してください。そこでゲスト向けチェックイン URL の確認・コピーができます。 ### 操作ボタン | ボタン | 説明 | 注意 | |--------|------|------| | **保存** | 設定を保存します | 新規登録時はユーザー ID とパスワードが必須 | | **接続テスト** | 保存済みの認証情報でねっぱん! API への接続を確認します | 設定を保存後に使用可能（未保存の場合はグレーアウト） | | **削除** | 連携設定を削除します（ヘッダー右上） | 削除後も既存インポート済み予約は残ります | --- ## 同期ステータスカード 設定が保存されると、設定フォームの下に同期ステータスカードが表示されます。 | 項目 | 説明 | |------|------| | 最終同期 | 直近の同期が完了した日時 | | ステータス | 同期結果のバッジ（下表参照） | | **今すぐ同期** ボタン | 即時で予約インポート（+ 2Way の場合は PIN 配信）を実行 | ### ステータスバッジの種類 | バッジ | 意味 | |--------|------| | `success` （緑） | 前回の同期が正常に完了した | | `error` （赤） | 同期でエラーが発生した | | `partial` （黄） | 一部の処理は成功したが、一部でエラーが発生した | | `pending` （グレー） | まだ同期が実行されていない | エラーまたは partial の場合、ステータスカードの下にエラーメッセージが表示されます。複数エラーがある場合は折りたたまれて表示され、「▼ 詳細を表示」ボタンで展開できます。 --- ## 部屋マッピングカード ねっぱん! の客室と UnlockOS の部屋を対応付けます。マッピングされた客室の予約のみがインポートされます。 ### ゲストフォームトグル 部屋マッピングセクションの上部に **ゲストフォーム** トグルがあります。 | 状態 | 説明 | |------|------| | ON（緑） | この連携でチェックインするゲストに、パスポート・氏名・住所などのフォーム入力を要求する | | OFF（グレー） | ゲストフォームの入力をスキップしてチェックインできる | > 宿泊施設の法令では本人確認が義務付けられているため、デフォルトは ON です。特段の理由がない限り ON のままにしてください。 ### 客室データの取得とマッピング手順 1. **「プロバイダーから部屋を取得」** ボタンをクリックする 2. ねっぱん! から客室マスターデータが取得され、テーブルに表示される 3. 各外部客室の「UnlockOS 部屋」ドロップダウンから対応する UnlockOS の部屋を選択する 4. **「マッピングを保存」** ボタンをクリックして確定する マッピングを変更した場合は必ず「マッピングを保存」をクリックしてください。ドロップダウンを変更しただけでは保存されません。 ### 部屋マッピングテーブルの列 | 列 | 説明 | |----|------| | 外部客室名 | ねっぱん! 側の客室名（または客室 ID） | | タイプ | ねっぱん! 側の客室タイプ名（`external_room_type_name`） | | UnlockOS 部屋 | 対応させる UnlockOS の部屋をドロップダウンで選択 | > UnlockOS 部屋のドロップダウンには、施設設定でアクティブ（有効）になっている部屋のみが表示されます。部屋が表示されない場合は施設設定で部屋を追加・有効化してください。 モバイル表示ではテーブルの代わりにカード形式でマッピングが表示されます。操作方法は同じです。 --- ## 同期ログカード 同期の実行履歴がタイムライン形式で表示されます。直近 10 件が表示されます（自動同期・手動同期の両方を記録）。 ### ログの列 | 項目 | 説明 | |------|------| | 同期タイプ | `reservation_pull`（予約取込）/ `master_sync`（客室マスターデータ取得） | | ステータス | `success` / `error` / `partial` | | 作成 | この同期で新規作成された予約件数 | | 更新 | この同期で更新された予約件数 | | キャンセル | この同期でキャンセルになった予約件数 | | エラー | エラーがある場合に展開可能なメッセージを表示 | --- ## バックエンド動作 ### 自動同期の仕組み pg_cron（データベースのスケジューラー）が 5 分ごとに `integration-sync` Edge Function を呼び出します。Edge Function は各施設の `sync_interval_minutes`（デフォルト 15 分）を参照し、前回同期からの経過時間が設定値に満たない場合はスキップします。 つまり、**ねっぱん! 上の予約変更は最大 15 分（設定による）で UnlockOS に反映**されます。 ### 同期される内容 - 予約の新規作成（`reservations_created`） - 予約の変更（`reservations_updated`） - 予約のキャンセル（`reservations_cancelled`） - 鍵 PIN の送信（`pins_pushed`、2Way モードのみ） ### 認証情報の保管 ユーザー ID・パスワード・マスター資格情報はデータベース上でpgsodium（AES-GCM 系暗号化）により暗号化されて保管されます（`credentials_encrypted` カラム）。API ドメイン・ユーザーコード・宿泊施設コードは機密情報でないため非暗号化 JSONB（`config` カラム）として保管されます。 ### 重複インポートの防止 ねっぱん! の予約には一意の識別子（`external_event_uid`）が付与されており、同じ予約が 2 度インポートされないようにデータベースレベルで制御されています。 --- ## 連携の削除 設定カード右上の **「削除」** ボタンをクリックすると確認ダイアログが表示されます。確認後、以下が実行されます： - 連携設定（`integration_connections` レコード）が削除される - 部屋マッピングが削除される（カスケード削除） - 同期ログが削除される（カスケード削除） > 既にインポートされた予約は削除されません。予約一覧・カレンダー上に残り続けます。 --- ## トラブルシューティング ### 接続テストが失敗する 以下を順番に確認してください： 1. **API ドメインが正しいか** — ねっぱん! の契約書・管理画面でドメインを確認（例: `www48`） 2. **ユーザー ID・パスワードが正確か** — 半角スペースや全角文字が混入していないか 3. **ユーザーコード・宿泊施設コードが正しいか** — ねっぱん! の管理画面で確認 4. **ねっぱん! 側で API アクセスが有効か** — ねっぱん! サポートに確認 ### 同期ステータスが `error` または `partial` になっている ステータスカード下部のエラーメッセージを確認してください。よくある原因： - **認証情報の期限切れまたは変更**: 設定フォームで認証情報を再入力して保存し直す - **ねっぱん! サーバーへの接続タイムアウト**: しばらく待ってから手動同期を再試行する - **部屋マッピングが未設定**: 「プロバイダーから部屋を取得」してマッピングを設定する ### 予約がインポートされない 1. 「有効化」トグルが ON になっているか確認する 2. 部屋マッピングが正しく設定されているか確認する（UnlockOS 部屋が選択されているか） 3. 「今すぐ同期」ボタンで手動同期を実行し、同期ログでエラーを確認する 4. ねっぱん! 側で予約が実際に登録されているか確認する 5. 5〜15 分待っても反映されない場合はサポートに問い合わせる ### 2Way モードで PIN が配信されない マスターユーザーコードとマスターユーザーパスワードが設定されているか確認してください。これらのフィールドが空の場合、PIN 配信は行われません。設定後は「保存」して「今すぐ同期」で確認してください。 ### 部屋マッピングのドロップダウンに部屋が表示されない 施設設定でアクティブな部屋が登録されていません。基本設定 → 部屋設定で部屋を追加し、有効化してください。 ### 「プロバイダーから部屋を取得」をクリックしても何も表示されない ねっぱん! 側に客室マスターデータが登録されていないか、認証情報に問題がある可能性があります。先に接続テストを実行して認証情報を確認してください。 ### 「同じアカウントが別の施設で有効化されています」エラーが出る 同一のねっぱん! アカウント（宿泊施設コード）は 1 施設にのみ接続できます。他の施設の連携設定を無効化または削除してから再試行してください。 --- ## よくある質問 ### Q: 1Way と 2Way の使い分けは？ A: 鍵 PIN をねっぱん! 側でも管理・通知したい場合は 2Way を選択します。UnlockOS のゲストチェックイン URL だけで運用する場合は 1Way で十分です。2Way にはマスター資格情報の設定が必要です。 ### Q: 複数の施設で別々のねっぱん! アカウントを使えますか？ A: はい。各施設ごとに独立した連携設定ができます。ただし、1 つのねっぱん! アカウント（宿泊施設コード）は 1 施設にのみ接続できます。 ### Q: ねっぱん! から取り込んだ予約と、UnlockOS で直接作成した予約の違いは？ A: ねっぱん! 経由でインポートされた予約は `integration_connection_id` が設定されており、予約の出所として識別できます。操作（変更・キャンセル等）は UnlockOS 上で行えます。 ### Q: ゲストフォームを OFF にしても問題ないですか？ A: 宿泊施設の法令では本人確認が義務付けられている場合があります。ゲストフォームを OFF にする前に、適用される法令・規約を確認してください。 ### Q: 同期は何分ごとに実行されますか？ A: バックグラウンドジョブは 5 分ごとに起動しますが、実際の同期頻度は施設ごとの `sync_interval_minutes`（デフォルト 15 分）に従います。つまり前回同期から 15 分以上経過している場合のみ同期が実行されます。 ### Q: 連携を削除した後、再設定は可能ですか？ A: はい、いつでも再設定できます。ただし部屋マッピングも削除されるため、再設定後に改めてマッピングを行う必要があります。 ### Q: ゲスト向けのチェックイン URL はどこで確認できますか？ A: 予約管理ダッシュボードの **チェックインタブ** で確認できます。ねっぱん! 連携が有効になるとそこに URL カードが表示されます。コピーボタンで URL をクリップボードにコピーしてゲストに共有してください。設定フォームの「チェックインタブで確認する」リンクからも移動できます。 --- ## 関連ページ - [外部連携](external-integrations.md) - [ロック接続](lock-connection.md) - [チェックイン設定](checkin-config-form.md) - [Googleカレンダー連携](google-calendar-integration.md)