j2.1.1
API の概要
Shopper Baskets V2 には Shopper Basket V1 のすべての機能が用意されています。また、一時的買い物カゴがサポートされています。 一時的買い物カゴでは、買い物客のストアフロントの買い物カゴに影響を与えることなく、合計、ラインアイテム、プロモーション、および商品の入手可能性を生成する計算を実行でき、これらの計算を一時的買い物カゴの注文手続きに使用できます。また、一時的な買い物カゴを使用して、即時の注文リクエストを行うこともできます。
注: dw.ocapi.shop.basket.beforePOST フックはサポートされなくなり、dw.ocapi.shop.basket.beforePOST_v2 フックに置き換えられました。
Shopper Baskets API を使用すると、B2C Commerce システムで買い物カゴを作成し、注文手続きの準備に必要なすべてのデータをその買い物カゴに設定できます。
買い物カゴを作成するには、Create basket エンドポイントから開始します。このエンドポイントは B2C Commerce システムで買い物カゴを作成し、basketId プロパティを含む買い物カゴの JSON 表現を返します。
事前にデータが設定された買い物カゴの JSON を Create basket エンドポイントに指定すると、1 回の API リクエストで買い物カゴを作成できます。
また、買い物カゴを作成し、同じ basketId を参照する後続の API リクエストを使用して、徐々にデータを入力することもできます。段階的なアプローチにより、入力データの検証を行いながら進めることができます。
Shopper Baskets API には、買い物カゴの各パーツに個別に入力するためのエンドポイントが含まれています。
- 請求先住所
- 顧客情報
- ラインアイテム
- 商品
- クーポン
- ギフト券
- 支払方法
- 価格表
- 配送
- 課税 (品目および買い物カゴ自体)
買い物カゴを作成するだけでなく、メインの /baskets リソースには、使用する HTTP メソッドと指定するパラメーターに応じて、買い物カゴの取得、引き継ぎ、マージ、および削除を行うためのエンドポイントも用意されています。これらのエンドポイントは、ユーザーがゲストとして買い物を開始してから注文手続き前にログインする場合など、さまざまな複雑なシナリオを処理するのに役立ちます。
また、メインの /baskets リソースを使用して、c_ を先頭にもつカスタムプロパティを買い物カゴに追加することができます (例: c_faxNumber)。
買い物カゴにすべての情報が入力されると、その basketId プロパティを使用して Shopper Orders API で注文を作成できます。
買い物カゴの作成の詳細については、買い物カゴの作成と注文の確定を参照してください。
認証と認可
買い物カゴの情報をリクエストするクライアントは、/baskets リソースへのアクセスが必要です。Shopper Baskets API には、Shopper Login and API Access Service (SLAS) の買い物客アクセストークンが必要です。
SLAS から買い物客アクセストークンをリクエストする方法の詳細については、SLAS ガイドのパブリッククライアントとプライベートクライアントのゲストユーザーフローを参照してください。
SLAS トークンの生成に使用するクライアント ID には、関連するスコープを含める必要があります。詳細については、認可スコープカタログを参照してください。
以下のリソースは、クライアント ID をもつ Account Manager OAuth トークンが必要です。
/baskets/{basketId}/taxes/baskets/{basketId}/items/{itemId}/taxes/baskets/{basketId}/price-books
ユースケース
フックの使用
フックの操作の詳細については、フックによる拡張性を参照してください。
買い物カゴの計算
フックを使用していない限り、買い物カゴに変更を加えるたびに以下の計算がトリガーされます。
- 商品価格を計算します。
- 商品ラインアイテムを反復処理し、各商品の価格モデルを使用してそれぞれの基本価格を決定します。1 つの商品に複数の価格表が適用される場合、最も低い価格が使用されます。
- 商品オプションモデルを使用して、商品オプションのラインアイテム価格を計算します。
- ボーナス商品の場合は、買い物カゴ内の依存調整を確認して価格を決定します。
- ギフト券ラインアイテム全体を反復処理し、基本価格に数量を掛けてそれぞれの価格を計算します。
- すべてのプロモーションについて再計算し、適宜追加、削除します。
- 商品固有の配送料を適用します。
- 合計配送料を計算します。
- すべてのプロモーションについて再計算し、適宜追加、削除します。 7.プロモーションエンジンによって追加された商品の価格を計算します。
- ラインアイテムの税区分コードを使用して税金を計算します。
- 内部税金モードでは、税率表を使用します。
- 外部税金モードでは、tax API エンドポイントから返される税率を使用します。
- 注文のネット、税、合計を行の合計で計算します。
外部課税
B2C Commerce API は、税率表を使用して内部で税金を計算します。サードパーティの税金プロバイダーと統合したり、独自に税金を計算したりしたい場合は、外部課税機能を使用して税率やオプションの課税値を追加できます。課税率を設定すると、この特定の税率に対応した税額が計算されます。値を渡すと、その値も再計算されずに課税値として使用されます。この機能を使用するには、買い物カゴ作成時に taxMode パラメーターを external に設定します。
外部課税を利用する場合、税率の設定を /baskets/{basketId}/taxes への 1 つのリクエストで行うか 、または、/baskets/{basketId}/items/{lineItemId}/taxes を使用して各ラインアイテムに別々のリクエストで行う必要があります。
買い物カゴの税金モードが external に設定されている場合、見落としを防ぐため、税金ゼロの項目であってもすべてのラインアイテムに税金項目が必要です。
フック有効時の外部課税
フックで外部税計算を使用するには、Calculate Hook で次の API メソッドを使用します。
dw.order.LineItemCtnr#isExternallyTaxed: 買い物カゴがtaxMode = externalで作成された場合に true を返します。dw.order.TaxMgr#applyExternalTax: 指定された買い物カゴに外部で設定された税率を適用します。dw.order.LineItemCtnr#isExternallyTaxedが true を返した場合にのみ使用します。
次の例は、Calculate フックでフックを有効にした外部税計算の実装を示しています。
exports.calculate = function (basket) {
if ( basket.isExternallyTaxed() )
{
TaxMgr.applyExternalTaxation( basket ); // apply the external tax calculation based on the tax rates set by the SCAPI external taxation APIs
}
else
{
// calculation with tax tables or customization
}
}
一時的買い物カゴ
一時的買い物カゴには、注文手続きの準備をするために必要なすべてのデータが設定されますが、次の点で通常の買い物客の買い物カゴと異なります。
- 買い物カゴの有効期間は 15 分に制限されます。
- 買い物客は最大 10 個 (デフォルトでは 4 個) の一時的買い物カゴを保持できます。これを構成するには、買い物カゴの環境設定 (サイト -> マーチャントツール -> 買い物カゴの環境設定) に移動し、顧客 1 人あたりの一時的買い物カゴ の環境設定を指定します。
- すべての買い物客 (ゲスト買い物客と登録済み買い物客)、およびエージェントが利用できます。
一時的買い物カゴを作成するには、Create basket エンドポイントで temporary パラメーターを true に設定します。
Let us know so we can improve!