PosTransactionDto 仕様 — 取引データのフィールドリファレンス

PosTransactionDto 取引データスキーマリファレンス API スマレジ Square POS連携

レシートローラーが扱う取引データの正規モデル PosTransactionDto の全フィールドを解説します。各 POS ベンダー（スマレジ、Square、その他）の取引データはすべてこのモデルに変換されたうえで、データベース・ダッシュボード・REST API・MCP ツールを通じて利用されます。

外部システムから API 経由で取引を読み書きする場合や、ベンダー側のフィールドがレシートローラー上でどのように見えるかを理解したい場合の参考にしてください。

概要

PosTransactionDto は 1 件の取引（1 件の会計）を表します。明細（商品単位）は LineItems として配列で保持され、内部的には LineItemsJson に JSON で永続化されています。

金額は Currency で示す通貨（既定 JPY）で、特記がない限り税込です
すべての日時は UTC 保持・表示時に JST 変換
キー: TransactionId（レシートローラー内部 ID）と ExternalTransactionId（POS ベンダー側の ID）の 2 つを持ちます
支払いは複数テンダー（分割会計）に対応し、Payments 配列で保持します（単一文字列の PaymentMethod は後方互換のため残しています）
返金・外部連携 ID・カード情報・生データなど、ベンダーが送る情報を取りこぼさないよう拡張されています

識別子

フィールド	型	説明
`TransactionId`	string	レシートローラー内部の取引 ID。多くの場合 POS 側の ID をそのまま採用します（idempotent upsert のキーになります）
`ExternalTransactionId`	string	POS ベンダー側の取引 ID。スマレジ: `transactionHeadId`、Square: `Payment.Id`
`OrganizationId`	string (Guid)	ビジネスアカウントの ID
`StoreId`	string (Guid)	店舗 ID
`TerminalId`	string (Guid)	POS 端末（レジ機）の ID

日時

フィールド	型	説明
`TransactionDateTime`	DateTime (UTC)	会計が成立した時刻。Square `created_at`、スマレジ `transactionDateTime` から変換
`CreatedAt`	DateTime (UTC)	レシートローラー側のレコード作成時刻（監査用）
`UpdatedAt`	DateTime (UTC)	レシートローラー側のレコード更新時刻（監査用）

金額

フィールド	型	説明
`Currency`	string	すべての金額の通貨コード（ISO-4217、既定 `JPY`）。Square は `money.currency` から、スマレジは JPY 固定
`TotalAmount`	decimal	合計金額（税込）
`TaxAmount`	decimal	消費税額
`SubtotalAmount`	decimal	小計（税抜）= `TotalAmount - TaxAmount`
`DiscountAmount`	decimal	割引額（負の値ではなく正の値で保持）
`TipAmount`	decimal?	チップ・サービス料。ソースが別途送る場合のみ（Square `tip_money`）。該当しない場合は null

明細

フィールド	型	説明
`LineItems`	List<PosTransactionLineItemDto>	商品単位の明細配列（計算プロパティ。実体は `LineItemsJson`）
`LineItemsJson`	string (JSON)	明細の JSON 永続化形式。直接読まず `LineItems` を使ってください
`ItemCount`	int	明細数量の合計（`LineItems.Sum(li => li.Quantity)`）

PosTransactionLineItemDto

フィールド	型	説明
`ProductName`	string	商品名。バリエーションがある場合は `"商品名 (バリエーション名)"` 形式
`Quantity`	int	販売数量
`UnitPrice`	decimal	単価（税抜）
`Subtotal`	decimal	小計（税込）
`TaxRate`	decimal	実効税率（%）。Square では明細から自動計算、スマレジでは `taxRate` を採用
`TaxAmount`	decimal?	明細単位の税額。Square `total_tax_money`、スマレジ `tax`。税率しか持たないソース・過去データでは null
`DiscountAmount`	decimal?	明細単位の割引額。Square `total_discount_money`。明細別割引を持たないソースでは null
`Category`	string	商品カテゴリ。スマレジは `categoryName`、Square は現状空
`Sku`	string?	ベンダー SKU / 商品コード。スマレジは `productCode`。PIM 商品との照合に使用
`CostPriceAtSale`	decimal?	販売時点の PIM 原価（税抜）スナップショット。粗利計算に使用。原価未設定なら null
`ProductId`	string?	ソース商品 ID（判明時）
`CatalogObjectId`	string?	ベンダーのカタログオブジェクト ID（Square `catalog_object_id`、スマレジ productId）。システム間連携用
`Unit`	string?	販売単位（「個」「kg」など）。ソースが持つ場合のみ
`Note`	string?	明細単位の備考
`Modifiers`	List<PosLineItemModifierDto>?	明細のオプション・モディファイア（Square modifiers）。`Name` と `Amount` を持つ

支払い

取引は複数のテンダー（分割会計）を持てます。完全な内訳は Payments（実体は PaymentsJson）に保持し、単一文字列の PaymentMethod は後方互換のため「主たるテンダー」を保持します。

