Square 顧客データとレシートローラー顧客データのマッピング

Square 顧客 Customer Directory POS連携データマッピング

Square Customer Directory に登録された顧客は、レシートローラー連携後、レシートローラーの顧客データ（CrmCustomerDto） に自動的に変換されて取り込まれます。本記事では、フィールド単位の対応関係と、Square 固有のクセをまとめます。

会員情報の双方向同期そのものの仕組み（タイミング・競合時の優先順位・トラブルシューティング）はスマレジ・Square との会員情報双方向同期をご覧ください。本記事はあくまでも「どのフィールドが対応するか」に焦点を当てた技術ドキュメントです。

Square Customer Directory	レシートローラー（`CrmCustomerDto`）	備考
`id`	— （PosCustomerLink に保持）	Square 内部 ID。RR 側では Customer ではなく、リンクテーブル `PosCustomerLinkEntity` の `vendorIdentifier` に保存。
`reference_id`	`MembershipCode`	店舗運営者がフリーに使える ID。RR の会員番号として直接採用。未設定の場合は RR 側で自動発番。
`family_name`	`LastName`	そのまま転記。
`given_name`	`FirstName`	そのまま転記。
`email_address`	`Email`	小文字化・前後空白除去で正規化。
`phone_number`	`Phone`	E.164 形式に正規化（Square はそもそも E.164 で保存されているため、多くの場合変換不要）。
`birthday`	`DateOfBirth`	Square は `YYYY-MM-DD` 形式。RR では UTC 日時として保存。
`address.postal_code`	`PostalCode`	ハイフンは保持されたまま。
`address.administrative_district_level_1`	`Prefecture`	都道府県。
`address.locality`	`City`	市区町村。
`address.address_line_1`	`Address1`	町名・番地。
`address.address_line_2`	`Address2`	建物名・部屋番号。
`note`	`Notes`	店舗スタッフ向けの自由記述メモ。

カナ氏名（LastNameKana / FirstNameKana） — Square にはカナフィールドが無いため空。
性別（Gender） — Square Customer Directory の標準項目に無い。
Square 側のグループ（group_ids） — Square のグループ機能は RR の MembershipLevel や Tags とは粒度が異なるため、現バージョンでは取り込まれません。
Square 側のセグメント（segment_ids） — 自動計算される動的セグメントのため、RR 側に転写する意味が薄く未対応。

Square から新しい顧客情報が届くと、RR 側で既存顧客との同一人物判定が以下の順で行われます。

いずれもマッチしなければ、新規顧客として CRM に追加されます。マッチした場合は既存顧客の情報が更新されます（フィールド単位の last-write-wins）。

会員登録・更新（Square → RR）：Square Webhook（customer.created / customer.updated）で数秒以内に CRM に反映。
定期バックアップ：Webhook が届かなかった場合に備え、1 時間ごとに SearchCustomers API で差分取得。
RR → Square：アプリで顧客が会員登録・情報更新を行った瞬間に、Square の CreateCustomer / UpdateCustomer 呼び出しがキューに追加。通常数秒〜数分以内に反映。

Square 側で顧客を物理削除すると、RR 側でのマッチングが効かなくなります。Square ダッシュボードからの削除は慎重に行ってください。
Square の reference_id をスタッフが手動で書き換えると、RR 側の MembershipCode マッチングが切れます。会員番号として扱うフィールドは、登録後は変更しない運用を推奨します。
Square の address は構造化フィールドですが、店舗スタッフが UI 上で「番地」と「建物名」を区別せずに address_line_1 に全部入れているケースが多く見られます。その場合 Address2 は空になります。
Square のグループ・セグメントを RR のタグとして活用したい場合は、開発チームまでご相談ください。