# Beds24 API v2 で予約を「漏れなく」取る — 黙って欠ける3つの罠と回避策 対象: Beds24（チャネルマネージャ / PMS）の API v2 を Node.js などから叩いて、空室・稼働・在庫の穴を集計している人。 症状: API は成功（HTTP 200）を返すのに、予約が一部欠けて「予約なしの閉室」「空室」に見える。ダブルブッキング寸前まで行った実例あり。 ## 罠1: `/bookings` の `arrivalFrom` / `arrivalTo` は「到着日」で絞る - 調べたい期間の開始日を `arrivalFrom` にすると、**それ以前に到着して滞在中のゲストが1件も返らない**。 - 在庫カレンダーの「閉」と突き合わせると、滞在中の部屋が「予約なしの閉室＝開け忘れ候補」に見える。開放したらダブルブッキング。 - 回避: `arrivalFrom = 期間開始日 − 45日`（最長滞在より長く）で取り、取った後に期間でフィルタする。 ```js 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 なら欠落を疑う。 ```js 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 分程度で、欠落ゼロの取得コードになる。 ---