需排班員工 · 03

員工離職

以開放式停權終止帳號使用權限，同時保留員工過往排班紀錄。

完成結果李美玲自 2026-10-31 00:00 起無法使用台北信義店 enrollment，歷史班表仍可查詢。

實際案例

HRIS 通知 S0002 李美玲的最後在職日為 2026-10-30。整合程式找到台北信義店的 enrollment，從隔日 00:00 起寫入無結束日的 terminated suspension。

資料流

1接收離職事件取得員工編號、所屬門市與最後在職日。HRIS event
2找到完整 enrollment以 merchantId 與 externalId 找到正確資料，避免停權到其他門市的綁定。GET /v1/enrollments
3換算停權時間最後在職日隔日 00:00（Asia/Taipei）換算為 UTC。timezone rule
4寫入離職停權使用 terminated，endTime 保持 null。PUT /v1/enrollment/{id}/suspension
5回讀驗證確認 enrollment 仍存在，且 suspension 起始時間與原因正確。GET /v1/enrollments

欄位 mapping

業務欄位	FREONE 欄位	本例值
員工編號	查詢 `externalId`	`S0002`
門市	查詢 `merchantId`	`tkfv5t`
停權起日	`startTime`	`2026-10-30T16:00:00Z`
停權結束	`endTime`	`null`，代表無期限
停權原因	`reason`	`terminated`

停權原因選項

reason 必須使用固定值，不是自由輸入文字。本例為離職，因此選 terminated；comment 欄位仍要隨 Request 傳入。

停權原因	英文名稱	`reason`	`comment`
離職	Terminated	`terminated`	可為空字串
借調	Secondment	`secondment`	可為空字串
留職停薪	UnpaidLeave	`unpaid-leave`	可為空字串
育嬰留停	ParentalLeave	`parental-leave`	可為空字串
其他	Other	`other`	必填具體原因，不可為空字串

Request

PUT /v1/enrollment/fb601791-54ea-4bc6-8a6b-ddb1fb1bd9b3/suspension
Content-Type: application/json

{
  "startTime": "2026-10-30T16:00:00Z",
  "endTime": null,
  "reason": "terminated",
  "comment": ""
}

Response

{
  "data": {
    "id": "fb601791-54ea-4bc6-8a6b-ddb1fb1bd9b3",
    "externalId": "S0002",
    "name": "李美玲",
    "alias": "美玲",
    "phone": "+886900000012",
    "parttime": false,
    "connected": true,
    "merchant": {
      "id": "tkfv5t",
      "name": "台北信義店"
    },
    "identityTag": {
      "id": "65107fa0-4284-46a5-82f7-b3657f660ed1",
      "name": "正職"
    },
    "skills": [],
    "createdTime": "2026-01-05T01:00:00Z",
    "updatedTime": "2026-10-20T03:00:00Z",
    "activatedTime": "2026-01-05T01:00:00Z",
    "activatedBy": {
      "id": "a9da86bb-e7a7-4779-a8e4-f61c40e72553",
      "name": "IT串接服務帳號"
    },
    "squads": [
      {
        "id": "sqmmhw5vonCzo",
        "name": "外場",
        "shiftSurveyEligible": true,
        "dayOffSurveyEligible": true
      }
    ],
    "suspension": {
      "startTime": "2026-10-30T16:00:00Z",
      "endTime": null,
      "reason": "terminated",
      "comment": "",
      "suspendedBy": {
        "id": "a9da86bb-e7a7-4779-a8e4-f61c40e72553",
        "name": "IT串接服務帳號"
      },
      "unsuspendedBy": null
    }
  }
}

驗收結果

原 enrollment ID 仍可查得，沒有移除歷史資料。
suspension.reason 是 terminated，且 endTime 為 null。
停權起點換算後是台北時間 2026-10-31 00:00。

關鍵提醒

離職請使用 suspension，不要刪除 enrollment。刪除會讓過往紀錄消失，只應留給確定是錯誤建檔的資料。

員工離職

實際案例​

資料流​

欄位 mapping​

停權原因選項​

Request​

Response​

驗收結果​