班表資料

依組別與日期範圍查詢班表，並區分預排資訊與最終核實資訊。

使用端點

GET /v1/shifts/{squadId}?from=2026-09-01&to=2026-09-07

參數	必填	說明
squadId	是	可存取的組別 ID
from	否	起始日期，包含當日；預設為今天
to	否	結束日期，包含當日；需與 from 一起使用，預設等於 from

• 不帶 from 與 to：查詢今天。
• 只帶 from：查詢 from 指定的當天。
• 同時帶 from 與 to：查詢包含起訖日在內的日期範圍。
• 請勿只帶 to。

班表模型

每筆班表包含組員、組別、商家、班表日期與建立／更新資訊。排班內容分成：

• planned：預排資訊。
• actual：最終資訊。

多數情況下 actual 會等於 planned。若兩者不同，代表當日或過去班表曾進行核實異動，可能同時出現工時差異與核實留言；actual 並不是打卡出勤資料。

核實回覆

latestAdjustmentConfirmation 只包含 state 與 comment：

state	介面文字	意義	comment
replied	發問	No with comment，組員對核實內容提出問題	必須有值
acknowledged	確認	Yes without comment，組員確認核實內容	空字串

沒有核實回覆時，latestAdjustmentConfirmation 為 null。

休假與班的組合

不要只用 dayOff 判斷當天是否有工作；應同時讀取 leaveType、duties[] 與 leaves[]。

情境	dayOff	leaveType	duties[]	leaves[]
純休假	true	有值	空陣列	通常為空陣列
有班＋部分休假	false	null	有值	有值，包含休假時段與假別
休假日加班	true	有值	有值，代表加班班表	通常為空陣列

部分休假的假別在 leaves[].leaveType，時段則在 leaves[].slot。休假日加班仍保留整日的 leaveType，工作內容則由 duties[] 表示。

建議流程

1. 先以 GET /v1/squads 取得 squadId 與該組別所屬的商家 ID。
2. 以 GET /v1/merchants 取得該商家的 timezone。
3. 依實際同步區間帶入 from 與 to。
4. 以商家的 timezone 解讀班表日期。
5. 以班表 id 作為同步識別，並保留 updatedTime 供後續比對。

回應物件的完整欄位請參考 Query accessible shifts。