レシートローラーはスマレジを含む複数の POS ベンダーと連携しています。どのベンダーから取り込まれた取引でも、内部的には共通の取引データモデル（PosTransactionDto）で扱えるよう、ベンダー固有のフィールドを正規化しています。本記事ではスマレジ Platform API の取引データを、レシートローラーの内部モデルにどう対応付けているかを技術的に解説します。

この記事は POS 連携の内部仕様を理解したい開発者・運用担当者向けの参考資料です。日常的な連携の設定手順は スマレジの POS 連携設定 をご覧ください。フィールド単位の正規モデル仕様は PosTransactionDto 仕様（フィールドリファレンス） を参照してください。

階層構造の対応

スマレジ Platform API は契約・店舗・端末・取引という 4 階層を持ちます。レシートローラー側はビジネスアカウント・店舗・POS 端末・取引という 4 階層で、設計上は 1 対 1 で対応します。

• 契約（contractId） ↔ レシートローラーのビジネスアカウント。スマレジで「レシートローラーリンク」アプリをインストールすると、その契約はレシートローラーの 1 ビジネスアカウントに紐付けられます（SmaregiContract.OrganizationId）。
• スマレジ店舗（storeId） ↔ レシートローラー店舗。PosTerminal.SmaregiStoreId でレシートローラー側 POS 端末に紐付けます。
• スマレジ端末（terminalId） ↔ レシートローラーの POS 端末。PosTerminal.SmaregiTerminalId に保持し、1 つの レシートローラー POS 端末は 1 つのスマレジ端末（レジ）に対応します。
• 取引（transactionHeadId） ↔ レシートローラーの取引。同 ID を PosTransaction.TransactionId および ExternalTransactionId として保存します。

取引ヘッダーのフィールドマッピング

スマレジ /pos/transactions のレスポンス（SmaregiTransaction）と、レシートローラーの PosTransactionDto の対応です。

ステータスコードの変換

スマレジのステータス値は数値文字列で返ります。レシートローラー内では文字列ラベルに正規化します。

フィールド名は仕様により status と cancelDivision を併用するケースがあります。両方の値を見て判定するため、いずれかが取れれば正しく分類されます。

支払い方法の正規化

スマレジの paymentMethods は配列で返り、各要素に支払い方法名と金額が入っています（分割決済の場合は複数要素）。レシートローラーは「主たる支払い方法」を 1 つだけ持つため、配列の中から金額が最大の要素を採用し、その日本語表記を内部コードに正規化します。

スマレジの取引一覧 API では支払い方法が含まれない場合があり、その際は別エンドポイントから補完取得を行います。実装の最新状況はソースコード（SmaregiTransactionMapper）を参照してください。

明細（行アイテム）のマッピング

取引ヘッダーとは別に、/pos/transactions/{id}/details から明細データを取得し、PosTransactionLineItemDto の配列に変換して LineItemsJson へシリアライズ保存します。

ItemCount（取引全体の購入点数）は、明細の Quantity の合計として算出します。

顧客情報の解決（CRM 連携）

スマレジから取得した customerId / customerCode は、取引データの直接フィールドとしては保存せず、顧客マッチキーとして CRM 解決サービス（IPosCustomerMatchService）に渡します。マッチが成立すれば、レシートローラーの CRM 顧客プロファイルに取引が自動でひも付き、顧客別の購入履歴や離反予兆スコアの算出に利用されます。

マッチキーの主な種類は次のとおりです（実装の PosCustomerMatchDto 参照）。

• 会員番号（メンバーシップコード）— スマレジの customerCode 等
• 外部顧客 ID — スマレジの customerId
• メールアドレス・電話番号 — スマレジから取得できる場合のみ

マッチが成立しない取引は、店舗端末 QR スキャン経由で顧客が後から自分でひも付けることもできます。

スタッフ情報の補完

取引ヘッダーには staffId しか入らないケースがあります。その場合は別途 /pos/staffs/{staffId} を呼び出して displayName を取得し、StaffName に保存します。スタッフ名の取得に失敗しても取引取り込み自体は失敗とせず、空のまま保存します（取引データの欠損を防ぐため）。

取得経路（Source）の区別

同じ取引でも、どの経路で取り込まれたかを Source フィールドで区別します。

• Webhook — スマレジからリアルタイムにプッシュされた経路
• Sync — 店舗オーナーが「スマレジと同期」ボタンを押した手動同期経路
• API — その他の Platform API 経由の取得（QR スキャン時の即時取得など）

同じ transactionHeadId が複数経路で届いても、同 ID をキーとして upsert するため取引が重複することはありません。Source 値は最後に取り込んだ経路を反映します。

タイムゾーンの扱い

スマレジ Platform API は JST（+09:00）の ISO 8601 形式で日時を返します。レシートローラー側はすべて UTC で保存し、表示時に JST へ変換します。Platform API への日時フィルタ送信時も、UTC を JST へ変換し、URL エンコードして送信します（+09:00 の + 記号が空白として解釈されないように）。

冪等性

取引の upsert は transactionHeadId をキーに行います。同じ取引が Webhook と手動同期の両方で届いても、結果として 1 件のレコードに収束します。UpdatedAt は最新の取り込み時刻に更新されますが、TransactionDateTime（取引発生時刻）は不変です。

取り込みパイプラインの全体像

1. スマレジ側で取引が発生 → スマレジ Platform から Webhook がレシートローラーへ送信される
2. レシートローラーの Webhook 受信エンドポイントがカスタムヘッダー認証を実施
3. ペイロードから transactionHeadIds（複数の場合あり）を抽出
4. 各 ID について Platform API から取引ヘッダー＋明細＋スタッフを取得
5. SmaregiTransactionMapper で PosTransactionDto に変換
6. 顧客マッチキーを IPosCustomerMatchService に渡し、CRM 解決を実行
7. PosTransactionService.UpsertAsync で保存（重複は上書き）
8. PosTerminal.LastTransactionAt を更新（QR スキャン経由の最新取引表示用）
9. 顧客が判明している場合は自動配信サービスに引き渡し（電子レシート配信）

関連記事

• PosTransactionDto 仕様（フィールドリファレンス） — 各フィールドの詳細仕様
• Square 取引データとのマッピング — Square 版
• スマレジの POS 連携設定 — 連携手順
• POS との連携
• Square の POS 連携設定
• スマレジ・Square との会員情報双方向同期
• 顧客別の購入履歴（POS 連携）