Beds24 API で「7室が既定レート ¥20,000 固定」と誤診しないための読み方（連動価格の罠と固定化ツール）

この指示書が解く問題

Beds24 を PMS にして複数室の料金を「1室の価格に連動（price linking）」させている宿で、 料金カレンダー API を素直に叩くと 連動元以外の全室が同じ既定レート（例: ¥20,000）で一定 に見える。 これを「値付けが壊れている」「送信が止まっている」と誤診して調査を始める事故が起きる。 実際にはチャネル（Airbnb / Booking.com / Agoda / 直販）には連動値が正しく出ていて、見ていたのは 部屋に保存された既定レートでしかない。同じ罠は運用の中で2回踏まれた（1回目は記録していても、 2回目は「未解決の欠陥」として起票されてしまった）。

原因（API の仕様）

GET /inventory/rooms/calendar?roomId=<id>&startDate=…&endDate=…&includePrices=true は、 includeLinkedPrices=true を 付けないと連動で導出された実効価格を返さない。 返るのは各室の保存値で、連動先の部屋は既定レートが「from〜to の1本のレンジ」で返る （日次の振れが無い・price2 だけ入っている、が見分けのサイン）。 includeLinkedPrices=true を付けると、日ごとに price1〜price16 の実効値が返る。

さらに price1..price16 は「レート1〜16」ではなく priceRules の id 1〜16 に対応し、 どの番号がどのチャネルへ出るかは 部屋ごとに違う（連動元の部屋だけ Booking.com が id=3、他は id=2、など）。 番号を決め打ちで読むと、これも誤読の元になる。

手順（AI に読ませればそのまま実装できる粒度）

1. まず1室を「フラグ有り／無し」の両方で読んで見分ける

/inventory/rooms/calendar?roomId=<連動先の部屋>&startDate=<日>&endDate=<日+4>&includePrices=true
/inventory/rooms/calendar?roomId=<同じ部屋>&startDate=<日>&endDate=<日+4>&includePrices=true&includeLinkedPrices=true

• 無しで「1本のレンジ・price2 だけ・既定レート」／有りで「日次・複数スロット」なら、罠を踏んでいる。
• 有りの値が連動元の部屋の値 × 倍率（例: Booking.com だけ ×1.2）と一致すれば、値付けは正常。

2. ゲスト側の実表示で裏を取る（API だけで結論を出さない）

• 直販ページ booking2.php?propid=<物件>&roomid=<部屋>&checkin=<日>&numnight=2 の合計額を読む （ヘッドレスブラウザで開いて本文を抽出し、スクショも自分で目視する）。
• OTA 側は同じ日付・同じ人数で1つ以上開き、既定レートが出ていないことを確認する。
• 送信窓（自動配信が書いている先の日数、例: 84日）の 外側の日付 も1窓読む。窓外は既定レートが 残りやすい領域なので、ここも連動値なら完全にシロ。

3. 読み取り専用ツールに固定化して、二度と手で単発クエリを書かない

作るもの（1ファイル＋テスト1ファイル、書き込み API は一切呼ばない）:

• priceRules を1回取得（/properties?id=<物件>&includeAllRooms=true&includePriceRules=true。 このフラグが無いと priceRules キーごと返らない）→ 部屋ごとに スロット番号 → チャネル を解く純関数 slotChannels(roomType)（channels.<name>.enable === true と bookingPage.direct === true を集める。 priceLinking.roomId / priceId / offsetMultiplier から roomX.priceY xZ の文字列も残す）。
• カレンダーは 常に includeLinkedPrices=true で取り、レンジを日ごとに展開する純関数 expandCalendar(ranges)（to 省略時は from の1日。日付計算は UTC 固定）。
• --compare-stored を付けた時だけフラグ無しでも取り、日ごとに「保存値」を併記。保存値が全日 既定レートで一定なら 「保存値は既定レートで一定（不活性・チャネルには出ない）」と1行出す 純関数 isFlatDefault(storedByDay, 既定レート)。
• 人間向け出力は「日付 / airbnb / booking / agoda / direct / [stored]」の固定列。末尾に必ず 「実効価格は includeLinkedPrices=true で取得。保存値とは別物」と1行出す。
• exit code: 0=正常 / 1=API 失敗 / 2=引数不正。429 のときだけ 5秒×回数で最大3回再試行。
• テストは純関数3つをフィクスチャで検定（ネットワークに出ない）。API 呼び出しは main() 内で 動的 import して、テストが認証情報に依存しないようにする。

4. 記録の直し方

• 起票済みの「未解決」を 「解決・欠陥ではない・再着手しない」に書き換える（消さない）。
• 罠の記録は「API 仕様の説明」だけでなく 「この道具で読む」という1コマンド まで書く。 説明だけだと次の人は自分で単発クエリを書いて同じ罠を踏む。

実装を委譲するときの注意

• 仕様はファイルで渡す（argv にバッククォートや $( を含めない）。
• 生成物は自分で node --test と実 API の1室スモークを回し、grep "fetch(\|writeFileSync\|method:" で 書き込み系の混入が無いことを確認してから置く。
• 「調査で分かった数値」は仕様書の冒頭コメントに残させる（例: 直販ページの実額）。次に疑った人が コードの先頭で答えに当たる。

期待できる効果

• 「既定レートで固定」の誤診をゼロにする（2回の再発 → ツール1本で読む運用に置換）。
• 監視の設計判断が速くなる: 連動元の1室だけをスナップショットしていても、全室連動なら設計どおりと 即答できる（連動ルール自体の変更だけは別途 priceRules を見る）。