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. 施設と部屋を確かめる」へ進んでください。

https://beds24.com/join.html を開き、登録フォーム（Create your account）に入力します。
「I am a commercial or business user」にチェックを入れ、利用規約を確認して Join now を押します。
登録したメールアドレスにパスワードが届きます。初回ログインでは、メールで届くログインコードの入力も求められます。

Beds24 の登録フォーム

欄	入力する内容	補足
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 を使います。

左上の Settings（歯車）→ Properties を開きます。
施設がまだなければ Add New Property で作ります。施設を作ると部屋が 1 室（Room 1）自動で作られます。
Description タブの Property Id の数字を控えます。これがプロパティ ID です。

施設の編集画面。Property Id の値がプロパティ ID

Rooms タブで部屋の一覧を確かめます。ここに並ぶ部屋を、あとで UnlockOS の部屋と対応付けます。

部屋の一覧（Properties → Rooms）

1 つの連携で扱える施設は 1 つです。 Beds24 に複数の施設がある場合は、施設ごとに UnlockOS の連携を作ります。

3. 招待コードを発行する

Beds24 の API（API V2）を外部サービスにつなぐときは、まず 招待コード（invite code） を発行します。

左上の Settings（歯車）→ Marketplace → API を開きます（https://beds24.com/control3.php?pagetype=apiv2 を直接開いても同じ画面です）。
Generate invite code を押します。

API 画面。上から招待コード、リフレッシュトークン、長期トークンの一覧

権限（Scope）を選ぶ画面で、次の 5 か所にチェックを入れます。

scope	READ	WRITE	UnlockOS での用途
bookings	✓	✓	予約の取得。2Way では鍵とチェックイン URL を予約に書き込みます
bookings-personal	✓		ゲストの氏名・メール・電話の取得
bookings-financial	✓		予約金額の取得
properties	✓		施設と部屋の一覧の取得（部屋の対応付けに使います）

「Select which properties this token can access」は All owned by account のまま、IP 制限は空欄、名前は分かりやすいもの（例: UnlockOS）にして、右下の Generate invite code を押します。

招待コードの発行画面。5 か所にチェックを入れる

権限はあとから変えられません。 1Way だけで使う場合も、bookings の WRITE には最初からチェックを入れておいてください。あとで 2Way に切り替えるときに、招待コードの発行からやり直さずに済みます。

招待コードの有効期限は 24 時間です。 発行したら、その日のうちに次の「4. リフレッシュトークンに引き換える」まで済ませてください。

4. リフレッシュトークンに引き換える

UnlockOS に登録するのは、招待コードではなく リフレッシュトークン です。招待コードを Beds24 の API 画面（Swagger UI）で引き換えます。

https://beds24.com/api/v2/ を開きます。
Authentication の中の GET /authentication/setup を開き、Try it out を押します。
code 欄に招待コードを貼ります。deviceName は空欄でかまいません。
Execute を押し、Server response のコードが 200 であることを確かめます。
Response body に token・expiresIn・refreshToken の 3 項目が並びます。3 番目の refreshToken の値を、前後の引用符（"）を除いてコピーします。

Swagger UI の引き換え画面（入力前）

取り違えに注意してください。 1 番目の token は 24 時間で切れる一時的な鍵です。これを UnlockOS に入れると、翌日に接続が切れます。コピーするのは必ず refreshToken です。

引き換えが済むと、API 画面の Refresh Tokens に 1 行増えます。
リフレッシュトークンは 30 日間使われないと失効します。UnlockOS が定期的に同期している限り、失効しません。
招待コード・リフレッシュトークンは Beds24 アカウントへの実際のアクセス権です。チャットや共有文書に書き写さず、コピーしたら UnlockOS の入力欄に直接貼ってください。引き換えが終わったら、トークンが表示されたままのタブは閉じてください。

5. UnlockOS で接続する

左のメニューの アプリ連携 →「外部連携」タブで Beds24 のカードを開きます（未接続なら「接続」）。
次の項目を入力します。

項目	入力する内容
プロパティID	「2. 施設と部屋を確かめる」で控えた Property Id
同期モード	まずは 1Way（インポートのみ）
リフレッシュトークン	「4. リフレッシュトークンに引き換える」でコピーした値
チェックインの主体	UnlockOS でチェックインする（推奨）（新しい接続では最初から選ばれています）

保存を押してから 接続テスト を押します。「接続に成功しました」と出れば、認証は通っています。

UnlockOS の連携設定

保存すると、リフレッシュトークン欄は「（保存済み）」の表示になります。この欄を空のまま保存し直しても、保存済みの値は消えません。
チェックインの主体の 3 つの選択肢の違いは、外部連携の「チェックインの主体を選ぶ」を参照してください。

6. 部屋を対応付けて有効にする

接続テストの直後は、まだ予約は取り込まれません。部屋を対応付けてから有効にします。

画面下部の 部屋マッピング で プロバイダーから部屋を取得 を押します。Beds24 の部屋が一覧に並びます。
各行の UnlockOS部屋 で、対応する部屋を選びます。
マッピングを保存 を押します。

部屋マッピング（上）と同期ログ（下）

画面上部に戻り、有効（Enable automatic synchronization） をオンにして保存を押します。状態の表示が active に変わり、定期的な同期が始まります。

有効化のトグルと同期ステータス

部屋の対応付けは鍵を発行する条件です。 対応付けていない部屋の予約も取り込まれますが、鍵は発行されません。

7. 動作を確かめる

予約が取り込まれること

Beds24 の上部のカレンダーアイコンを押し、空いている日のマスを押します（右上の Add Booking でも同じです）。
部屋・日付・料金・ゲストの氏名を入力します。
フォーム最下部の Continue を押して予約を確定します。予約番号が採番されます。

予約フォームの下部。確定は右下の Continue

フォーム上部の Save では予約は作られません。 必ず最下部の Continue を押してください。

UnlockOS の連携設定画面で 今すぐ同期 を押します。同期ログ に reservation_pull が追加され、「作成: 1」と表示されれば取り込めています。取り込んだ予約は UnlockOS の予約管理のカレンダーにも表示されます。

鍵が書き戻されること（2Way）

UnlockOS の連携設定で 同期モード を 2Way（インポート + PIN送信） に変えて保存します。
Beds24 で新しい予約を作るか、既存の予約を編集して保存し、UnlockOS で 今すぐ同期 を押します。
Beds24 で予約を開き、Info タブを見ます。UnlockOS が書き込んだ次の 3 項目が並んでいれば成功です。

項目	内容
CHECKINURL	ゲストが UnlockOS でチェックインする URL（予約 ID とチェックイン・チェックアウト日を含みます）
QR	解錠用 QR コードの値
PIN	解錠番号

予約の Info タブ。CHECKINURL・QR・PIN が書き戻されている

チェックインの主体で「UnlockOS でチェックインする（URLのみ）」を選んでいる場合は CHECKINURL だけ、「連携先でチェックインする」を選んでいる場合は QR と PIN だけが書き戻されます。

8. Webhook を登録する（推奨）

Webhook を登録すると、Beds24 での予約の作成・変更・キャンセルが、定期同期を待たずにすぐ UnlockOS に届きます。

UnlockOS の連携設定画面の Webhook で URLを発行 を押し、表示された URL をコピーします。
Beds24 で Settings（歯車）→ Properties → Access を開き、Booking Webhook に URL を貼って保存します。
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 で予約を作ったのに取り込まれません