B2C Commerce API 入門ガイド

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

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

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

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

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

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

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

SCAPI は Shopper API と Admin API の 2 つの主要な API グループで構成されており、使用する API はアプリケーションによって異なります。Shopper API グループは、商品の閲覧、買い物カゴの管理、注文手続きなど、顧客向けの機能用に設計されています。Admin 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 ガイドを参照してください。

オープンソースの JavaScript SDK は npm で利用でき、デベロッパーが作業を開始するのに役立ちます。

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

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

B2C Commerce API を使用してストアフロントを構築したいデベロッパー向けに、コンポーザブルストアフロントソリューションを提供しています。詳細については、コンポーザブルストアフロントのドキュメントを参照してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Salesforce ステータスで B2C Commerce API の可用性に関する更新をサブスクライブできます。

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

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

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