วิธีใช้ Staff API

วัตถุประสงค์ของคู่มือนี้

รวบรวมวิธีสร้าง・ดึง・อัปเดต・ลบพนักงาน (สตาฟฟ์) ภายใต้บัญชีธุรกิจ โดยใช้ Staff API ของ ReceiptRoller คู่มือนี้เป็นจุดเริ่มต้นเมื่อจัดการข้อมูลพนักงาน เช่น แอปจัดการกะ แอปยอดขายแยกตามสตาฟฟ์ POS หรือการเชื่อมต่อระบบ HR

เงื่อนไขเบื้องต้น

• ต้องได้แอกเซสโทเคนจาก OAuth 2.0 Authorization Code Flow แล้ว
• สโคปของแอปต้องรวม store.staff.read (อ่าน)／store.staff.write (สร้าง・อัปเดต・ลบ)
• ต้องทราบ ID ของบัญชีธุรกิจ (UUID) (การดึงรายการบัญชีธุรกิจ・ร้านค้า・เครื่อง POS)
• Base 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 — ค้นหาบางส่วนด้วยชื่อ (รวมคานะ)・รหัสพนักงาน・reference 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. ดึงรายละเอียด…