B2C Commerce API 入門ガイド

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

SCAPI を使用すると、完全なストアフロントから Business Manager に追加するカスタムマーチャントツールまで、幅広いアプリケーションを構築できます。SCAPI が B2C Commerce スタックにどのように適合するかについては、コンポーザブルストアフロントと SCAPI を参照してください。B2C Commerce のお客様は、この API を追加費用なしで利用できます。

このページでは、SCAPI と、その使用を開始する方法について説明します。エンドポイントの参照については、API 参照資料を参照してください。B2C Commerce 管理者のドキュメントを表示するには、B2C Commerce の使用開始を参照してください。

B2C Commerce インスタンスがない場合は、クイックスタートの説明に従って、デモサンドボックスとサンプルデータで API を試してみてください。

SCAPI を使用するように独自のインスタンスを設定するには、次のようにします。

  1. 作業する環境 (開発、本番、ステージングなど) を決定します。また、独自の On-Demand Sandbox を作成することもできます。
  2. SCAPI の API グループについて理解します。
  3. ベース URL とリクエストの作成と認可のガイドの指示に従います。

SCAPI の概要に関する追加情報については、このトピックの残りのセクションを参照してください。

SCAPI は、Shopper API と SCAPI Admin API という 2 つの主要な API グループで構成されています。使用する API グループは、アプリケーションによって異なります。

  • Shopper API グループは、商品の閲覧、買い物カゴの管理、注文手続きなどの顧客向け機能のために設計されています。
  • SCAPI Admin API グループは、商品管理、注文管理、在庫管理、顧客管理などのマーチャント向け機能を対象としています。

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

SCAPI Shopper APISCAPI Admin 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内容: Assignments、Catalogs、Customers、Inventory Availability、Orders、および Products

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

SLAS では、Shopper API へのアクセスを保護するだけでなく、アプリケーションでサードパーティの ID プロバイダー、シングルサインオン、パーソナライゼーションを有効にすることもできます。

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

オープンソースの JavaScript SDK は npm で入手でき、作業の開始に役立ちます。

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

その他の言語については、SCAPI Postman コレクションまたは commerce-sdk に含まれる API 仕様を確認してください。

SCAPI を使用してストアフロントを構築する場合は、コンポーザブルストアフロントソリューションを提供しています。コンポーザブルストアフロントのドキュメントを参照してください。

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

OCAPI の代わりに SCAPI を使用する理由を参照してください。

SCAPI では、機能をカスタマイズおよび拡張できます。

  • B2C Commerce インスタンスにデプロイされたカートリッジに含まれるフックを使用して、Shopper API の動作をカスタマイズします。フックによる拡張性を参照してください。
  • フックを使用して実装できない追加機能が必要な場合は、カスタム API を参照してください。

相関 ID を使用して、特定のリクエストを特定のレスポンスに一致させます。これにより、内部サーバーエラーなどの予期しない問題のトラブルシューティングが容易になります。

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

リクエストとレスポンスの識別を参照してください。

correlation-id と組み合わせて使用すると、sfdc_verboseヘッダーを使用して Log Center で詳細ログ出力を生成および検索できます。

  • バニティドメインを使用するように設定された Staging (ステージング) 環境で SCAPI を使用する場合は、Staging (ステージング) 用の eCDN を設定する必要があります。
  • 可用性を確保し、サービス拒否攻撃からユーザーを保護するために、一部の SCAPI リクエストはレート制限されています。各ファミリーの API がどのように制限されているかは、レート制限を参照してください。
  • Shopper API とカスタム API は 10 秒以内にレスポンスする必要があり、SCAPI Admin API のリクエストとフックは 60 秒以内にレスポンスする必要があります。SCAPI リクエストへのレスポンスがタイムアウトしきい値を超えると、HTTP 504 ステータスコードが返されます。
  • パフォーマンスを向上させるため、Shopper API ファミリーのリクエストは、トークンの Unique Shopper ID (USID) を使用して B2C Commerce サーバーにルーティングされます。1 つのサーバーに過剰な負荷がかかるのを回避するため、多くのゲスト買い物客を代行してリクエストを行う場合は同じ USID を使用しないでください。
  • SCAPI はクロスオリジンリクエストをサポートしていません。Web ブラウザーで使用する場合は、リバースプロキシを使用してください。

一部の新機能は、特定の B2C Commerce バージョンでのみ使用できます。この情報は、B2C Commerce リリースノートおよび該当する場合は API 仕様に含まれています。

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

SCAPI は定期的に更新され、新機能、パフォーマンスの最適化、バグ修正、セキュリティアップデート、その他の改善が行われています。これらの更新は、Salesforce ステータスおよびSCAPI リリースノートで発表されています。

事前の通知なしに破壊的変更を行うことは避けていますが、更新には次のような 非破壊的変更 が含まれる場合があります。

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

B2C Commerce では、新機能をデプロイする際にローリングリリース戦略を使用します。Production (本番) 環境で新機能を使用する前に、Production (本番) インスタンスグループで必要な B2C Commerce バージョンが実行されていることを確認し、B2C Commerce のデプロイスケジュールを確認して、すべてのインスタンスへのデプロイがいつ予定されているかを判断します。 :::

SCAPI の可用性に関する更新は、Salesforce ステータスで購読できます。

B2C Commerce システムの更新中は、API からメンテナンスレスポンスが返されます。

SCAPI では負荷制限とレート制限が提供されるため、買い物客は常にストアフロントにアクセスできます。

  • 特定の API を使用する詳細なユースケースと例については、開発に記載されているガイドを参照してください。
  • API エンドポイントの各セットの全機能を調べるには、参照資料の仕様を参照してください。