CrmCustomerDto リファレンス

CRM 顧客データモデルリファレンス POS連携

この記事の対象
レシートローラーの顧客（CRM）データを API・MCP・Webhook 経由で扱う開発者向けです。POS から取り込まれた顧客情報がどのように正規化されるかを説明します。

CrmCustomerDto はレシートローラーの顧客マスタの正規モデルです。アプリで会員登録された顧客、POS（スマレジ・Square）の会員マスタから取り込まれた顧客、店舗 CRM 画面から手動で登録された顧客 — すべてがこの 1 つの型に集約されます。

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	メールアドレス。小文字化・前後空白除去で正規化。マッチングキーの 1 つ。
`Phone`	string	電話番号。E.164 形式に正規化（例: `+819012345678`）。マッチングキーの 1 つ。
`Gender`	string	性別。任意。
`DateOfBirth`	DateTime?	誕生日。任意。UTC として保存。

住所

PostalCode / Prefecture / City / Address1 / Address2。FullAddress プロパティで連結表示。すべて string で任意。

会員情報

フィールド	型	内容
`MembershipCode`	string	会員番号。RR が自動発番、または POS 側から取り込み（スマレジの `customerCode`、Square の `reference_id` など）。マッチングキーの 1 つ。
`MembershipLevel`	string	会員ランク。既定値 `"Standard"`。例: Standard / Silver / Gold。

行動指標

フィールド	型	内容
`VisitCount`	int	来店回数。POS 取引から自動集計。
`TotalSpent`	decimal	累計購入金額。POS 取引から自動集計。
`LastVisitDate`	DateTime?	最終来店日。POS 取引から自動更新。

タグ・メモ・監査

Tags（カンマ区切り）、Notes（フリーテキスト）、Status（既定 "Active"。退会済み・ブロック済みなど）、CreatedAt、UpdatedAt。

POS との関係

CrmCustomerDto は POS 非依存の正規モデルです。POS から取り込まれた顧客は、別エンティティ PosCustomerLinkEntity によって RR 顧客 ID と POS 側識別子（vendor + identityType + vendorIdentifier の三つ組）が紐付けられます。

POS との会員データの双方向同期、競合解決ルール（vendor 側 / RR 側のどちらが新しいか、フィールド単位の last-write-wins）、マッチングキーの優先順位についてはスマレジ・Square との会員情報双方向同期を参照してください。

POS ベンダーからのマッピング

各 POS の顧客フィールドが CrmCustomerDto のどのフィールドに対応するかは、店舗ヘルプの個別記事にまとめています。

注意点

OrganizationId と CustomerId の組み合わせが一意のキーです。同じメールアドレスでも組織が違えば別顧客として扱われます。
マッチング（重複検出）は MembershipCode → Email → Phone の順で確認されます。詳細は会員情報双方向同期。
VisitCount / TotalSpent / LastVisitDate は集計値です。直接書き換えても次の取引ロードで上書きされます。
顧客の物理削除は推奨されません。Status を退会済みに更新してください。POS 側で物理削除すると、RR 側でのマッチングが効かなくなります。