跳至主要内容

需排班員工 · 01

新增員工

把 HR 新進資料轉成正確門市、組別、身份別、技能與啟用日的 FREONE 組員。

完成結果王小明會從 2026-09-25 起成為台北信義店外場組可排班的員工，並以 S0001 與 HRIS 對應。

實際案例​

王小明是一位新人正職，預計 2026-10-01 報到，但門市希望從 2026-09-25 起先將他列入班表。HRIS 同時提供「清潔」技能與等級 3。整合程式先解析門市、組別及標籤的 FREONE ID，再建立 enrollment。

HRIS 來源資料範例值FREONE 用途
員工編號S0001externalId，供後續同步與回讀
姓名／暱稱王小明／小明name、alias
聯絡電話+886900000011phone
正職／兼職正職parttime: false
門市台北信義店解析為 tkfv5t
組別外場解析為 sqmmhw5vonCzo
身份別正職解析為身份別 UUID
技能／等級清潔／3解析技能標籤 UUID，組成選填的 skills
報到日／提前排班日2026-10-01／2026-09-25activatedTime 使用較早的排班日

資料流​

  1. 1接收新進事件取得員工編號、姓名、電話、正兼職、門市、組別與預計報到日。HRIS event
  2. 2解析門市與組別由可存取的 Squad 找到台北信義店外場組及其 Merchant。GET /v1/squads
  3. 3解析身份別取得台北信義店可用的正職 identityTagId。GET /v1/identity-tags/{merchantId}
  4. 4解析技能標籤取得台北信義店可用的清潔技能 tagId，保留 HRIS 的等級 3。GET /v1/skill-tags/{merchantId}
  5. 5決定問卷資格分別決定是否開放給班意願與休假意願；兩者可同時開啟。business rule
  6. 6決定啟用時間為了提前排班，使用 2026-09-25 00:00（Asia/Taipei）。business rule
  7. 7建立並回讀建立 enrollment，並以 externalId 確認門市、組別、問卷資格與啟用日。POST /v1/enrollments/{merchantId}

欄位 mapping​

FREONE 欄位本例值決定方式
Path merchantIdtkfv5t由門市名稱對應 Squad 所屬 Merchant
phone+886900000011沿用 HRIS 的員工電話
name王小明沿用 HRIS 的員工姓名
alias小明沿用 HRIS 的暱稱
externalIdS0001沿用 HRIS 員工編號
parttimefalse依正職／兼職填入：正職為 false，兼職為 true
identityTagId65107fa0-4284-46a5-82f7-b3657f660ed1由「正職」查得
skills[0].tagId4f2b126d-eccf-44aa-b98a-dd2ac1879d12由台北信義店可用的「清潔」技能標籤查得
skills[0].level3沿用 HRIS 技能等級，須為 1–5 的整數
squads[0].squadIdsqmmhw5vonCzo由台北信義店＋外場查得
squads[0].shiftSurveyEligibletrue是否開放給班意願；通常供兼職報班／給班使用
squads[0].dayOffSurveyEligibletrue是否開放休假意願；通常供正職畫休使用
activatedTime2026-09-24T16:00:00Z台北時間 2026-09-25 00:00

兩種問卷資格是獨立設定，可以複選。本例的正職員工兩者都設為 true，表示同時開放給班與休假意願；實際串接時應依門市的問卷規則決定，不必因 parttime: false 就關閉給班意願。

skills 是選填欄位。若 HRIS 沒有技能資料，可省略；若有資料，先從技能標籤端點取得目標商家的 tagId。

Request​

POST /v1/enrollments/tkfv5t
Content-Type: application/json

{
  "phone": "+886900000011",
  "name": "王小明",
  "alias": "小明",
  "parttime": false,
  "externalId": "S0001",
  "activatedTime": "2026-09-24T16:00:00Z",
  "identityTagId": "65107fa0-4284-46a5-82f7-b3657f660ed1",
  "skills": [
    {"tagId": "4f2b126d-eccf-44aa-b98a-dd2ac1879d12", "level": 3}
  ],
  "squads": [
    {
      "squadId": "sqmmhw5vonCzo",
      "shiftSurveyEligible": true,
      "dayOffSurveyEligible": true
    }
  ]
}

Response​

{
  "data": {
    "id": "a571cbd6-8795-4ccd-924b-63097c77314c",
    "externalId": "S0001",
    "name": "王小明",
    "alias": "小明",
    "phone": "+886900000011",
    "parttime": false,
    "connected": true,
    "merchant": {
      "id": "tkfv5t",
      "name": "台北信義店"
    },
    "identityTag": {
      "id": "65107fa0-4284-46a5-82f7-b3657f660ed1",
      "name": "正職"
    },
    "skills": [
      {"tagId": "4f2b126d-eccf-44aa-b98a-dd2ac1879d12", "level": 3}
    ],
    "createdTime": "2026-09-15T02:00:00Z",
    "updatedTime": "2026-09-15T02:00:00Z",
    "activatedTime": "2026-09-24T16:00:00Z",
    "activatedBy": {
      "id": "a9da86bb-e7a7-4779-a8e4-f61c40e72553",
      "name": "IT串接服務帳號"
    },
    "squads": [
      {
        "id": "sqmmhw5vonCzo",
        "name": "外場",
        "shiftSurveyEligible": true,
        "dayOffSurveyEligible": true
      }
    ],
    "suspension": null
  }
}

驗收結果​

  • 以 merchantId=tkfv5t、externalId=S0001 回讀時只有一筆 enrollment。
  • 回應中的 Squad 是 sqmmhw5vonCzo，身份別是正職，且 parttime 為 false。
  • skills 包含清潔技能的 tagId，等級為 3。
  • 該 Squad 的給班意願與休假意願資格皆為 true，沒有因正職身份自動關閉其中一項。
  • activatedTime 對應台北時間 2026-09-25 00:00，而不是報到日或 API 呼叫日。
關鍵提醒

未傳 activatedTime 時會使用呼叫 API 的當下；若要提前排班，必須明確傳入預計開始出現在班表的日期。若查不到身份別，請先到 FREONE 後台新增並完成休假／排班規則設定；若查不到技能標籤，請先確認目標商家已設定該技能，再重跑整合。