※ これから記載する事項は、私が所属する会社とは一切関係のない事柄です。

この記事はヘッドレス API の使い方のシリーズの一つです。その他の記事は下記を参照してください。

今回は SCAPI プライベートクライアントを利用したショッパー系 API の呼び方を紹介したいと思います。

データ系とショッパー系の違いについては「データ系 API 編」を参照してください。

クライアントタイプ

SCAPI のショッパー系の API の認証する際には２つのクライアントタイプがあります。

プライベートクライアント ・・・クライアントシークレットを安全に保管しておけるアプリケーション。例えば、主な処理をサーバー側で行うような従来型のウェブアプリケーションや backend-for-frontend (BFF) を持つウェブまたはモバイルアプリケーション
パブリッククライアント ・・・クライアントシークレットを安全に保管しておけないアプリケーション。例えば、シングルページアプリケーションやネイティブアプリ

この記事では、SCAPI のプライベートクライアントで３つの顧客タイプが商品をカートに追加するユースケースを説明します。

ゲストユーザ ・・・ログインしていないユーザ
登録済みユーザ(B2C Login) ・・・ B2C Commerce に登録済みユーザ
登録済みユーザ(Federated Login) ・・・ Google や Facebook といったIDプロバイダーを利用して(Federated Login)ログインしたユーザ

ショッパー系APIの呼び方

1. API クライアントの作成

「API クライアントの作成」と同様なので割愛

2. スコープの設定

「スコープの設定」と同じ手順だが、で 「データ」 ではなく、 「ストアフロント」 を選択。

3. (Federated Login のために) Google OAuth2.0 の設定

現状 SLAS でサポートされている IDP はこちらを確認してください。

Google Cloud Platformの認証情報ページへ遷移
画面上部の [+認証情報を作成] をクリックし、リストから [OAuthクライアントIDの作成} をクリックし、タブからアプリケーションの種類として 「ウェブアプリケーション」 を選択。
任意の名前を入力し、さらに承認済みのリダイレクト URI にhttps://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/{IDPID}のフォーマットのURLを入力し保存します。
- IDPID は 「4.(Federated Loginのために) IDP を登録」 で説明した IDP の登録時に設定する ID ですが、ここでは google としておきます。
- shortCode、tenantID、orgID、siteID、realmID については「B2C Commerce に関わる ID を把握」を参照してください。

4. (Federated Loginのために) IDP を登録

下記のようなリクエストを行います

REQUEST:
PUT /shopper/auth-admin/v1/tenants/{tenantID}/idps/{IDPID} HTTP/1.1
Host: {shortCode}.api.commercecloud.salesforce.com
Authorization: Bearer {token}
Content-Type: application/json

REQUEST BODY:
{
  "name": "{IDPID}",
  "clientId": "{googleClientID}",
  "clientSecret": "{googleClientSecret}",
  "authUrl": "https://accounts.google.com/o/oauth2/auth",
  "tokenInfoUrl": "https://www.googleapis.com/oauth2/v3/tokeninfo",
  "userInfoUrl": "https://www.googleapis.com/oauth2/v3/userinfo",
  "tokenUrl": "https://oauth2.googleapis.com/token",
  "redirectUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/{IDPID}",
  "preferenceValue": true
}

5. SLAS テナントの登録

