CrmCustomerDto 參考

CRM 顧客資料模型參考 POS串接

本文的對象
本文適用於透過 API、MCP、Webhook 處理 ReceiptRoller 顧客（CRM）資料的開發者。說明從 POS 匯入的顧客資訊如何被正規化。

CrmCustomerDto 是 ReceiptRoller 的顧客主檔的正規模型。在應用程式會員登錄的顧客、從 POS（Smaregi、Square）的會員主檔匯入的顧客、從店鋪 CRM 畫面手動登錄的顧客 — 全部都彙集到這一個型別。

1 個商業帳戶 = 1 個 CRM 命名空間。可在同一商業帳戶底下的多個店鋪共用顧客，以 StoreIds 欄位表現「屬於哪個店鋪」。

欄位	型別	內容
`OrganizationId`	string	商業帳戶 ID。PartitionKey。
`CustomerId`	string	RR 內部的顧客 ID（GUID）。RowKey。
`StoreIds`	string	所屬店鋪 ID 的逗號分隔。可以 `StoreIdList` 屬性作為陣列讀寫。

欄位	型別	內容
`LastName` / `FirstName`	string	姓、名（漢字）。顯示用有 `FullName` 屬性。
`LastNameKana` / `FirstNameKana`	string	姓、名（假名）。有 `FullNameKana` 屬性。
`Email`	string	電子郵件位址。以小寫化、去除前後空白進行正規化。是比對鍵之一。
`Phone`	string	電話號碼。正規化為 E.164 格式（例：`+819012345678`）。是比對鍵之一。
`Gender`	string	性別。選填。
`DateOfBirth`	DateTime?	出生日期。選填。以 UTC 保存。

PostalCode / Prefecture / City / Address1 / Address2。以 FullAddress 屬性連結顯示。皆為 string 且為選填。

欄位	型別	內容
`MembershipCode`	string	會員編號。RR 自動採番，或從 POS 端匯入（Smaregi 的 `customerCode`、Square 的 `reference_id` 等）。是比對鍵之一。
`MembershipLevel`	string	會員等級。預設值 `"Standard"`。例：Standard / Silver / Gold。

Tags（逗號分隔）、Notes（自由文字）、Status（預設 "Active"。已退會、已封鎖等）、CreatedAt、UpdatedAt。

CrmCustomerDto 是不依賴 POS 的正規模型。從 POS 匯入的顧客，會由另一個實體 PosCustomerLinkEntity 將 RR 顧客 ID 與 POS 端識別碼（vendor ＋ identityType ＋ vendorIdentifier 的三元組）關聯。

關於與 POS 的會員資料雙向同步、衝突解決規則（vendor 端 / RR 端何者較新，以欄位為單位的 last-write-wins）、比對鍵的優先順位，請參閱與 Smaregi、Square 的會員資訊雙向同步。

各 POS 的顧客欄位對應到 CrmCustomerDto 的哪個欄位，彙整在店鋪幫助的個別文章中。