在庫・リソース・予約分析API の使い方

予約そのものの操作は 予約管理API をご覧ください。

予約在庫（Stock）

客室・マシン・区画など、日単位または泊単位で貸し出すものを扱います。在庫種別が「何を貸すか」を表し、そこから生成される日ごとの在庫が「いつ貸せるか」を表します。

POST /api/v1/reservations/stock/types
Authorization: Bearer {token}
Content-Type: application/json

{
  "storeId": "store-001",
  "name": "スタンダードルーム",
  "kind": "Night",
  "quantity": 8,
  "maxOccupancy": 2,
  "basePrice": 12000
}

kind は泊単位なら Night、日単位なら Day です。quantity は同じものが何室・何台あるか、maxOccupancy は1つあたり何名まで入れるかを表します。

turnaroundDays を指定すると、予約の後に次の貸し出しまで空ける日数を確保できます。清掃や整備が必要な場合に使用してください。

在庫の生成と予約可能期間

在庫種別を作っただけでは予約できません。generate で日ごとの在庫を作って初めて予約を受けられます。すでに在庫のある日はそのまま残るため、繰り返し実行しても問題ありません。

horizon は在庫のある最終日を返します。この日を過ぎた日付は予約できません。在庫の生成を止めたまま日が経つと、予約可能期間が今日に近づき、やがて予約を受け付けられなくなります。エラーにはならず、画面上も壊れて見えないため、この機能でもっとも起きやすい不具合です。

定期的に horizon を確認し、近づいてきたら生成する運用をおすすめします。在庫が一度も生成されていない場合は null を返します。

リソース（Resources）

予約を割り当てられる席とスタッフを取得します。参照のみです。席の配置は店舗レイアウトで管理されており、予約連携のためのAPIから間取りを編集できるようにするのは別の話になるためです。

staff/availability が返すのはシフト上の勤務時間であって、空き時間ではありません。返された時間帯にすでに予約が入っていることもあります。実際に予約できる時刻を知りたい場合は、予約管理APIの menus/{menuId}/availability を使ってください。

予約分析（Analytics）

期間を指定した集計です。予約管理APIの stats が1か月分を返すのに対し、こちらは任意の期間とリピーターの状況を返します。

GET /api/v1/reservations/analytics
  ?storeId=store-001&fromDate=2026-08-01&toDate=2026-08-31
Authorization: Bearer {token}

{
  "totalBookings": 240,
  "completed": 198,
  "cancelled": 24,
  "noShow": 6,
  "upcoming": 12,
  "revenue": 1680000,
  "uniqueCustomers": 143,
  "repeatCustomers": 61,
  "repeatRate": 0.4265
}

repeatRate は期間内に2回以上ご予約いただいたお客様の割合です。予約が1件もない期間では null を返します。revenue は予約時の価格の合計で、通貨の主単位です。

fromDate と toDate は必須です。省略した場合や期間が逆転している場合は 400 を返します。

OpenAPI定義

リクエスト・レスポンスの詳細は APIリファレンス と /openapi/v1.json をご覧ください。

関連ガイド

• 予約管理API（Reservations API）の使い方
• 通い放題プラン・回数券API の使い方
• 定期予約・出欠・キャンセル待ちAPI の使い方