「Create a SLAS Client」を行ってください。
この際に、 [Private?] の値を true に [Redirect URI] の値にコールバックで処理する自身のアプリケーションのエンドポイントを設定してください。(例：http://localhost:3000/callback)

この時生成した Client Id と Secret をメモしておいてください。

6. アクセストークンの取得

ゲストユーザ

下記のようなリクエストを行い、レスポンスボディの中から access_token を取得します。
- credential は 「5. SLASテナントの登録」 で取得した clientId と secret で、それらを clientId:secret のようにコロン(:)で結合したものを Base64 でエンコードした値です。

REQUEST: 
POST /shopper/auth/v1/organizations/{orgID}/oauth2/token HTTP/1.1
Host: {shortCode}.api.commercecloud.salesforce.com 
Authorization: Basic {credential}
Content-Type: application/x-www-form-urlencoded 

REQUEST PARAMETER: 
grant_type=client_credentials

登録済みユーザ(B2C Login)

まずは下記のようなリクエストでユーザーがログインをする。
- redirectUri はコールバックで処理する自身のアプリケーションのエンドポイントを入力
- code_challenge は code_verifier という 43 ～ 128 文字の文字列を SHA256 でハッシュ化したものを入力。（ロジックは公開されている Postman コレクションの Pre-request Script を参照）
- usid はゲストユーザのトークン取得時のレスポンスボディにある usid に値を入力
- userCredential はユーザ ID / パスワード、それらを id:passwordのようにコロン(:)で結合したものを Base64 でエンコードした値です。

REQUEST: 
POST /shopper/auth/v1/organizations/{orgID}/oauth2/login HTTP/1.1
Host: {shortCode}.api.commercecloud.salesforce.com 
Authorization: Basic {userCredential}
Content-Type: application/x-www-form-urlencoded 

REQUEST PARAMETER: 
grant_type=client_credentials
&client_id={clientID}
&redirect_uri={redirectUri}
&channel_id={siteID}
&code_challenge={codeChallenge}
&usid={usid}

上記のリクエストをすると HTTP ステータスが 303 でレスポンスヘッダーの Location に {redirectUri}/callback?usid={}&state={}&scope=openid%20offline_access&code={} のフォーマットでURLが入っているので、その URL にブラウザでリダイレクトさせる。
自身のアプリケーションで、/callback を実装し、code の値を利用して下記のリクエストを行い、レスポンスボディ内の access_token を取得
- code_verifier は code_challenge 生成時に利用した文字列。（ロジックは公開されているPostmanコレクションの Pre-request Script を参照）
- code はリダイレクト先 URL のパラメータに入っている code を入力

REQUEST: 
POST /shopper/auth/v1/organizations/{orgID}/oauth2/token HTTP/1.1
Host: {shortCode}.api.commercecloud.salesforce.com 
Authorization: Basic {credential}
Content-Type: application/x-www-form-urlencoded 

REQUEST PARAMETER: 
grant_type=authorization_code_pkce
&client_id={clientID}
&redirect_uri={redirectUri}
&code_verifier={codeVerifier}
$code={code}

登録済みユーザ(Federated Login)

まずは下記のようなリクエストでユーザーがログインをする。
- IDPID は 「4.(Federated Loginのために) IDP を登録」 で作成した IDPID。今回は google

REQUEST: 
GET /shopper/auth/v1/organizations/{orgID}/oauth2/authorize
?redirect_uri={redirect_url}
&response_type=code
&client_id={clientID}
&hint={IDPID}
&channel_id={siteID}
&usid={usid} HTTP/1.1
Host: {shortCode}.api.commercecloud.salesforce.com

上記のリクエストをすると HTTP ステータスが 303 でレスポンスヘッダーの Location に{https://accounts.google.com/o/oauth2/auth?scope=openid%20email%20profile&response_type=code&client_id={}&redirect_uri={}&state={}のフォーマットで URL が入っているので、その URL にブラウザでリダイレクトさせる。
すると画像のように Google のログイン画面に遷移するので、ログイン。

Google Cloud Platform の OAuth 同意画面ページで公開ステータスを「テスト」でテストユーザを設定している場合は、そのユーザでログインしてください。

ログイン成功すると http://localhost:3000/callback?usid={}&code={}のフォーマットの URL にブラウザでリダイレクトさせる。
自身のアプリケーションで、/callback を実装し、code の値を利用して下記のリクエストを行い、レスポンスボディ内の access_token を取得

REQUEST: 
POST /shopper/auth/v1/organizations/{orgID}/oauth2/token HTTP/1.1
Host: {shortCode}.api.commercecloud.salesforce.com 
Authorization: Basic {credential}
Content-Type: application/x-www-form-urlencoded 

REQUEST PARAMETER: 
grant_type=authorization_code
&redirect_uri={redirectUri}
&code={code}

7. ショッパー系 API を呼ぶ

下記のようにサンプルとして /baskets を呼ぶ。
token に上記 3 つのパターンのいずれかで取得したアクセストークンを入力しリクエストすると無事 200 で返ってくる。

その他のAPIについては SCAPI の API ドキュメントの「Shopper〜」から始まっているものを参照ください。

REQUEST:
POST /checkout/shopper-baskets/v1/organizations/{orgID}/baskets
?siteId={siteID} HTTP/1.1
Host: {shortCode}.api.commercecloud.salesforce.com
Authorization: Bearer {token}
Content-Type: application/json

REQUEST BODY:
{}