預約管理 API（Reservations 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（若在請求中明確指定，則以該值為優先）。

狀態的更新

在 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-06-15",
  "to": "2026-06-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 管理畫面的版面編輯器進行。

相關指南

• API 驗證指南（OAuth 2.0 授權碼流程）
• OAuth 權限範圍一覽與可用與否
• 營業時間 API（Business Hours API）的使用方式
• 員工管理 API（Staff API）的使用方式