Beds24 API連携の落とし穴：v1とv2の違い・放置30日で切れるトークン
Beds24のAPI連携を新しく作るなら、v2だけを使い、v1とは混ぜないでください。連携が急に止まったら、まず「使わずに30日たってrefresh tokenが失効していないか」と「5分あたりの利用上限に当たっていないか」を確かめます。予約や料金を壊さないためには、「HTTP 200でも本文のエラーを見る」「泊数の数え方を確かめる」「書き込みは止めるスイッチを付けて、最初は通知だけで動かす」の3点を、自作でも外注でも必ず守ります。以下、私たちが自社施設の運営でBeds24のv1とv2を動かして確かめたことを、発注や点検にそのまま使える形でまとめます。
Beds24のAPIでできること・向かないこと
APIを使うと、管理画面を開かずに予約や料金をプログラムから読み書きできます。宿の運営でよく使うのは次のような用途です。
- 予約一覧の自動取得: 新しい予約やキャンセルを定期的に取り、スプレッドシートや清掃の段取りに流す
- 通知の自作: チェックイン前日の予約をまとめて、スタッフのチャットに送る
- 料金や在庫の自動更新: 空き状況や日付に応じて料金を調整する（動的料金）
一方で、利用上限はアカウント単位で決まっていて、既定では5分あたり100クレジットです（詳しくは後述）。ゲストがページを開くたび、ボタンを押すたびにBeds24へ問い合わせる作りは、すぐ上限に当たります。判断基準は次のとおりです。
| 使い方 | 向き・不向き |
|---|---|
| 数分〜数時間おきにまとめて取得し、手元に保存して使う | 向いている |
| 1日1回、翌日分の予約を集計して通知する | 向いている |
| ゲストの操作のたびにBeds24へ問い合わせる | 向かない |
| 同じアカウントで複数の連携を別々に動かす | 上限を分け合うので、合計の使用量を見積もる |
v1かv2か、トークンの寿命
比較表
| v1（旧JSON API） | v2 | |
|---|---|---|
| 接続先 | https://api.beds24.com/json |
https://api.beds24.com/v2 |
| 認証の置き場所 | リクエスト本文の authentication（apiKey と propKey） |
ヘッダ token |
| 鍵の種類 | APIキー | 招待コード → refresh token → access token（読み取りだけなら long life token） |
| 公式の扱い | 非推奨。新しい用途には勧めていない | 多くの場合に推奨 |
| ドキュメント | JSON API | Swagger |
公式は、v1が非推奨であること、v1とv2を混ぜて使わないことを明記しています（Beds24 Wiki: API）。
私たちのところでは、連携ごとにv1とv2が並行して動いている状態になりました。認証の置き場所も鍵の種類も違うので、手を入れるたびに「いま触っているのはどちらの連携で、どちらの鍵か」を確かめる必要があります。この手間は、連携が増えるほど重くなります。だから結論は、新しく作るならv2だけ。既存のv1は、作り直す機会にv2へ寄せるです。
v2の始め方
- 管理画面の (SETTINGS) MARKETPLACE > API で招待コードを作る
- このときスコープ（権限）を必要な分だけに絞る。予約を読むだけの連携に、料金を書き換える権限は付けない
- 接続元が決まっているなら、IPアドレスの許可リストも設定する（カンマ区切りで複数可）
- 招待コードからrefresh tokenを作る（招待コードは24時間で切れるので、作ったらすぐ使う）
- refresh tokenからaccess tokenを作り、リクエストのたびにヘッダで送る
トークンの寿命
| 鍵 | 寿命 | 用途 |
|---|---|---|
| 招待コード | 24時間 | refresh tokenを作るための一時的なもの |
| refresh token | 使い続ける限り有効。使わずに30日たつと失効 | access tokenを作る元 |
| access token | 24時間 | 実際のリクエストに使う |
| long life token | 読み取り専用。使わずに90日たつと失効 | 予約を見るだけの連携 |
予約一覧の取得や通知のように「見るだけ」の連携なら、long life tokenを選ぶと書き込みの事故が起きる余地そのものが無くなります。料金や在庫を書き換える連携だけ、refresh tokenを使う形に分けるのが安全です。
「急に動かなくなった」ときに見る所
点検チェックリスト
- [ ] 30日以上、連携を止めていなかったか: refresh tokenは使わずに30日たつと失効します。オフシーズンに止めていた自動化、しばらく放置していた通知の仕組みを再開したときは、まずここを疑います。招待コードを作り直し、トークンを取り直せば戻ります
- [ ] 利用上限に当たっていないか: 応答ヘッダ
x-five-min-limit-remainingが0近くになっていないか、上限超過の応答（429）が出ていないかを見ます - [ ] 401（認証エラー）が続いていないか: access tokenは24時間で切れます。私たちの連携では、401が返ったらトークンを作り直して1回だけ再試行する作りにしています。何度も繰り返す作りにすると、原因がトークン以外にあるときに呼び続けて上限を削ります
利用上限はクレジット制
v2の利用上限は「回数」ではなくクレジットで数えます（Beds24 Wiki: API V2）。
- 上限はアカウント単位で、既定は5分あたり100クレジット
- 1回のリクエストのコストは、内容の複雑さで変わる。「5分で何回まで」とは言い切れない
- 月10€で5分あたり200クレジットに増やせる
- 応答ヘッダで状況が分かる
| ヘッダ | 分かること |
|---|---|
x-request-cost |
そのリクエストで使ったクレジット |
x-five-min-limit-remaining |
残りのクレジット |
x-five-min-limit-resets-in |
枠が戻るまでの秒数 |
私たちの連携では、リクエストのたびに1回のコストと残量を記録しています。記録があれば、どの処理が枠を食っているかが後から分かり、増枠が要るのか作りを直すべきかを判断できます。上限に当たったら、x-five-min-limit-resets-in が示す秒数だけ待ってから再開します。
予約や料金を壊さないための注意点
v1を使い続けている人がハマる所
v1で動いている連携を点検するときは、次の表を上から確かめてください。
| 罠 | 何が起きるか | どう避けるか |
|---|---|---|
lastNight はチェックアウト日の前日 |
チェックアウト日をそのまま入れると1泊多く登録される | 「最後に泊まる夜」を入れる。登録後に管理画面で泊数を見比べる |
| 日付の書き方が2種類 | 登録の firstNight/lastNight はハイフン付き（2014-10-01）、検索の arrivalFrom などはハイフン無し（20141001）。取り違えると絞り込みが効かない |
用途ごとに書式を分けて扱う |
| HTTP 200でも本文にエラー | 「成功」と判定されたのに登録されていない | 応答本文にエラーが入っていないかを必ず見る |
| 認証をヘッダに入れても素通り | エラーにならず200が返るのに、認証が効いていない | 認証は本文の authentication に入れる |
| 1件と複数件で形が変わる | 1件は本文の直下、複数件は array にまとめる（最大100件） |
件数で送り方を切り替える |
| ゲスト名の項目名が予約によって揺れる | 通知やスプレッドシートで名前が空欄になる | 名前の項目を1つに決め打ちせず、複数の候補を順に見る |
lastNight・HTTP 200のエラー・認証の素通りは、公式の説明ページからは読み取りにくく、私たちが実際に動かして確認した挙動です。とくに lastNight は、清掃や料金の計算まで1泊ずれて伝わるので、最初に確かめる項目です。
v1の予約の status は番号で返ります（getBookings）。
| 番号 | 意味 |
|---|---|
| 0 | キャンセル |
| 1 | 確定 |
| 2 | 新規 |
| 3 | リクエスト |
| 4 | ブラック |
| 5 | 問い合わせ |
「確定」だけを数えるつもりで0（キャンセル）を含めてしまうと、埋まっていない日を埋まっていると判断します。集計や通知の条件に、どの番号を含めるかを明記してください。
参考: setBooking
予約の取りこぼしを防ぐ
- ページ送りをする: v2の予約一覧は1ページ約100件です。
pageパラメータと、応答に入る次ページへのリンクで続きを取ります。1ページ目だけで終わる作りだと、予約が増えた時期に黙って取りこぼします（Beds24 Wiki: API V2）。v1のgetBookingsも1回の取得は最大1000件です - 在庫カレンダーの終了日はその日の泊まりを含む: v2の在庫カレンダーの
endDateは宿泊日で数え、指定した日の夜も範囲に入ります。私たちが確認した挙動です。チェックアウト日を入れると、1泊分余計に読み書きします
料金や在庫を書き換える前に
判断基準は「まず通知だけで動かし、止めるスイッチを付けてから書き込む」です。
私たちの動的料金の仕組みには書き込みを有効にするスイッチがあり、既定では料金を書き換えずに「この日をいくらにする案です」と通知するだけです。書き込みの経路を新しく足すときも、同じくスイッチで囲みます。スイッチの無い書き込みは足しません。
この順番にしておけば、計算の誤り（泊数のずれ、キャンセルの数え間違い）は通知の段階で人の目に触れます。書き込みを始めたあとも、おかしいと思ったらスイッチ1つで止められます。
外注・自作する前の確認リスト
外注先に渡すか、自分で作る前に上から確かめてください。
- [ ] v2だけで作るか。v1と混ぜていないか
- [ ] スコープは必要最小限か。見るだけの連携なら読み取り専用のlong life tokenにしているか
- [ ] IPアドレスの許可リストを設定しているか
- [ ] 使わずに30日で失効する対策があるか。止めていた連携を再開する手順が決まっているか
- [ ] 401のとき、トークンを作り直して1回だけ再試行する作りか
- [ ] 利用量を記録しているか。1回のコストと残量をログに残し、上限に当たったら指定の秒数だけ待つか
- [ ] HTTP 200でも本文のエラーを見て成否を判定しているか
- [ ] ページ送りで予約を最後まで取っているか
- [ ] 泊数の数え方（v1の
lastNight、在庫カレンダーのendDate）を実際の予約で確かめたか - [ ] statusのどの番号を含めるか、ゲスト名をどの項目から取るかが決まっているか
- [ ] 書き込みを止めるスイッチがあり、既定が「通知だけ」になっているか
このうち1つでも「分からない」と返ってきたら、本番の予約や料金につなぐ前に確かめてもらってください。
ご相談について
NNiNNでは、自社施設で動かしてきたBeds24連携の経験をもとに、連携の設計や、既存の連携の点検をお手伝いしています。「作った連携が急に止まった」「外注先の設計がこのままで大丈夫か見てほしい」といったご相談は、事業サポートをご覧のうえ、お問い合わせからお気軽にどうぞ。
