組員資料
以 enrollment 管理商家的組員資料、組別歸屬、身份別、技能與停權狀態。
可用操作
| Method | Path | 用途 |
|---|---|---|
GET | /v1/enrollments | 查詢 Service Account 可管理的組員 |
POST | /v1/enrollments/{merchantId} | 在指定商家建立組員 |
PUT | /v1/enrollment/{enrollmentId}/profile | 替換組員基本資料 |
PUT | /v1/enrollment/{enrollmentId}/squads | 完整更新組別歸屬與問卷開放設定 |
PUT | /v1/enrollment/{enrollmentId}/suspension | 建立或修改停權期間 |
查詢組員
GET /v1/enrollments 可使用 merchantId、phone 或 externalId 查找組員。同時帶入多個條件時，只會回傳全部條件都符合的資料；例如同時帶入 merchantId 與 phone，必須是指定商家內電話相符的組員才會出現。
停權原因
PUT /v1/enrollment/{enrollmentId}/suspension 的 reason 不是自由輸入文字，請依停權目的使用下列固定值：
| 業務情境 | 英文名稱 | reason |
|---|---|---|
| 離職 | Terminated | terminated |
| 借調 | Secondment | secondment |
| 留職停薪 | UnpaidLeave | unpaid-leave |
| 育嬰留停 | ParentalLeave | parental-leave |
| 其他 | Other | other |
使用 other 時，comment 必須填寫具體原因，不可傳送空字串。其他原因的 comment 仍應依 API request schema 傳入，但可留空字串。
例如，員工自 2026-10-15 起育嬰留停，並於 2026-11-01 復職：
PUT /v1/enrollment/{enrollmentId}/suspension
Content-Type: application/json
{
"startTime": "2026-10-14T16:00:00Z",
"endTime": "2026-10-31T16:00:00Z",
"reason": "parental-leave",
"comment": ""
}
startTime 是停權開始時間；endTime 是停止停權、恢復使用權限的時間。上例以 Merchant 所在的 Asia/Taipei 時區換算，因此員工於台北時間 2026-11-01 00:00 起復職。
建立與更新
建立組員至少需要 phone、name、alias 與 parttime。parttime 為布林值：true 代表兼職，false 代表非兼職。可另外帶入外部系統識別 externalId、啟用時間、身份別、初始組別及 skills。每筆技能指派包含技能標籤的 tagId 與 1–5 的整數 level；建立時省略、傳 null 或空陣列都表示沒有技能。先依商家查詢可用的身份別與技能標籤，再使用對應 ID。
修改基本資料使用 PUT /v1/enrollment/{enrollmentId}/profile，須送出 name、alias、phone、parttime、externalId、identityTagId。externalId 可用空字串清除。這支 API 也會替換技能指派；若省略 skills、傳 null 或空陣列，既有技能會全部清除。完整操作請參考修改員工資料範例。
當組員的 connected: true 時，表示該手機號碼已在小橘 App 綁定登入，無法修改。更新 profile 時，phone 須沿用現有值；若要更換手機號碼，請使用新增員工流程，以新號碼建立組員。
PUT 不支援只傳送想修改的欄位。更新 profile 前，請先查詢組員現有資料，修改指定欄位後，把其餘必填欄位與要保留的 skills 完整送回；profile 更新不包含組別或停權欄位。
更新 squads 時，本次送出的組別清單會取代原有清單；未帶入的原有組別會被移除。每個組別都要帶入 squadId、shiftSurveyEligible 與 dayOffSurveyEligible。shiftSurveyEligible 表示是否開放該組員的排班問卷，dayOffSurveyEligible 表示是否開放休假問卷。請先保留現有設定，再修改需要調整的值。
更新前，請確認目標商家在 Service Account 的授權範圍內；若 API 回傳 403，代表目前憑證無法執行該操作。
完整 request／response schema 請參考 Enrollment API。