需排班員工 · 04

員工留停與復職

以有起訖日期的停權區間表達留職停薪、育嬰留停與預定復職。

完成結果陳怡君於 2026-10-15 起暫停使用，並在 2026-11-01 00:00 自動恢復 enrollment 權限。

實際案例

S0003 陳怡君申請 2026-10-15 起育嬰留停，預定 2026-11-01 復職。整合程式使用 inclusive startTime 與 exclusive endTime 表達完整區間。

資料流

1接收留停區間取得員工編號、門市、留停原因、開始日與預定復職日。HRIS event
2找到完整 enrollment使用 merchantId＋externalId 找到正確 enrollment。GET /v1/enrollments
3換算起訖時間將台北時間兩個日期的 00:00 換算成 UTC。timezone rule
4寫入留停區間使用 parental-leave，endTime 設為復職日的開始。PUT /v1/enrollment/{id}/suspension
5回讀驗證確認停權原因、起訖時間與預定復職日。GET /v1/enrollments

欄位 mapping

業務欄位	FREONE 欄位	本例值
留停開始	`startTime`（包含）	`2026-10-14T16:00:00Z`
預定復職	`endTime`（不包含）	`2026-10-31T16:00:00Z`
留停類型	`reason`	`parental-leave`
說明	`comment`	`育嬰留停，預計 11/01 復職`

停權原因選項

reason 必須使用固定值，不是自由輸入文字。本例為育嬰留停，因此選 parental-leave；一般留職停薪則選 unpaid-leave。comment 欄位仍要隨 Request 傳入。

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

Request

PUT /v1/enrollment/fb601791-54ea-dfhi-8a6b-ddb1fb1mozjd/suspension
Content-Type: application/json

{
  "startTime": "2026-10-14T16:00:00Z",
  "endTime": "2026-10-31T16:00:00Z",
  "reason": "parental-leave",
  "comment": "育嬰留停，預計 11/01 復職"
}

Response

{
  "data": {
    "id": "fb601791-54ea-dfhi-8a6b-ddb1fb1mozjd",
    "externalId": "S0003",
    "name": "陳怡君",
    "alias": "怡君",
    "phone": "+886900000013",
    "parttime": false,
    "connected": true,
    "merchant": {
      "id": "tkfv5t",
      "name": "台北信義店"
    },
    "identityTag": {
      "id": "65107fa0-4284-46a5-82f7-b3657f660ed1",
      "name": "正職"
    },
    "skills": [],
    "createdTime": "2026-02-01T01:00:00Z",
    "updatedTime": "2026-10-01T05:00:00Z",
    "activatedTime": "2026-02-01T01:00:00Z",
    "activatedBy": {
      "id": "a9da86bb-e7a7-4779-a8e4-f61c40e72553",
      "name": "IT串接服務帳號"
    },
    "squads": [
      {
        "id": "sqmmhw5vonCzo",
        "name": "外場",
        "shiftSurveyEligible": true,
        "dayOffSurveyEligible": true
      }
    ],
    "suspension": {
      "startTime": "2026-10-14T16:00:00Z",
      "endTime": "2026-10-31T16:00:00Z",
      "reason": "parental-leave",
      "comment": "育嬰留停，預計 11/01 復職",
      "suspendedBy": {
        "id": "0dab2cd6-702a-4e94-876d-4a91c514a76e",
        "name": "林小米店長"
      },
      "unsuspendedBy": null
    }
  }
}

驗收結果

2026-10-15 00:00 起 enrollment 處於停權區間。
2026-11-01 00:00 起離開停權區間，可再次使用。
原 enrollment、組別與歷史排班資料皆保留。

離職與留停的差異

離職與長期留停都使用 suspension。離職通常以 terminated 搭配沒有復職時間的 endTime: null；有預定復職日的留停則選對應原因，並把 endTime 設為復職日開始。

員工留停與復職

實際案例​

資料流​

欄位 mapping​

停權原因選項​

Request​

Response​

驗收結果​