B2C Commerce API 入門ガイド

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

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 リクエストとレスポンスの相関の詳細については、リクエストとレスポンスの特定を参照してください。

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

  • バニティドメインを使用するように設定された Staging (ステージング) 環境で B2C Commerce API を使用する場合は、Staging (ステージング) 用の eCDN を設定する必要があります。
  • 可用性を確保し、サービス妨害攻撃から顧客を保護するために、一部の B2C Commerce API へのリクエストにはレート制限が設けられています。各ファミリーの API がどのように制限されているかは、レート制限を参照してください。
  • パフォーマンスを向上させるため、Shopper API ファミリーのリクエストは、トークンの一意の買い物客 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 では、新機能をデプロイする際にローリングリリース戦略を使用します。本番環境で新機能を使用する前に、本番インスタンスグループで必要な B2C Commerce バージョンが実行されていることを確認し、B2C Commerce のデプロイスケジュールを確認して、すべてのインスタンスにデプロイする予定の時期を決定します。

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

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

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

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