Smaregi・Square 與會員資訊的雙向同步
ReceiptRoller 的會員資訊與連動的 POS（Smaregi・Square 等）雙向同步。在 ReceiptRoller 端登錄會員時，也會反映到 POS 的會員主檔；反之在 POS 登錄的會員資訊，也會匯入至 ReceiptRoller 的 CRM。不需要重複管理會員資訊。
本文說明雙向同步的機制、同步項目、同步時機、衝突時的優先順序、支援的 POS、設定方式。
什麼是雙向同步
「雙向」指資料朝兩個方向流動。
- ReceiptRoller → POS（outbound）：將透過應用程式登錄會員的顧客資訊，登錄至 POS 的會員主檔。如此一來，顧客首次來店時，POS 收銀人員即可辨識該顧客
- POS → ReceiptRoller（inbound）：將在 POS 登錄的會員資訊，匯入至 ReceiptRoller 的 CRM。如此一來，在店頭登錄會員的顧客，也能收到 Wallet 會員證或推播通知
同步項目
- 會員編號：ReceiptRoller 發行的編號，或 POS 發行的編號。無論哪一方先發行，都會以相同編號運作
- 姓名：姓・名（支援漢字與拼音兩種）
- 電子郵件地址
- 電話號碼（正規化為 E.164 格式）
- 會員等級：一般・銀卡・金卡等
- 生日（選填）
- 狀態：有效・已退會・已封鎖等
來店紀錄、購買紀錄、累計購買金額等行為資料，因為 ReceiptRoller 端會統整彙總來自 POS 的收據資料，所以不需要另外同步。
同步時機
ReceiptRoller → POS
- 新登錄時：顧客在應用程式完成會員登錄的瞬間，會將登錄工作加入 POS 端的佇列。通常在數秒到數分鐘內反映至 POS 端
- 資訊更新時：顧客在應用程式更新聯絡方式、姓名、生日等時，也會同步反映至 POS
- 等級變更時：因店舖管理畫面或購買紀錄變更會員等級時，POS 的會員等級也會同步更新
POS → ReceiptRoller
- 透過 Webhook（即時）：POS 進行新會員登錄或更新時，會透過 Webhook 立即通知 ReceiptRoller。通常數秒內即可反映至 CRM
- 定期同步（備份）：為因應 Webhook 未送達的情況，會定期取得 POS 的整個會員主檔並反映差異（預設每 1 小時一次）
衝突時的優先順序
當同一位顧客的資訊在兩端同時被更新時，會以「較新更新日期時間的資料」為優先。例如：
- 10:00 顧客在應用程式更新電子郵件地址
- 10:05 POS 端店舖人員更新電話號碼
- → 電子郵件地址以 10:00 應用程式的值、電話號碼以 10:05 POS 的值確定
若同時更新（毫秒單位無差異的情況），則以 POS 端的值為優先。由於 POS 是店舖業務流程的核心，設計上尊重 POS 的輸入。
新顧客的比對
當在 POS 登錄的顧客匯入 ReceiptRoller 的 CRM 時，會 自動比對是否為既有顧客的同一人。比對的鍵值依以下順序確認。
- 會員編號（完全一致）
- 電子郵件地址（小寫化・前後去除空白後的完全一致）
- 電話號碼（正規化為 E.164 格式後的完全一致）
若比對成功，會更新既有顧客的資訊。若未比對成功，則作為新顧客加入 CRM。
支援的 POS
- Smaregi：支援會員主檔・交易資料的雙向同步。使用 Smaregi Platform API
- Square：支援與 Customer Directory 的雙向同步。使用 Square Customers API
連動步驟請參閱另一篇文章「Square POS 的連動步驟」「Smaregi 的連動步驟」。其他 POS 也預計依序支援。
各 POS 的欄位對應
各 POS 的會員欄位對應 ReceiptRoller 顧客資料（CrmCustomerDto）的哪個欄位，已彙整於各 POS 的技術文件中。若有「我們的 Smaregi 明明有登錄出生年月日，卻沒有反映到 RR 端」之類的疑問，請參閱以下文章。
- Smaregi 會員資料的對應
- Square 顧客資料的對應
- CrmCustomerDto 參考文件（開發者用・正規模型的完整欄位規格）
設定步驟
只要完成與 POS 的連動，會員資訊的雙向同步就會自動啟用。不需要額外設定。
若想暫停同步，或想篩選同步項目，可從店舖管理畫面 →「POS連動」→「同步設定」進行調整。
確認同步狀態
在店舖管理畫面的「POS連動」→「同步紀錄」，可確認過去的同步紀錄。每筆紀錄會記載以下資訊。
- 方向（ReceiptRoller → POS ／ POS → ReceiptRoller）
- 目標顧客的會員編號與姓名
- 同步的項目（郵件・電話・等級等）
- 結果（成功・失敗・跳過）
- 時間戳記
失敗的紀錄會自動重試最多 3 次。仍然失敗時，原因（POS 端的驗證錯誤、資料格式錯誤等）會記錄於日誌中，並顯示於店舖管理畫面的通知中心。
疑難排解
- 在 POS 登錄的顧客未反映到 CRM：請於「同步紀錄」確認該顧客的同步狀態。若 Webhook 未送達，請確認 POS 端的 Webhook 設定，或稍候定期同步（每 1 小時一次）的下次時機
- 會員編號在 POS 與 CRM 不一致：雙向同步過程中可能發生衝突。請於「同步紀錄」確認衝突紀錄。原則上，先發行的編號會在雙方保留
- POS 的會員等級未更新：POS 端的會員等級項目名稱有時與 ReceiptRoller 預期的不同。請聯絡支援團隊
- 同一位顧客在 CRM 中重複登錄：若比對鍵值（會員編號・郵件・電話）皆不一致，會作為不同人登錄。請從 CRM 畫面的「重複候選」手動合併
注意事項
- 若在 POS 端完全刪除（實體刪除）會員資料，ReceiptRoller 端將無法進行比對。建議在 POS 端使用邏輯刪除（停用）
- 大量資料的首次同步（既有數千至數萬筆會員資料）會依序透過定期同步處理，完成可能需要數小時至半天
- 因 POS 端 API 的速率限制，若瞬間進行大量更新，部分同步可能會延遲
相關說明
-
Square員工資料與ReceiptRoller員工資料的對應關係說明Square Team Member如何與ReceiptRoller的員工資料（StaffDto）建立關聯。內容涵蓋手動連結的操作方式、交易資料負責人解析邏輯，以及Team Member API主要欄位的整理。
-
Smaregi 連動 — 全貌與開始方式Smaregi 與 ReceiptRoller 連動的全貌、所需準備、3 個步驟的概要，以及後續應閱讀的詳細文章彙整而成的第一篇文章。
-
Square顧客資料與ReceiptRoller顧客資料的對應關係說明Square Customer Directory如何轉換為ReceiptRoller的顧客資料（CrmCustomerDto）。內容涵蓋given_name／family_name的對應、地址的拆解邏輯，以及reference_id的處理方式。
-
Smaregi商品資料與ReceiptRoller商品資料的對應關係說明Smaregi的商品主檔資料如何轉換為ReceiptRoller的商品主檔（ProductDto），逐欄位整理商品代碼、商品名稱、分類、售價、成本、稅率的對應關係，以及Smaregi特有的注意事項。
-
Smaregi交易資料與ReceiptRoller交易資料的對應關係說明從Smaregi Platform API取得的交易資料，如何對應至ReceiptRoller交易資料模型的技術文件。內容涵蓋層級結構的對應、欄位層級的對應表、狀態碼的轉換、支付方式的正規化、明細／顧客／員工資訊的解析、時區與冪等性的處理、取得路徑（Source）的區別等內部規格，供想理解相關細節的開發者、營運負責人參考。