Square顧客資料與ReceiptRoller顧客資料的對應關係

Square 顧客 Customer Directory POS連動資料對應

登錄於Square Customer Directory的顧客資料，在完成與ReceiptRoller的連動後，會自動轉換並匯入至ReceiptRoller的顧客資料（CrmCustomerDto）中。本文將整理欄位層級的對應關係，以及Square特有的注意事項。

會員資訊的雙向同步機制本身（時機、衝突發生時的優先順序、疑難排解）請參閱Smaregi、Square的會員資訊雙向同步。本文純粹是聚焦於「哪個欄位對應到哪裡」的技術文件。

Square Customer Directory	ReceiptRoller（`CrmCustomerDto`）	備註
`id`	— （保存於PosCustomerLink）	Square內部ID。ReceiptRoller端並非儲存於Customer，而是儲存在連結資料表 `PosCustomerLinkEntity` 的 `vendorIdentifier` 中。
`reference_id`	`MembershipCode`	門市經營者可自由使用的ID。直接採用作為ReceiptRoller的會員編號。若未設定，則由ReceiptRoller端自動發放編號。
`family_name`	`LastName`	原樣轉錄。
`given_name`	`FirstName`	原樣轉錄。
`email_address`	`Email`	轉為小寫、去除前後空白後進行正規化。
`phone_number`	`Phone`	正規化為E.164格式（Square本身即以E.164儲存，因此多數情況下無需轉換）。
`birthday`	`DateOfBirth`	Square為 `YYYY-MM-DD` 格式。ReceiptRoller則以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的群組功能與ReceiptRoller的 MembershipLevel 或 Tags 顆粒度不同，目前版本並不會匯入。
Square端的區隔（segment_ids）— 因屬於自動計算的動態區隔，轉錄至ReceiptRoller端的意義不大，目前尚未支援。

從Square收到新的顧客資料時，ReceiptRoller端會依下列順序進行與既有顧客的同一人判定。

若三者皆未比對成功，則會以新顧客的形式新增至CRM。若比對成功，則既有顧客的資訊會被更新（欄位層級的last-write-wins）。

會員新增、更新（Square → ReceiptRoller）：透過Square Webhook（customer.created / customer.updated）於數秒內反映至CRM。
定期備援：為應對Webhook未送達的情況，每1小時透過 SearchCustomers API取得差異資料作為備援機制。
ReceiptRoller → Square：當App內顧客完成會員登錄或資料更新的瞬間，Square的 CreateCustomer / UpdateCustomer 呼叫便會加入佇列。通常會在數秒至數分鐘內完成反映。

若在Square端實體刪除顧客，ReceiptRoller端的比對將失效。從Square儀表板刪除時請務必謹慎操作。
若門市人員手動改寫Square的 reference_id，ReceiptRoller端的 MembershipCode 比對將會中斷。建議作為會員編號使用的欄位，在登錄後不予變更。
Square的 address 雖為結構化欄位，但常見門市人員在UI上未區分「門牌號碼」與「建築物名稱」，而是全部輸入於 address_line_1 的情況。此時 Address2 將為空值。
若希望將Square的群組、區隔運用為ReceiptRoller的標籤，請與開發團隊洽談。