ProductDto リファレンス

PIM 商品データモデルリファレンス POS連携

この記事の対象
レシートローラーの商品マスタ（PIM）を API・MCP・Webhook 経由で扱う開発者向けです。POS から取り込まれた商品情報、店舗別の価格、バリエーション、原価などの構造を説明します。

ProductDto はレシートローラーの商品マスタ（PIM）の正規モデルです。店舗ダッシュボードの商品管理画面で登録された商品、Square Catalog から同期された商品、CSV インポートで取り込まれた商品 — すべてがこの 1 つの型に集約されます。

商品マスタは組織（ビジネスアカウント）単位で管理され、配下の店舗で共有できます。店舗ごとに異なる価格を持たせたい場合は、後述の StorePricesJson を使います。

主なフィールド

識別子・基本情報

フィールド	型	内容
`OrganizationId`	string	ビジネスアカウント ID。PartitionKey。
`ProductId`	string	RR 内部の商品 ID（GUID）。RowKey。
`ProductName`	string	商品名。
`SKU`	string	在庫管理単位（SKU コード）。Square 連携時は Variation の SKU が入る。
`JanCode`	string	JAN コード（バーコード）。
`Category`	string	カテゴリ名（文字列）。階層構造ではなくフラットな分類。
`Brand` / `Supplier` / `Description` / `Unit`	string	ブランド、仕入先、説明、単位（個・本・kg など）。

商品仕様

ModelNumber / Series / Color / Size / Weight / ContentVolume / Material / Specification / CountryOfOrigin。すべて string で任意。物販系の商品マスタで使う想定です。

B2B・物流・通関

CasePackSize（ケース入数）、MinimumOrderQuantity、LeadTimeDays、HsCode（HS コード）、StorageRequirements（保管条件）、Certifications。卸売・輸出入を行うビジネス向けの拡張フィールドです。

価格・原価

フィールド	型	内容
`BasePrice`	decimal	税抜き販売価格（基準価格）。
`BaseCostPrice`	decimal	原価（基準）。利益分析の基礎データ。
`TaxRate`	decimal	税率。既定 `0.10`（日本標準）。
`StorePricesJson`	string (JSON)	店舗別の価格・原価オーバーライド。`StorePrices` プロパティで配列としてアクセス可能。`GetPriceForStore(storeId)` / `GetCostPriceForStore(storeId)` ヘルパーあり。

計算ヘルパー：TaxIncludedPrice（税込価格）、ProfitMargin（粗利率 %）、MinVariantPrice / MaxVariantPrice（バリエーションあり時の価格幅）。

画像

ImageUrl（カバー画像 URL）と ImageUrlsJson（ギャラリー全体の JSON 配列）。ImageUrls プロパティで配列として読み取り可能。レガシー 1 画像商品との後方互換のため、ImageUrlsJson が空のときは ImageUrl を含む単要素配列にフォールバックします。

バリエーション

HasVariants（バリエーションを持つか）、VariantOptionsJson（カラー・サイズなどの選択肢定義）、Variants（ProductVariantDto の配列）。色違い・サイズ違いを 1 商品として扱う場合に使用します。

POS 連携用フィールド

フィールド	内容
`SquareCatalogObjectId`	Square Catalog の Item オブジェクト ID（`#XXXX` 形式）。同期時にセット。
`SquareVariationId`	Square Catalog の Variation オブジェクト ID。最初のバリエーションを保存。

プレオーダー・ステータス・監査

IsPreOrder、PreOrderReleaseDate、PreOrderNote（予約商品の発売日 / 注釈）。Status（Active / Discontinued / Draft）、SortOrder、InternalMemo、CreatedAt、UpdatedAt。

POS からのマッピング

各 POS の商品データが ProductDto のどのフィールドに対応するかは、店舗ヘルプの個別記事にまとめています。POS によって扱える項目が大きく異なる点に注意してください。

Square 商品データとレシートローラー商品データのマッピング — Catalog API による完全な双方向同期
スマレジ商品データとレシートローラー商品データのマッピング — 現バージョンでは取引明細経由のみ

注意点

OrganizationId と ProductId の組み合わせが一意のキーです。同じ商品名でも組織が違えば別商品です。
BaseCostPrice は売上分析の利益計算に直接使われます。値の更新は履歴を伴わないため、原価変更時のスナップショットが必要な場合は別途設計が必要です（コストデータ拡張 t-e9a2f447 系で検討中）。
StorePricesJson は店舗別オーバーライドであり、未設定の店舗では BasePrice / BaseCostPrice がそのまま適用されます。
Square Catalog から取り込まれた商品は SquareCatalogObjectId がセットされ、再同期時はこの ID で照合されます。手動で書き換えないでください。