スマレジスタッフデータとレシートローラースタッフデータのマッピング

スマレジスタッフ POS連携データマッピング

スマレジのスタッフマスタは、レシートローラー連携後、レシートローラーのスタッフデータ（StaffDto） に自動的に変換されて取り込まれます。本記事では、フィールド単位の対応関係と、スマレジ固有のクセをまとめます。

同期の使い方はスタッフ画面の右上メニューから「スマレジと同期」をクリックします。詳細はスマレジの POS 連携設定をご覧ください。

フィールド対応表

スマレジ `/pos/staffs`	レシートローラー（`StaffDto`）	備考
`staffId`	`SmaregiStaffId`	スマレジ内部 ID。再同期時の照合キー。
`staffCode`	`EmployeeNumber`	社員番号として保存。
`staffName`	`LastName` + `FirstName` + `DisplayName`	空白で姓・名に分割（「下田昌平」→ LastName=下田 / FirstName=昌平）。空白が無い場合は LastName に全文、FirstName は空。DisplayName には元の文字列をそのまま保存。
`email`	`Email`	空のときは RR 側の既存値を保持。
`displayFlag`	`IsActive`	`"0"`（非表示）は同期対象外。`"1"` は `IsActive = true`。

取り込まれない項目

スマレジ /pos/staffs エンドポイントの仕様上、以下の RR 側フィールドには対応するデータが存在しません。RR 側で別途登録してください。再同期で上書きされることはありません。

電話番号（Phone）
生年月日（DateOfBirth）
入社日（HireDate）
雇用形態（EmploymentType）— 正社員・パート・契約など
時給（HourlyRate）
住所・緊急連絡先
役職名（Position）— スマレジは roleId を返しますが、役職名の解決には別エンドポイントが必要なため、現バージョンでは未対応
所属店舗（AssignedStoreIds）— スマレジ /pos/staffs は店舗アサインを返さない
カナ氏名（LastNameKana / FirstNameKana）— StaffDto に該当フィールドが無いため。staffNameKana は将来追加時に活用予定

マッチングと新規登録

スマレジからスタッフが取り込まれる際、既存スタッフとの照合は SmaregiStaffId の完全一致のみで行われます。一致しなければ新規スタッフとして登録されます。氏名や社員番号での自動マージは行いません。

同期のタイミング

スマレジ → RR：スタッフ画面右上メニューの「スマレジと同期」ボタンで手動実行。/pos/staffs から全スタッフを取得し、SmaregiStaffId で照合して新規追加・更新します。
再同期時の挙動：既存スタッフ（同じ SmaregiStaffId）は EmployeeNumber / LastName / FirstName / DisplayName / Email / IsActive が上書きされます。RR 側で追加した HourlyRate / HireDate / EmploymentType / Position / AssignedStoreIds / 緊急連絡先などは保持されます。
RR → スマレジ：現バージョンでは未対応。RR 側で登録したスタッフはスマレジには自動反映されません。

取引データの担当者解決

スタッフマスタを同期しておくと、取引データ（PosTransactionDto）に含まれる staffId から RR スタッフレコードを自動解決できるようになります。これにより、レシート表示・売上担当者集計が「スマレジ内部 ID」ではなく「RR で登録した社員名」で表示されるようになります。

スタッフマスタを同期していない場合は、取引データに含まれる staffName（スマレジ側で表示されている氏名）がそのまま使われます。

注意点

スマレジ側でスタッフを物理削除すると、その SmaregiStaffId による照合が効かなくなります。スマレジでは displayFlag による非表示化を推奨します。
RR 側で IsActive = false（退職扱い）にしても、過去取引の担当者解決は引き続き機能します。退職スタッフのレコードは削除せず残してください。
姓・名の自動分割は「最初の空白で 2 つに区切る」シンプルな処理です。複合姓や 3 単語以上の名前は意図しない分割になる可能性があります。同期後に RR 側で個別に修正できます。
1 人のスタッフが複数店舗を担当する場合は、同期後に RR 側で AssignedStoreIds に複数店舗を設定してください。