員工管理 API（Staff API）的使用方式

本指南的目的

本文彙整使用 ReceiptRoller 的員工管理 API（Staff API），建立、取得、更新、刪除商業帳戶底下員工（Staff）的方法。這是在處理員工資料時的入口指南，適用於排班管理應用程式、依 POS 員工分開的營業額應用程式、人事系統串接等。

前提

• 已透過 OAuth 2.0 授權碼流程取得存取權杖
• 應用程式的權限範圍中包含 store.staff.read（讀取）／store.staff.write（建立、更新、刪除）
• 已得知商業帳戶 ID（UUID）（取得商業帳戶、店鋪、POS 端末的一覽）
• 基底 URL: https://receiptroller.io

端點一覽

1. 取得員工一覽

GET /api/v1/staff?organizationId={organizationId}
Authorization: Bearer {access_token}

查詢參數（皆為選填，AND 結合）

• storeId — 僅該店鋪所配屬的員工（也包含全店鋪配屬的員工）
• position — 以職稱篩選（完全一致）
• employmentType — FullTime / PartTime / Contract / Other
• status — Active / Inactive / Pending
• search — 以姓名（含假名）、員工編號、參照 ID 進行部分搜尋
• includeDeleted — 是否包含已刪除（預設 false）

回應範例

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "staff": [
    {
      "id": "stf-001",
      "organizationId": "a04507de-...",
      "employeeNumber": "E-0001",
      "referenceId": "TM_xyz",
      "userId": "",
      "name": {
        "first": "太郎",
        "last": "田中",
        "firstKana": "タロウ",
        "lastKana": "タナカ",
        "display": "田中 太郎"
      },
      "role": {
        "position": "店長",
        "employmentType": "FullTime",
        "isOwner": false
      },
      "status": "Active",
      "contact": { "phone": "090-1234-5678", "email": "tanaka@example.com" },
      "hr": { "hireDate": "2024-04-01T00:00:00Z", "dateOfBirth": "1990-05-15T00:00:00Z", "address": "東京都渋谷区..." },
      "pay": {
        "hourlyRate": 1800,
        "isOvertimeExempt": true,
        "tipEligible": true,
        "jobs": [
          {
            "jobTitle": "店長",
            "payType": "HOURLY",
            "hourlyRate": 1800,
            "annualRate": 0,
            "weeklyHours": 40,
            "locationIds": ["store-A"]
          },
          {
            "jobTitle": "レジ",
            "payType": "HOURLY",
            "hourlyRate": 1200,
            "annualRate": 0,
            "weeklyHours": 10,
            "locationIds": ["store-B"]
          }
        ]
      },
      "assignments": {
        "storeIds": ["store-A", "store-B"],
        "allLocations": false
      },
      "emergency": { "name": "田中花子", "phone": "090-...", "relation": "配偶者" },
      "integrations": { "squareTeamMemberId": "TM_xyz", "smaregiStaffId": "" },
      "profileImageUrl": "https://...",
      "notes": "",
      "createdAt": "2024-04-01T09:00:00Z",
      "updatedAt": "2026-06-02T10:30:00Z"
    }
  ],
  "totalCount": 1
}

2. 取得 1 名的詳細

GET /api/v1/staff/{staffId}?organizationId={organizationId}
Authorization: Bearer {access_token}

若員工不屬於指定的商業帳戶，則回傳 404。

3. 新增建立

POST /api/v1/staff?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "displayName": "佐藤 花子",
  "firstName": "花子",
  "lastName": "佐藤",
  "firstNameKana": "ハナコ",
  "lastNameKana": "サトウ",
  "employeeNumber": "E-0002",
  "position": "レジ担当",
  "employmentType": "PartTime",
  "status": "Active",
  "phone": "080-9876-5432",
  "email": "sato@example.com",
  "hourlyRate": 1200,
  "hireDate": "2026-06-01",
  "isOvertimeExempt": false,
  "tipEligible": true,
  "assignedStoreIds": "store-001,store-002",
  "isAssignedToAllLocations": false,
  "jobAssignmentsJson": "[{\"jobTitle\":\"レジ\",\"payType\":\"HOURLY\",\"hourlyRate\":1200,\"weeklyHours\":20,\"locationIds\":[\"store-001\"]}]"
}

重點

• displayName 或 firstName + lastName 其中之一為必填
• 即使在請求本文包含 organizationId 也會被忽略。一定會使用以權杖／查詢解析出的商業帳戶
• 若有多個工作，請在 jobAssignmentsJson 傳入陣列。若只有單一工作，僅 position + hourlyRate 也可以

4. 更新

PUT /api/v1/staff/{staffId}?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "displayName": "佐藤 花子",
  "phone": "080-9876-5432",
  "hourlyRate": 1300,
  "status": "Active"
}

會以送出的欄位覆寫（非部分更新，而是完全置換）。想保留值的欄位請將既有值一併重新送出。

5. 刪除（軟刪除）

DELETE /api/v1/staff/{staffId}?organizationId={organizationId}
Authorization: Bearer {access_token}

重點

• 回應為 204 No Content
• 由於是軟刪除，仍可從過去的排班日誌或 POS 交易解析出對應的員工 ID
• 已刪除員工不會包含在一覽、搜尋結果中

與 Square Team Member 的對應

本 API 的欄位與 Square Team Members API 具互通性。在 Square 串接啟用的商業帳戶中，integrations.squareTeamMemberId 會自動設定，Square 端的變更也會反映至 ReceiptRoller 端（預定於 Phase 3, t-e9a2f482 實作）。

Square 來源的欄位

• referenceId ⇔ Square reference_id
• role.isOwner ⇔ Square is_owner
• status ⇔ Square status（ACTIVE → "Active" / INACTIVE → "Inactive"）
• assignments.allLocations ⇔ Square assignment_type: ALL
• pay.jobs ⇔ Square wage_setting.job_assignments
• pay.isOvertimeExempt ⇔ Square is_overtime_exempt
• pay.tipEligible ⇔ Square tip_eligible

ReceiptRoller 獨有的欄位（Square 沒有／不同步）

• 假名（firstNameKana, lastNameKana）
• 入職日、出生年月日、地址
• 緊急聯絡人（emergency.*）
• 雇用型態（FullTime / PartTime / Contract / Other）
• 個人檔案照片
• 備註、員工編號、Smaregi 串接 ID

典型的流程（行動應用程式）

1. 以 OAuth 取得存取權杖 → 權限範圍包含 store.staff.read 與 store.staff.write
2. 以 GET /api/v1/me/organizations 選擇商業帳戶
3. 在員工一覽畫面以 GET /api/v1/staff?storeId=... 分頁顯示
4. 新增時 POST /api/v1/staff
5. 編輯畫面 GET /api/v1/staff/{id} → PUT /api/v1/staff/{id}
6. 離職處理 DELETE /api/v1/staff/{id}（或以 status: "Inactive" PUT）

錯誤回應

相關資訊

• 取得商業帳戶、店鋪、POS 端末的一覽
• 商品管理 API（Products API）的使用方式
• 銷售管理 API（Orders / OMS API）的使用方式
• 營業額實績 API（Sales API）的使用方式
• OAuth 權限範圍一覽與可用與否