PosTransactionDto 仕様 — 取引データのフィールドリファレンス
PosTransactionDto
取引データ
スキーマ
リファレンス
API
スマレジ
Square
POS連携
レシートローラーが扱う取引データの正規モデル PosTransactionDto の全フィールドを解説します。各 POS ベンダー（スマレジ、Square、その他）の取引データはすべてこのモデルに変換されたうえで、データベース・ダッシュボード・REST API・MCP ツールを通じて利用されます。
外部システムから API 経由で取引を読み書きする場合や、ベンダー側のフィールドがレシートローラー上でどのように見えるかを理解したい場合の参考にしてください。
概要
PosTransactionDto は 1 件の取引（1 件の会計）を表します。明細（商品単位）は LineItems として配列で保持され、内部的には LineItemsJson に JSON で永続化されています。
- すべての金額は店舗通貨 (JPY) で 税込 です（特記がない限り）
- すべての日時は UTC 保持・表示時に JST 変換
- キー:
TransactionId（レシートローラー内部 ID）とExternalTransactionId（POS ベンダー側の ID）の 2 つを持ちます
識別子
| フィールド | 型 | 説明 |
|---|---|---|
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) | レシートローラー側のレコード更新時刻（監査用） |
金額
| フィールド | 型 | 説明 |
|---|---|---|
TotalAmount | decimal (JPY) | 合計金額（税込） |
TaxAmount | decimal (JPY) | 消費税額 |
SubtotalAmount | decimal (JPY) | 小計（税抜）= TotalAmount - TaxAmount |
DiscountAmount | decimal (JPY) | 割引額（負の値ではなく正の値で保持） |
明細
| フィールド | 型 | 説明 |
|---|---|---|
LineItems | List<PosTransactionLineItemDto> | 商品単位の明細配列（計算プロパティ。実体は LineItemsJson） |
LineItemsJson | string (JSON) | 明細の JSON 永続化形式。直接読まず LineItems を使ってください |
ItemCount | int | 明細数量の合計（LineItems.Sum(li => li.Quantity)） |
PosTransactionLineItemDto
| フィールド | 型 | 説明 |
|---|---|---|
ProductName | string | 商品名。バリエーションがある場合は "商品名 (バリエーション名)" 形式 |
Quantity | int | 販売数量 |
UnitPrice | decimal (JPY) | 単価（税抜） |
Subtotal | decimal (JPY) | 小計（税込） |
TaxRate | decimal | 実効税率（%）。Square では明細から自動計算、スマレジでは taxRate をそのまま採用 |
Category | string | 商品カテゴリ。スマレジは categoryName を採用、Square は現状空 |
支払い
| フィールド | 型 | 説明 |
|---|---|---|
PaymentMethod | string (enum) | 支払い方法を以下に正規化:Cash / CreditCard / QR / IC / Other |
ReceiptNumber | string | レシート番号（POS 側で発番された番号） |
スタッフ
| フィールド | 型 | 説明 |
|---|---|---|
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 | 備考・メモ。Square ではレシート URL がここに格納されることがあります |
CRM 連携
取引が顧客に紐づけられた場合（POS 側の会員情報、電話・メール一致など）、レシートローラーの ICrmCustomerResolver が以下のフィールドを埋めます。
| フィールド | 型 | 説明 |
|---|---|---|
MembershipCode | string? | レシートローラー会員番号。紐付かなかった場合は null |
CrmCustomerId | string? | CRM 顧客レコードの ID。紐付かなかった場合は null |
表示用ヘルパー
UI 側で利用するための計算プロパティです。直接 DB に保存されません。
PaymentMethodDisplayName— 支払い方法の日本語表記（例: 「クレジットカード」）StatusDisplayName— ステータスの日本語表記（例: 「完了」「取消」）StatusBadgeClass— Bootstrap バッジ用 CSS クラスSourceDisplayName— 出典の表示名FormattedDateTime— 「yyyy/MM/dd HH:mm」形式の日時FormattedTotal— カンマ区切りの合計金額
ベンダー別マッピング
具体的に各 POS ベンダーがどのフィールドをどう埋めるかは、以下のベンダー別マッピング記事をご参照ください。
公開日: 2026-05-29
更新日: 2026-05-29
カテゴリ
タグ
API (10)
Webhook (8)
api (6)
OAuth (5)
oauth (5)
トラブル (5)
POS連携 (4)
getting-started (4)
アプリ登録 (4)
app-registration (3)