---
title: Commerce と CPQ
description: "製品から確定した金額までの道筋。ポリシー、明細の価格決定方式を決めるプロファイル、価格表、仕入原価、そして見積バージョンを扱います。"
---

ここのすべてのエンドポイントは `cpq` モジュールを必要とします。流れは一方向です。ワークスペースのポリシーとプロファイルが何が可能かを決め、価格表と仕入原価が数値を供給し、見積バージョンが結果を凍結します。

## まずポリシー

[`GET /settings/commercial`](/ja/reference/commerce/get-api-v1-settings-commercial) はすべての見積が従う算術を返します。ワークスペースごとに 1 つのオブジェクトでリビジョンを持ち、見積の側からこれを上書きすることはできません。

| 設定 | 既定 | 決めるもの |
| --- | --- | --- |
| `baseCurrency` | `JPY` | 金額を報告する通貨 |
| `currencies` | `{}` | 他にどの通貨を許すか、どの条件で許すか |
| `currencyScale` | `0` | 金額の小数桁数、0〜4。既定値は既定の通貨に合わせたものです |
| `rounding` | `half_up` | 計算された価格の丸め方。`half_up`、`half_even`、`toward_zero`、`floor`、`ceil` |
| `taxRounding` | `floor` | 同じ選択を税に独立して適用 |
| `taxCalculation` | `per_rate_total` | 税を `per_line` で計算するか、見積全体で税率ごとに一度計算するか |
| `calculationOrder` | `discount_before_tax` | 割引が税の前に入るか後に入るか |
| `pricesIncludeTax` | `false` | カタログ価格が税込みかどうか |
| `fiscalYearStartMonth` | `4` | 会計年度の開始月 |
| `timezone` | `Asia/Tokyo` | 日付を解釈するタイムゾーン |

**ポリシーの変更はリビジョン付きの書き込みです。** [`PUT`](/ja/reference/commerce/put-api-v1-settings-commercial) は読み取り時のリビジョンを取り、古い値は `settings_stale` で拒否します。既に書かれた見積は作成時のポリシーを保持します。各バージョンが `policySnapshot` を持つためです。

## プロファイルが明細の価格決定方式を決める

[`GET /cpq/configuration`](/ja/reference/commerce/get-api-v1-cpq-configuration) は `profile` という 1 つのフィールドを返し、それが見積明細で使える 5 つの価格決定方式を決めます。

| 方式           | `catalog` | `procurement` | `hybrid` | 仕入原価が必要 |
| -------------- | --------- | ------------- | -------- | -------------- |
| `catalog`      | ✓         |               | ✓        |                |
| `cost_plus`    |           | ✓             | ✓        | ✓              |
| `gross_margin` |           | ✓             | ✓        | ✓              |
| `resale`       |           | ✓             | ✓        | ✓              |
| `manual`       |           | ✓             | ✓        |                |

**`catalog` のワークスペースは価格表からのみ価格を決めます。`procurement` のワークスペースは `catalog` を一切使えません。** ユーザーインターフェースで方式を提示する前にプロファイルを読んでください。プロファイルに含まれない方式は無視されるのではなく拒否されます。

## 各方式の計算

率はパーセントではなく小数の割合で、結果はすべてポリシーの `rounding` で丸められます。

| 方式 | 算術 |
| --- | --- |
| `catalog` | 価格表のエントリ。計算はありません |
| `cost_plus` | `cost × (1 + markup)` |
| `gross_margin` | `cost ÷ (1 − margin)` |
| `resale` | `retailPrice` に対し、`downstreamMargins`（1〜10 個）の各率で `× (1 − rate)` を順に適用 |
| `manual` | 与えられた `unitPrice`。1〜500 文字の `reason` も必須です |

原価を使う 3 つの方式は、原価エントリが存在しないか負の場合 `purchase_cost_required` で拒否します。`manual` は原価も利益も報告しません。他は `unitProfit` を `unitPrice − unitCost` として報告します。

**`manual` は逃げ道であり、逃げ道として記録されます。** 必須の `reason` が明細に保存されるため、手で価格を付けた見積はその理由を述べています。

## 製品・価格表・価格合意

**製品**は販売対象です。**価格表**は 1 つの通貨の名前付き価格一覧で、価格は 1 件ずつではなく [`POST /price-books/{id}/entries`](/ja/reference/commerce/post-api-v1-price-books-by-id-entries) で 1〜500 件ずつまとめて入ります。

