營業時間 API（Business Hours API）的使用方式

API OAuth 營業時間 Business Hours 特別營業日可營業時間排班 Android iOS

關於本指南
本文彙整 ReceiptRoller 營業時間 API（/api/v1/stores/{storeId}/business-hours）的使用方式。可從行動應用程式或外部系統，取得、更新每個星期的營業時間、特別營業日（臨時歇業、營業時間變更），以及作為排班建立上限的可營業時間。

營業時間 API（Business Hours API）的使用方式

必要的權限範圍

權限範圍	授予的權限
`store.business-hours.read`	營業時間、特別營業日、可營業時間、營業中判定的參照
`store.business-hours.write`	營業時間、特別營業日、可營業時間的更新

請在應用程式編輯畫面的「API 權限範圍」勾選後，將其含入授權 URL 的 scope 參數中。

驗證

與其他 v1 API 採相同的權杖規範。

綁定於商業帳戶的權杖 — 可直接呼叫
使用者範圍的權杖（適用於原生行動應用程式）— 請在查詢加上 ?organizationId=

端點一覽

方法	路徑	內容
GET	`/api/v1/stores/{storeId}/business-hours`	取得每個星期的營業時間
PUT	`/api/v1/stores/{storeId}/business-hours`	營業時間的整批更新
PUT	`/api/v1/stores/{storeId}/business-hours/{dayOfWeek}/{shiftIndex}`	特定星期、時段的更新
DELETE	`/api/v1/stores/{storeId}/business-hours/{dayOfWeek}/{shiftIndex}`	特定星期、時段的刪除
GET	`/api/v1/stores/{storeId}/business-hours/special-days`	特別營業日（臨時歇業、營業時間變更）的一覽
PUT	`/api/v1/stores/{storeId}/business-hours/special-days/{date}`	特別營業日的登錄、更新
DELETE	`/api/v1/stores/{storeId}/business-hours/special-days/{date}`	特別營業日的刪除
GET	`/api/v1/stores/{storeId}/business-hours/work-hours-limit`	可營業時間（作為排班建立上限的業務時間）的取得
PUT	`/api/v1/stores/{storeId}/business-hours/work-hours-limit`	可營業時間的更新
GET	`/api/v1/stores/{storeId}/business-hours/open-status`	目前是否營業中的判定

營業時間與可營業時間的差異

營業時間 — 對顧客公開的開店、關店時間。每個星期可登錄多個時段（午間營業、夜間營業等）
可營業時間 — 作為可建立排班的時間上限的業務時間。可設定為包含開店前的準備與關店後的收拾在內的範圍

排班管理功能與排班建立 API，只能在可營業時間的範圍內登錄排班。

可營業時間的設定

PUT /api/v1/stores/{storeId}/business-hours/work-hours-limit
Authorization: Bearer {token}
Content-Type: application/json

{
  "standardWorkStartTime": "08:00",
  "standardWorkEndTime": "23:00"
}

時刻以 HH:mm 格式指定，且開始必須早於結束。若兩者皆設為空字串，則變為無限制（可登錄 24 小時排班）。

特別營業日的登錄

PUT /api/v1/stores/{storeId}/business-hours/special-days/2026-08-13
Authorization: Bearer {token}
Content-Type: application/json

{
  "isClosed": true,
  "note": "夏季休業"
}

除臨時歇業外，也可登錄只變更特定日期營業時間的內容。open-status 的判定會優先評估特別營業日。

營業時間 API（Business Hours API）的使用方式

營業時間 API（Business Hours API）的使用方式

必要的權限範圍

驗證

端點一覽

營業時間與可營業時間的差異

可營業時間的設定

特別營業日的登錄

相關指南