Beds24 API v2 で予約を「漏れなく」取る — 黙って欠ける3つの罠と回避策

対象: Beds24（チャネルマネージャ / PMS）の API v2 を Node.js などから叩いて、空室・稼働・在庫の穴を集計している人。 症状: API は成功（HTTP 200）を返すのに、予約が一部欠けて「予約なしの閉室」「空室」に見える。ダブルブッキング寸前まで行った実例あり。

罠1: /bookings の arrivalFrom / arrivalTo は「到着日」で絞る

• 調べたい期間の開始日を arrivalFrom にすると、それ以前に到着して滞在中のゲストが1件も返らない。
• 在庫カレンダーの「閉」と突き合わせると、滞在中の部屋が「予約なしの閉室＝開け忘れ候補」に見える。開放したらダブルブッキング。
• 回避: arrivalFrom = 期間開始日 − 45日（最長滞在より長く）で取り、取った後に期間でフィルタする。

const LOOKBACK_DAYS = 45;
const arrivalFrom = addDays(from, -LOOKBACK_DAYS);
const bookings = await beds24Get('/bookings', { propertyId, arrivalFrom, arrivalTo: to });
// その後 b.arrival < to && b.departure > from で期間に当てる

罠2: /bookings は 100 件でページングされ、超過分は黙って欠ける

• propertyId だけで広い期間を取ると 100 件で切れ、応答の pages.nextPageExists: true が立つだけ。エラーにはならない。
• 隣接予約の有無を判定する処理で、後ろの部屋の予約が丸ごと消えた実例あり。
• 回避: nextPageExists が false になるまで page=1,2,... を回す。または roomId で部屋ごとに取る。件数がちょうど 100 なら欠落を疑う。

async function getAllBookings(params) {
  const out = [];
  for (let page = 1; ; page++) {
    const r = await beds24Get('/bookings', { ...params, page });
    out.push(...(r.data || []));
    if (!r.pages?.nextPageExists) return out;
  }
}

罠3: /properties の応答は長いと途中で切れる（offset 継ぎ足し）

• includeAllRooms=true&includeTexts=all で全部屋のテキストを含めると応答が約 45,000 字で切れ、後半の部屋が読めず「空」に見える。
• includeTexts=true や言語コードはエラーにならず無視される。有効なのは all だけ。
• 回避: offset を渡し、nextOffset が null になるまで継ぎ足す。応答長が付けない時と同じなら無視されている。

検証の型（ツールを2本以上で突き合わせる）

• 稼働集計ツールと在庫の穴ツールの数字が合わなければ、まずコードより先に取得窓（arrivalFrom・page・offset・--to の窓端）を疑う。
• 「予約なしの閉室」を報告する前に、同じ期間を Beds24 管理画面のカレンダーと突き合わせる。
• 在庫を開ける提案は、その部屋のその日に滞在中ゲストがいないことを予約 ID 付きで示してから。

期待効果

ゼロから調査すると API 仕様の読み違いで半日〜1日。この指示書を読ませれば予約取得の実装は 30 分程度で、欠落ゼロの取得コードになる。