# Beds24 連携 ヘルプ ## 概要 宿泊管理サービス **Beds24** の予約を UnlockOS に取り込み、予約ごとに鍵（解錠番号・QR）とチェックイン URL を発行する連携です。Booking.com・Airbnb・Expedia などの予約も、Beds24 にまとまっていればそのまま取り込めます。 このページでは、Beds24 側の準備から UnlockOS の設定、動作の確認、運用の注意までを順に説明します。作業は **Beds24 側 → UnlockOS 側 → 動作確認** の順に進めてください。 ### できること | 同期モード | 内容 | |---|---| | **1Way（インポートのみ）** | Beds24 の予約を UnlockOS に取り込みます。鍵とチェックイン URL は UnlockOS 側でだけ使います | | **2Way（インポート + PIN送信）** | 取り込みに加えて、発行した鍵とチェックイン URL を Beds24 の予約に書き戻します。Beds24 のメッセージ機能などからゲストに案内できます | まず 1Way で取り込みを確かめ、そのあと 2Way に切り替える進め方をおすすめします。 ### 必要なもの - Beds24 のアカウント（試用アカウントでも接続できます） - UnlockOS に登録済みの部屋と、その部屋の鍵（KEYVOX などのスマートロック） - UnlockOS の管理画面で「アプリ連携」を開ける権限 --- ## 1. Beds24 のアカウントを作る すでに Beds24 を使っている場合は、次の「2. 施設と部屋を確かめる」へ進んでください。 1. `https://beds24.com/join.html` を開き、登録フォーム（Create your account）に入力します。 2. 「I am a commercial or business user」にチェックを入れ、利用規約を確認して **Join now** を押します。 3. 登録したメールアドレスにパスワードが届きます。初回ログインでは、メールで届くログインコードの入力も求められます。  | 欄 | 入力する内容 | 補足 | |---|---|---| | Business name | 施設名や事業者名 | あとから変更できます | | Property type | 施設の種類（Hotel など） | | | Number of properties | 施設の数 | | | Location | Japan | タイムゾーンが日本時間になります | | First name / Last name | 担当者の氏名（ローマ字） | | | Email address | 受信できる業務用アドレス | パスワードとログインコードが届きます | | Phone | 連絡先の電話番号 | | | Create a username | 任意のログイン ID | | | Language | English | 管理画面は英語かドイツ語です | | Referrer code | 空欄 | | 初回ログイン後に事業者情報（Please complete your business details）の入力を求められます。住所を入力して保存してください。言語設定や案内画面は既定のまま閉じてかまいません。 --- ## 2. 施設と部屋を確かめる UnlockOS の設定では、Beds24 の **プロパティ ID** を使います。 1. 左上の Settings（歯車）→ **Properties** を開きます。 2. 施設がまだなければ **Add New Property** で作ります。施設を作ると部屋が 1 室（Room 1）自動で作られます。 3. **Description** タブの **Property Id** の数字を控えます。これがプロパティ ID です。  4. **Rooms** タブで部屋の一覧を確かめます。ここに並ぶ部屋を、あとで UnlockOS の部屋と対応付けます。  **1 つの連携で扱える施設は 1 つです。** Beds24 に複数の施設がある場合は、施設ごとに UnlockOS の連携を作ります。 --- ## 3. 招待コードを発行する Beds24 の API（API V2）を外部サービスにつなぐときは、まず **招待コード（invite code）** を発行します。 1. 左上の Settings（歯車）→ **Marketplace** → **API** を開きます（`https://beds24.com/control3.php?pagetype=apiv2` を直接開いても同じ画面です）。 2. **Generate invite code** を押します。  3. 権限（Scope）を選ぶ画面で、次の 5 か所にチェックを入れます。 | scope | READ | WRITE | UnlockOS での用途 | |---|---|---|---| | bookings | ✓ | ✓ | 予約の取得。2Way では鍵とチェックイン URL を予約に書き込みます | | bookings-personal | ✓ | | ゲストの氏名・メール・電話の取得 | | bookings-financial | ✓ | | 予約金額の取得 | | properties | ✓ | | 施設と部屋の一覧の取得（部屋の対応付けに使います） | 4. 「Select which properties this token can access」は **All owned by account** のまま、IP 制限は空欄、名前は分かりやすいもの（例: `UnlockOS`）にして、右下の **Generate invite code** を押します。  **権限はあとから変えられません。** 1Way だけで使う場合も、bookings の WRITE には最初からチェックを入れておいてください。あとで 2Way に切り替えるときに、招待コードの発行からやり直さずに済みます。 **招待コードの有効期限は 24 時間です。** 発行したら、その日のうちに次の「4. リフレッシュトークンに引き換える」まで済ませてください。 --- ## 4. リフレッシュトークンに引き換える UnlockOS に登録するのは、招待コードではなく **リフレッシュトークン** です。招待コードを Beds24 の API 画面（Swagger UI）で引き換えます。 1. `https://beds24.com/api/v2/` を開きます。 2. **Authentication** の中の **GET /authentication/setup** を開き、**Try it out** を押します。 3. **code** 欄に招待コードを貼ります。**deviceName** は空欄でかまいません。 4. **Execute** を押し、Server response のコードが **200** であることを確かめます。 5. Response body に `token`・`expiresIn`・`refreshToken` の 3 項目が並びます。**3 番目の `refreshToken`** の値を、前後の引用符（"）を除いてコピーします。  **取り違えに注意してください。** 1 番目の `token` は 24 時間で切れる一時的な鍵です。これを UnlockOS に入れると、翌日に接続が切れます。コピーするのは必ず `refreshToken` です。 - 引き換えが済むと、API 画面の **Refresh Tokens** に 1 行増えます。 - リフレッシュトークンは **30 日間使われないと失効します**。UnlockOS が定期的に同期している限り、失効しません。 - 招待コード・リフレッシュトークンは Beds24 アカウントへの実際のアクセス権です。チャットや共有文書に書き写さず、コピーしたら UnlockOS の入力欄に直接貼ってください。引き換えが終わったら、トークンが表示されたままのタブは閉じてください。 --- ## 5. UnlockOS で接続する 1. 左のメニューの **アプリ連携** →「外部連携」タブで **Beds24** のカードを開きます（未接続なら「接続」）。 2. 次の項目を入力します。 | 項目 | 入力する内容 | |---|---| | プロパティID | 「2. 施設と部屋を確かめる」で控えた Property Id | | 同期モード | まずは **1Way（インポートのみ）** | | リフレッシュトークン | 「4. リフレッシュトークンに引き換える」でコピーした値 | | チェックインの主体 | **UnlockOS でチェックインする（推奨）**（新しい接続では最初から選ばれています） | 3. **保存** を押してから **接続テスト** を押します。「接続に成功しました」と出れば、認証は通っています。  - 保存すると、リフレッシュトークン欄は「（保存済み）」の表示になります。この欄を空のまま保存し直しても、保存済みの値は消えません。 - チェックインの主体の 3 つの選択肢の違いは、[外部連携](external-integrations.md)の「チェックインの主体を選ぶ」を参照してください。 --- ## 6. 部屋を対応付けて有効にする 接続テストの直後は、まだ予約は取り込まれません。部屋を対応付けてから有効にします。 1. 画面下部の **部屋マッピング** で **プロバイダーから部屋を取得** を押します。Beds24 の部屋が一覧に並びます。 2. 各行の **UnlockOS部屋** で、対応する部屋を選びます。 3. **マッピングを保存** を押します。  4. 画面上部に戻り、**有効（Enable automatic synchronization）** をオンにして **保存** を押します。状態の表示が `active` に変わり、定期的な同期が始まります。  **部屋の対応付けは鍵を発行する条件です。** 対応付けていない部屋の予約も取り込まれますが、鍵は発行されません。 --- ## 7. 動作を確かめる ### 予約が取り込まれること 1. Beds24 の上部のカレンダーアイコンを押し、空いている日のマスを押します（右上の **Add Booking** でも同じです）。 2. 部屋・日付・料金・ゲストの氏名を入力します。 3. **フォーム最下部の Continue** を押して予約を確定します。予約番号が採番されます。  **フォーム上部の Save では予約は作られません。** 必ず最下部の **Continue** を押してください。 4. UnlockOS の連携設定画面で **今すぐ同期** を押します。**同期ログ** に `reservation_pull` が追加され、「作成: 1」と表示されれば取り込めています。取り込んだ予約は UnlockOS の予約管理のカレンダーにも表示されます。  ### 鍵が書き戻されること（2Way） 1. UnlockOS の連携設定で **同期モード** を **2Way（インポート + PIN送信）** に変えて保存します。 2. Beds24 で新しい予約を作るか、既存の予約を編集して保存し、UnlockOS で **今すぐ同期** を押します。 3. Beds24 で予約を開き、**Info** タブを見ます。UnlockOS が書き込んだ次の 3 項目が並んでいれば成功です。 | 項目 | 内容 | |---|---| | CHECKINURL | ゲストが UnlockOS でチェックインする URL（予約 ID とチェックイン・チェックアウト日を含みます） | | QR | 解錠用 QR コードの値 | | PIN | 解錠番号 |  チェックインの主体で「UnlockOS でチェックインする（URLのみ）」を選んでいる場合は CHECKINURL だけ、「連携先でチェックインする」を選んでいる場合は QR と PIN だけが書き戻されます。 --- ## 8. Webhook を登録する（推奨） Webhook を登録すると、Beds24 での予約の作成・変更・キャンセルが、定期同期を待たずにすぐ UnlockOS に届きます。 1. UnlockOS の連携設定画面の **Webhook** で **URLを発行** を押し、表示された URL をコピーします。 2. Beds24 で Settings（歯車）→ **Properties** → **Access** を開き、**Booking Webhook** に URL を貼って保存します。 3. Beds24 で予約を 1 件変更し、UnlockOS の Webhook の **最終受信** が更新されることを確かめます。 - 登録しなくても定期同期で取り込まれます。反映が同期の間隔ぶん遅れるだけです。 - **URLを再発行すると、古い URL はすぐに使えなくなります。** 再発行したら Beds24 の登録も貼り替えてください。 - Webhook の URL は、それ自体が合言葉を含む秘密の URL です。第三者に共有しないでください。 --- ## 運用で知っておくこと ### 同期のタイミング - 定期同期はおよそ **15 分ごと**です。Webhook を登録していれば、変更はほぼすぐに届きます。 - 急ぐときは連携設定画面の **今すぐ同期** を押してください。 - UnlockOS は **前回の同期のあとに変更された予約だけ** を Beds24 から取り込みます。そのため、1Way で取り込んだ予約は、**2Way に切り替えただけでは鍵が書き戻されません。** 既存の予約に書き戻したいときは、Beds24 で予約を開いて何か 1 項目（Reference 欄など）を変えて保存し、次の同期を待ってください。 ### チェックイン・チェックアウトの時刻は Beds24 が正 取り込んだ予約の時刻は、Beds24 の内容で決まります。 | 時刻 | 決まり方 | |---|---| | チェックイン（利用開始） | Beds24 の予約の **Arrival Time**。空欄なら UnlockOS の **フロントデスク → デフォルト時間設定** のチェックイン時間 | | チェックアウト（利用終了） | 常に UnlockOS の **フロントデスク → デフォルト時間設定** のチェックアウト時間（Beds24 にはチェックアウト時刻の欄がありません） | - アーリーチェックインは、Beds24 の予約の **Arrival Time** に時刻を入れてください。 - UnlockOS の予約編集で時刻を変えることもできますが、**Beds24 側で予約が編集されるたびに Beds24 の内容で上書きされます**（Arrival Time 以外の項目の編集でも上書きされます）。レイトチェックアウトも同様で、Beds24 で予約が編集されるとデフォルトのチェックアウト時間に戻ります。 - 時刻を確実に残したい予約は、Beds24 側をあとから編集しないか、編集した直後に UnlockOS 側で直してください。 ### チェックイン後に Beds24 で予約を変えた場合 延泊・人数変更・部屋替えなど、チェックイン後に Beds24 で予約を変えても、UnlockOS の予約は **チェックイン中のまま** です。日程や部屋の変更は反映され、鍵もそれに合わせて追従します。チェックアウトもそのまま行えます。 ### Beds24 で予約をキャンセルした場合 - UnlockOS の予約もキャンセルされ、鍵は失効します。 - ゲストが **まだ滞在中（チェックイン中）** の場合は、滞在が終わるまでキャンセルを保留します（部屋が空室扱いになって、次の予約が入るのを防ぐため）。 - **完了した滞在**は、あとから Beds24 でキャンセルしても「完了」のまま残ります。 ### 二重予約に注意 Beds24 は、UnlockOS の予約管理で直接作った予約を知りません。そのため、同じ部屋・同じ日を Beds24 側（や、Beds24 につながった OTA）で売ってしまうことがあります。 - 重なった Beds24 の予約は **UnlockOS に取り込まれません**。チェックイン URL の検索にも出ず、鍵も発行されません。 - 取り込めなかったことは、今のところ連携設定画面の **同期ログ** にしか表示されません。 - Beds24 と連携している部屋の予約は、**Beds24 側でだけ受ける** 運用をおすすめします。UnlockOS で直接予約を入れる場合は、Beds24 側でもその日程を売り止めにしてください。 ### ゲスト名の表示とチェックイン URL での検索 - UnlockOS では、Beds24 の予約のゲスト名が **「姓 名」の順**（例: `Johnson Emily`）で表示されます。 - ゲストがチェックイン URL で予約を名前で検索するときは、姓と名の順番・空白の有無・全角の空白の違いがあっても見つかります（例: 「佐藤 美咲」の予約は「美咲 佐藤」「佐藤美咲」でも見つかります）。 - 名前の一部だけでも見つかりますが、1 文字だけでは検索できません。短い時間に何度も検索を外すと、しばらく検索できなくなります。 --- ## よくある質問 ### Q: 接続テストで「接続に失敗しました」と出ます A: 次を確かめてください。 - リフレッシュトークン欄に入れたのが `refreshToken` の値か（`token` ではないか、前後の引用符が残っていないか） - プロパティ ID が Beds24 の **Property Id** と一致しているか - 招待コードの権限に bookings と properties の READ が入っているか 入れ直すときは、Beds24 の API 画面で招待コードを発行し直し、引き換えからやり直してください。 ### Q: 翌日になったら接続が切れました A: リフレッシュトークンの代わりに、24 時間で切れる `token` の値を入れている可能性があります。「4. リフレッシュトークンに引き換える」の手順で `refreshToken` を入れ直してください。 ### Q: Beds24 で予約を作ったのに取り込まれません A: 次を確かめてください。 - Beds24 の予約フォームで **最下部の Continue** を押したか（上部の Save では予約は作られません）。Beds24 のカレンダーに予約が表示されていれば作られています - 連携の **有効** がオンになっているか - 同じ部屋・同じ日に UnlockOS 側の予約がないか（重なっていると取り込まれません。同期ログを確認してください） ### Q: 予約は取り込まれたのに、鍵が発行されません A: その予約の部屋が **部屋マッピング** で UnlockOS の部屋に対応付けられているかを確かめてください。対応付けていない部屋の予約には鍵が発行されません。 ### Q: 2Way にしたのに、Beds24 に鍵が書き戻されません A: 2Way に切り替える前に取り込んだ予約には、自動では書き戻されません。Beds24 で予約を編集して保存すると、次の同期で書き戻されます。新しく作った予約は、取り込まれた時点で書き戻されます。 ### Q: Beds24 の予約編集画面に保存ボタンが見当たりません A: 既存の予約の編集画面では、**Save** と **Save and leave open** が右上にあります。ブラウザの幅が狭いと画面の外に出て見えないことがあるので、ウィンドウを広げるか横にスクロールしてください。保存したら、カレンダーや Detail タブで反映を確かめてください。 ### Q: UnlockOS で変えたチェックイン時刻が元に戻りました A: 取り込んだ予約の時刻は Beds24 が正です。Beds24 側で予約が編集されると、Beds24 の内容で上書きされます。「運用で知っておくこと」の「チェックイン・チェックアウトの時刻は Beds24 が正」を参照してください。 --- ## 関連ページ - [外部連携](external-integrations.md) - [予約作成・編集](reservation.md)