予約管理API（Reservations API）の使い方

予約まわりのAPIは機能ごとにガイドを分けています。このページは予約そのものと予約枠を扱います。通い放題プランや回数券、定期予約、出欠管理などは末尾の「関連ガイド」からご覧ください。

必要なスコープ

アプリ編集画面の「APIスコープ」でチェックを入れたうえで、認可URLの scope パラメータに含めてください。

認証

他のv1 APIと同じトークン規約です。

• ビジネスアカウントに紐付いたトークン — そのまま呼び出せます
• ユーザースコープのトークン（ネイティブモバイルアプリ向け） — クエリに ?organizationId= を付与してください

エンドポイント一覧

いずれも storeId をクエリまたはボディで指定します。

予約の作成

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

{
  "storeId": "store-001",
  "customerName": "山田 太郎",
  "customerPhone": "090-0000-0000",
  "partySize": 4,
  "slotId": "slot-xxxx",
  "note": "窓際の席を希望"
}

API経由で作成した予約は bookingSource が API として記録されます（リクエストで明示的に指定した場合はその値が優先されます）。

所要時間が変わるメニューの予約

カットとカラーのように所要時間が異なるメニューを扱う店舗では、先に GET /api/v1/reservations/menus/{menuId}/availability で開始時刻の候補を取得してください。所要時間に足りる連続した枠だけが返るため、60分のメニューを30分枠ひとつに入れてしまう取り違えが起きません。

返却された候補には primarySlotId と joinedSlotIds が含まれます。予約作成時は前者を slotId、後者を joinedSlotIds として送ると、必要な枠がまとめて押さえられます。

ステータスの更新

PUT /api/v1/reservations/{reservationId} のボディで status を変更すると、Web管理画面と同じステータス遷移処理が実行されます。予約枠の残席計算や確認・キャンセル通知も管理画面での操作と同じように動作します。

指定できるステータス：

• Pending（承認待ち）
• Confirmed（確定）
• Completed（来店済み）
• Cancelled（キャンセル）
• NoShow（無断キャンセル）

予約枠の一括生成

POST /api/v1/reservations/slots/generate は、店舗の予約設定（枠の長さ・営業時間・定休日）にもとづいて指定期間の予約枠をまとめて生成します。

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

{
  "storeId": "store-001",
  "from": "2026-08-15",
  "to": "2026-08-21",
  "perResource": true
}

perResource を true にすると、店舗レイアウトに登録された予約可能な席（テーブル・個室・カウンター）ごとに予約枠が生成されます。席単位での予約受付を行う場合に使用してください。

席（テーブル）情報の取得

GET /api/v1/reservations/tables?storeId= は、店舗レイアウトに登録された予約可能なリソースを返します。

{
  "items": [
    { "id": "table-01", "name": "テーブル1", "type": "table", "typeDisplayName": "テーブル", "capacity": 4 },
    { "id": "room-01",  "name": "個室A",     "type": "room",  "typeDisplayName": "個室",     "capacity": 8 }
  ]
}

ここで返る id は、予約枠や予約の assignedResource にそのまま指定できます。席レイアウト自体の編集はWeb管理画面のレイアウトエディタで行ってください。

OpenAPI定義

全エンドポイントの定義は /openapi/v1.json で公開しています。APIリファレンス と同じ内容で、AndroidやiOSのクライアント生成にそのまま利用できます。

関連ガイド

• 通い放題プラン・回数券API の使い方
• 定期予約・出欠・キャンセル待ちAPI の使い方
• 在庫・リソース・予約分析API の使い方
• API認証ガイド（OAuth 2.0 認可コードフロー）
• OAuthスコープ一覧と利用可否
• 営業時間API（Business Hours API）の使い方