**価格合意**は 1 つの取引先を 1 つの価格表に期間付きで結び付けます。明細に複数該当する場合、`priority` が高いものが勝ち、最小数量の大きい方が同点を破ります。両方が同じ場合は恣意的に解決せず `price_agreement_ambiguous` で拒否します。矛盾する 2 つの合意は価格の問題ではなく設定の問題です。

**仕入原価**は事業が支払った額で、[`POST /purchase-costs`](/ja/reference/commerce/post-api-v1-purchase-costs) で記録し、製品ごとに [`GET /products/{id}/purchase-costs`](/ja/reference/commerce/get-api-v1-products-by-id-purchase-costs) で読みます。原価から価格を決める明細は `costEntryId` でエントリを指定するため、見積は今日の原価ではなく使った過去の原価を記録します。

## 見積・バージョン・明細

**見積**は `number`、取引先、任意で商談、そして裏付けとなる CRM レコードを持ちます。金額自体は持ちません。それはバージョンにあります。

**バージョン**は見積の価格が付いた 1 つの状態です。`currency`、`subtotal`、`taxableAmount`、`tax`、`discount`、`total`、価格決定時の `cpqProfile` と `policySnapshot`、`customerSnapshot`、`contentHash`、そして `draft`・`submitted`・`approved`・`rejected`・`accepted`・`superseded` のいずれかの `state` を持ちます。

commerce のエンドポイントはその状態を報告し、設定はしません。バージョンをその状態の間で動かすのは[承認](/ja/guides/concepts/permissions)側で、見積のレコードに対して申請されます。commerce が制御するのはバージョンが**凍結**されているかどうかで、これは状態とは別のフラグです。

バージョンの**明細**は `quantity`、`unit`、`unitPrice`、`unitCost`、`netAmount`、`discountAmount`、`taxRate`、使われた `pricingMethod`、`priceSnapshot`、そして数値の出所である `sourcePriceEntryId` か `sourceCostEntryId` を持ちます。2 つの列挙がこれを分類します。`chargeType` は `one_time`・`recurring`・`milestone`、`componentKind` は `product`・`hardware`・`software`・`service`・`option`・`package` です。

各明細は**スケジュール**を持てます。金額をどう期間に配分して請求するかで、`chargeType` と同じ 3 種類、月単位の間隔、マイルストーンのラベルを持ちます。これは価格決定ではなく請求の関心事で、形は[リファレンス](/ja/reference)にあります。

## ドラフトと改訂

2 つの経路があり、同じではありません。

[`POST /quotes`](/ja/reference/commerce/post-api-v1-quotes) は見積を作成し、最初のバージョンを**凍結します**。[`POST /quotes/drafts`](/ja/reference/commerce/post-api-v1-quotes-drafts) は同じものを、そのバージョンを凍結しない状態で作成し、[`PUT /quotes/{id}/draft`](/ja/reference/commerce/put-api-v1-quotes-by-id-draft) がそれをその場で編集します。凍結されたバージョンは編集できません。`quote_version_frozen` が代わりに改訂を作るよう告げます。

[`POST /quotes/{id}/versions`](/ja/reference/commerce/post-api-v1-quotes-by-id-versions) はバージョンを追加して見積を改訂します。知っておく価値のある 2 つの拒否があります。

- `quote_stale` — 送ったリビジョンが現在のものではありません。読み直して再試行してください。
- `quote_draft_open` — 最新のバージョンがまだ凍結されていません。**改訂の前にドラフトを完了してください。** ドラフトと改訂は同じ見積を変える 2 つの方法で、同時に進められるのは一方だけです。
- `quote_approval_pending` — その見積に承認が開いています。改訂の前に取り下げてください。

[`POST /quotes/preview`](/ja/reference/commerce/post-api-v1-quotes-preview) は何も作らずに見積の価格を計算します。利用者が入力している間に合計を表示するのはこれです。

## 原価の履歴がない状態で試す

`procurement` または `hybrid` のワークスペースは、その製品の仕入原価が存在するまで `cost_plus` の明細に価格を付けられません。先に `POST /purchase-costs` で 1 件記録するか、原価履歴を読み込んでいる間は理由を添えて `manual` を使ってください。