このガイドの目的

レシートローラーの従業員管理API（Staff API）を使って、ビジネスアカウント配下の従業員（スタッフ）を作成・取得・更新・削除する方法をまとめます。シフト管理アプリ、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 のみでもOK

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での変更がレシートローラー側にも反映されます（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

レシートローラー独自のフィールド（Squareにはない／同期されない）

• カナ名（firstNameKana, lastNameKana）
• 入社日、生年月日、住所
• 緊急連絡先（emergency.*）
• 雇用形態（FullTime / PartTime / Contract / Other）
• プロフィール写真
• 備考、社員番号、スマレジ連携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スコープ一覧と利用可否