B2C Commerce API 入門ガイド

API の使用を今すぐ開始するには、クイックスタートに移動してください。エンドポイントの参照については、API 参照資料を参照してください。

B2C Commerce API は、B2C Commerce インスタンスとやり取りするための RESTful API のコレクションです。この API は、「Salesforce Commerce API」、頭文字をとって「SCAPI」、または単に「Commerce API」など、いくつかの異なる名前で呼ばれています。

デベロッパーはこの API を使用して、完全なストアフロントから Business Manager を補強するカスタムマーチャントツールに至るまで、幅広いアプリケーションを構築できます。B2C Commerce の顧客は、追加料金なしで API を利用できます。

API は、大きく 2 つの API グループ、Shopper API と Admin API に分かれています。そして、それぞれのグループの中で、API ファミリーに分割され、さらに関連する機能にフォーカスした小さなグループに分割されます。

2 つの API グループを並べて比較してみます。

Shopper APIAdmin API
買い物客や、買い物客を代行する信頼できるシステムが使用管理者や他の特権ユーザーが使用
Shopper Login and API Access Service (SLAS) がアクセスのセキュリティを保護Account Manager がアクセスのセキュリティを保護
匿名ユーザーと複数の認証メソッドをサポートAccount Manager のみが単独で認証を処理
読み取り専用 (例外: Shopper Baskets と Shopper Orders)読み取りと書き込み
大規模な利用を想定した設計中程度の利用を想定した設計
API 名は「Shopper」で始まる命名規則なし
含まれるもの: Shopper Baskets、Shopper Customers、Shopper Orders、Shopper Products、その他 7 つ含まれるもの: Assignments、Catalogs、Customers、Inventory Availability、Orders、Products、その他 8 つ

B2C Commerce API で重要な役割を果たすのが、Shopper Login and API Access Service (SLAS) です。SLAS 認可エンドポイントは、Shopper API へのアクセスを保護するトークンを提供します。トークンは、OAuth 2.1 規格で定義されたさまざまな付与タイプを使って提供されます。

SLAS によって、Shopper API へのアクセスをセキュアにできるだけでなく、サードパーティによるプロバイダー識別、シングルサインオン、パーソナル化の機能をアプリケーションで使用できるようになります。

SLAS の詳細とアプリケーションでの使用方法については、SLAS ガイドを参照してください。

SLAS が B2C Commerce API に追加される前は、買い物客のログインは、/customers/actions/login/trusted-system/actions/login の各エンドポイントで行われていました。これらのエンドポイントは廃止予定であり、2023 年 3 月 31 日に削除される予定です。新規顧客はこれらのエンドポイントを使用できず、既存顧客も使用しないよう勧められています。その代わり、セキュリティと可用性に関する高い基準を満たす SLAS の使用を強く推奨します。

オープンソースの JavaScript SDK は npm で利用でき、デベロッパーはこの API をすぐに使い始めることができます。

パッケージ説明ドキュメントソースコード
commerce-sdkサーバーサイドまたはコマンドラインアプリケーションで使用される Node.js SDK。ドキュメントソース
commerce-sdk-isomorphicサーバーサイドおよび Web ブラウザーで使用される JavaScript SDK。ドキュメントソース
@salesforce/commerce-sdk-reactReact.js SDK。ドキュメントソース

Salesforce では、React アプリで B2C Commerce API を利用し、いち早く開発を進めたいデベロッパー向けに、Progressive Web App Kit (PWA Kit) フレームワークを提供しています。PWA Kit アプリケーションを Salesforce のパブリッククラウドインフラに展開するには、Managed Runtime というコンパニオン製品を使用します。

PWA Kit と Managed Runtime の詳細については、製品ドキュメントを参照してください。

B2C Commerce API は、Open Commerce API (OCAPI) とは別物です。どちらの API でも多くの同じタスクを実行できますが、両者の間に完全な機能パリティがあるわけではありません。

Shopper API の動作は、B2C Commerce インスタンスにデプロイされたカートリッジに含まれるフックを使用してカスタマイズできます。

詳細については、フックによる拡張性を参照してください。

相関 ID を使用して特定のリクエストと特定のレスポンスを照合することで、内部サーバーエラーなど予期せぬ問題のトラブルシューティングを簡単に行えるようになります。

B2C Commerce API エンドポイントへのリクエストで correlation-id ヘッダーが渡された場合、レスポンスには correlation-id の値を含む x-correlation-id ヘッダーが含められます。また、API によって、各レスポンスのための独自の相関 ID が生成されます。

API リクエストとレスポンスの相関の詳細については、リクエストとレスポンスの特定を参照してください。

  • バニティドメインを使用するように設定された Staging (ステージング) 環境で B2C Commerce API を使用する場合は、Staging (ステージング) 用の eCDN を設定する必要があります。
  • パフォーマンスを向上させるため、Shopper API ファミリーのリクエストはトークンの Unique Shopper ID (USID) を使用して ECOM サーバーにルーティングされます。1 つのサーバーに過剰な負荷がかかるのを回避するため、多くのゲスト買い物客を代行してリクエストを行う場合は同じ USID を使用しないでください。
  • B2C Commerce API は、クロスオリジンリクエストをサポートしていません。Web ブラウザーで使用する場合は、リバースプロキシを使用してください。
  • B2C Commerce API は CORS ヘッダーを解釈しません。

お使いのコードが API に対する非破壊的変更 (nonbreaking change) を処理できることを確認してください。

B2C Commerce API のリソースの各グループは、バグ修正、セキュリティ更新、パフォーマンス業績の最適化、新機能、その他の改善によって定期的に更新されます。通常これらの更新は、 更新が行われた後リリースノートで発表されます。

事前の通知なしに重大な変更を行うことはしませんが、一部の更新には以下のような非破壊的変更が含まれます。

  • 新しいエンドポイント
  • 既存のエンドポイントに追加される新しいメソッド
  • 新しいボディフィールド
    • レスポンスの新しいフィールド
    • 新しいオプションのリクエストフィールド
    • デフォルト値をもつ新しい必須リクエストフィールド
  • レスポンスボディ内のフィールドの順序変更
  • 新しいオプションのリクエストとレスポンスのヘッダー
  • 新しいオプションのクエリパラメーター
  • デフォルト値をもつ新しい必須クエリパラメーター
  • エラー応答の変更。ビジネスロジックを実行するためにエラーメッセージを解析することは推奨されていません。代わりに、HTTP レスポンスコードとエラータイプを使用してください。
  • SLAS JWT に追加される新しいクレーム
  • SLAS JWT 内の既存のクレームの並べ替え
  • HTTP レスポンスコードとエラーコードを誤ったコードから正しいコードに修正するためのフィックス

B2C Commerce API サービスの利用可能状況に関する最新情報は、Salesforce ステータスで購読できます。

デモ用 Sandbox (サンドボックス) とサンプルデータで API を試すには、API と SDK のデモに移動してください。

API を使用するために実際のインスタンスの設定を始める準備ができたら、構成値Shopper API の認可のガイドを参照してください。

各 API エンドポイントの全機能を調べるには、参照資料セクションの仕様を参照してください。