フィールド	型	説明
`PaymentMethod`	string (enum)	主たる支払い方法を正規化: `Cash` / `CreditCard` / `QR` / `IC` / `Other`
`Payments`	List<PosPaymentDto>	テンダーの完全な内訳（計算プロパティ。実体は `PaymentsJson`）
`PaymentsJson`	string (JSON)	テンダー内訳の JSON 永続化形式
`ReceiptNumber`	string	レシート番号（POS 側で発番された番号）

PosPaymentDto

フィールド	型	説明
`Method`	string	正規化した方法（`Cash` / `CreditCard` / `QR` / `IC` / `Other`）、または対応しない場合はソースの生の名称
`Amount`	decimal	このテンダーの金額
`TenderedAmount`	decimal?	預かり金額（ソースが報告する場合）
`ChangeAmount`	decimal?	釣り銭（ソースが報告する場合）
`Brand`	string?	カードブランド（VISA、Mastercard など）。カード決済のみ
`Last4`	string?	カード下 4 桁。表示可（PAN は保持しません）
`ExternalId`	string?	ソース側の支払い ID（取引 ID と異なる場合）

返金

（一部）返金された取引の返金内訳です。Refund（実体は RefundJson）に保持されます。

フィールド	型	説明
`Refund`	PosRefundDto?	返金内訳（なければ null）
`RefundJson`	string (JSON)	返金内訳の JSON 永続化形式

PosRefundDto

フィールド	型	説明
`Amount`	decimal	返金額
`IsPartial`	bool	一部返金かどうか
`Reason`	string?	返金理由
`OriginalTransactionId`	string?	返金対象の元取引
`RefundedAt`	DateTime?	返金日時

注: モデルと API のかたちは整備済みで、返金データが存在すれば反映されます。Square / スマレジは返金を別の Webhook イベントとして送るため、エンドツーエンドの返金取込は別途の同期処理で対応します。

外部連携・レシートURL

ソース POS の各種 ID とレシート URL を、取引を出自レコードへ突き合わせられるよう保持します。

フィールド	型	説明
`ReceiptUrl`	string	顧客向けレシート URL（Square `receipt_url`）。構造化フィールドです（以前は Notes に格納していましたが廃止）
`ExternalIds`	PosExternalIdsDto?	ベンダー横断 ID（計算プロパティ。実体は `ExternalIdsJson`）
`ExternalIdsJson`	string (JSON)	外部 ID の JSON 永続化形式

PosExternalIdsDto

フィールド	型	説明
`ProviderOrderId`	string?	ベンダーの注文 ID（Square `order_id`）
`LocationId`	string?	ベンダーのロケーション ID（Square `location_id`）
`ProviderCustomerId`	string?	ベンダーの顧客 ID（Square `customer_id`、スマレジ customerId）

生データ

フィールド	型	説明
`RawJson`	string (JSON)	取込時のソース生ペイロード。モデル化していないフィールド（カード fingerprint 等）も復元できるよう保持します。サーバー内部用で API では返しません

スタッフ

フィールド	型	説明
`StaffName`	string	担当スタッフ名（取得できなかった場合は空）
`StaffId`	string	POS ベンダー側のスタッフ ID（Square: `team_member_id`、スマレジ: `staffId`）

ステータス・出典

フィールド	型	説明
`Status`	string (enum)	`Completed` / `Voided` / `Refunded` / `Pending`。表示用は `StatusDisplayName`
`Source`	string (enum)	`API`（POS から自動取込）/ `Webhook`（POS からプッシュ通知）/ `CSV`（一括取込）/ `Manual`（手動入力）
`Notes`	string	備考・メモ。レシート URL は `ReceiptUrl` に移動したため、ここには格納しなくなりました

CRM 連携

取引が顧客に紐づけられた場合（POS 側の会員情報、電話・メール一致など）、レシートローラーの ICrmCustomerResolver が以下のフィールドを埋めます。

フィールド	型	説明
`MembershipCode`	string?	レシートローラー会員番号。紐付かなかった場合は null
`CrmCustomerId`	string?	CRM 顧客レコードの ID。紐付かなかった場合は null

ソース側の生の顧客 ID は ExternalIds.ProviderCustomerId で別途参照できます。

表示用ヘルパー

UI 側で利用するための計算プロパティです。直接 DB に保存されません。

PaymentMethodDisplayName — 支払い方法の日本語表記（例: 「クレジットカード」）
StatusDisplayName — ステータスの日本語表記（例: 「完了」「取消」）
StatusBadgeClass — Bootstrap バッジ用 CSS クラス
SourceDisplayName — 出典の表示名
FormattedDateTime — 「yyyy/MM/dd HH:mm」形式の日時
FormattedTotal — カンマ区切りの合計金額

後方互換性

上記の拡張フィールドはすべて 追加・nullable で、JSON 列として永続化されます。Table Storage のマイグレーションは不要で、既存行や既存の LineItemsJson はそのまま有効です。新フィールドは新規に取り込まれた取引から反映されます（過去データへ反映するには再同期が必要です）。

ベンダー別マッピング

具体的に各 POS ベンダーがどのフィールドをどう埋めるかは、以下のベンダー別マッピング記事をご参照ください。