Salesforce Commerce APIを活用したヘッドレスコマース：統合エンジニアのための実践ガイド

背景と応用シーン

Salesforce 統合エンジニアとして、私たちは日々、様々なシステム間のデータ連携やプロセスの自動化という課題に取り組んでいます。特に Eコマースの領域では、顧客体験の多様化に伴い、従来のモノリシックなアーキテクチャから、より柔軟で拡張性の高い Headless Commerce (ヘッドレスコマース) への移行が加速しています。ヘッドレスコマースとは、フロントエンド（顧客が見るUI/UX部分、いわゆる「ヘッド」）とバックエンド（商品管理、在庫、注文処理などのビジネスロジック）を分離するアーキテクチャのことです。

このアプローチにより、企業は単一のウェブサイトだけでなく、カスタムモバイルアプリ、スマートウォッチ、ソーシャルメディア、デジタルサイネージなど、あらゆるチャネルで一貫した購買体験を提供できるようになります。このアーキテクチャの中心的な役割を担うのが、強力な API 群です。

Salesforce Commerce Cloud は、この現代的なニーズに応えるため、堅牢な Salesforce Commerce API を提供しています。この API を活用することで、統合エンジニアは Commerce Cloud の強力なバックエンド機能を、あらゆるフロントエンドや外部システムとシームレスに連携させることが可能になります。例えば、以下のような応用シーンが考えられます。

カスタムフロントエンド開発：React や Vue.js といった最新のフレームワークで構築された、独自のブランド体験を提供するウェブサイトや PWA (Progressive Web App) のバックエンドとして Commerce Cloud を利用する。
モバイルアプリケーション連携：iOS/Android ネイティブアプリから商品検索、カート追加、決済までの一連の購買フローを Commerce API 経由で実現する。
外部システム連携：ERP (Enterprise Resource Planning) や PIM (Product Information Management) といった基幹システムと商品・在庫・注文データをリアルタイムで同期する。
IoT コマース：スマート冷蔵庫からの消耗品自動再注文や、コネクテッドカーからのサービス購入など、新しいチャネルでの購買体験を創出する。

本記事では、Salesforce 統合エンジニアの視点から、この Salesforce Commerce API の基本原理を解説し、具体的なコード例を交えながら、その活用方法と実装時の注意点について詳しく掘り下げていきます。

原理説明

Salesforce Commerce API は、Salesforce Platform 上に構築された RESTful API の集合体であり、B2C および B2B Commerce の両方の機能にアクセスするために設計されています。これは、以前から存在した B2C Commerce 固有の OCAPI (Open Commerce API) とは異なり、Salesforce Core Platform の標準的な機能（例えば、接続アプリケーションによる認証やガバナ制限など）と深く統合されている点が大きな特徴です。

統合エンジニアとして理解すべき主要なコンセプトは以下の通りです。

APIの種類

Commerce API は、主に以下のカテゴリに分類されます。

Shopper API群：顧客向けの体験を構築するための API です。商品検索、商品詳細の取得、バスケット（カート）操作、チェックアウト、注文履歴の確認などが含まれます。ヘッドレスコマースのフロントエンドが直接呼び出すのは、主にこの API 群です。
Data API群：Commerce Cloud のデータを管理・操作するための API です。外部システムとのデータ同期（例：PIM から商品データをインポート、ERP へ注文データをエクスポート）などに利用されます。

認証メカニズム

API へのアクセスには、Salesforce の標準的な認証・認可の仕組みである Connected App (接続アプリケーション) と OAuth 2.0 を利用します。統合シナリオに応じて、適切なフローを選択する必要があります。

Guest Shopper Flow (ゲスト顧客フロー): ログインしていない顧客が商品を閲覧したり、カートに商品を追加したりする際に使用します。クライアントクレデンシャルと公開されている Shopper API を組み合わせて、一時的なゲスト顧客トークンを取得します。
Registered Shopper Flow (登録済み顧客フロー): ログイン済みの顧客が注文履歴の確認や個人情報の変更などを行う際に使用します。Authorization Code and Credentials Flow などを利用して、顧客個別のアクセストークンを取得します。
Server-to-Server Integration (サーバー間連携): バックエンドシステム間でデータを同期する場合など、ユーザーの介在なしに API を呼び出す際に使用します。JWT Bearer Flow や Client Credentials Flow を利用してアクセストークンを取得します。

本記事では、特にサーバー間連携やゲスト顧客向けのシナリオで基本となる、OAuth 2.0 Client Credentials Flow を用いたアクセストークンの取得方法と、そのトークンを利用した API コールについて解説します。

サンプルコード

ここでは、Salesforce Commerce API を利用する際の基本的なステップを、公式ドキュメントに基づいたコード例と共に解説します。

1. アクセストークンの取得 (OAuth 2.0 Client Credentials Flow)

まず、API を呼び出すために必要な Bearer トークンを取得します。これには、事前に設定した Connected App の Consumer Key (Client ID) と Consumer Secret (Client Secret) が必要です。

# HTTPリクエストの例 (cURLを使用)
# POSTリクエストをSalesforceのトークンエンドポイントに送信します。

curl -X POST https://MyDomainName.my.salesforce.com/services/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=YOUR_CONSUMER_KEY" \
-d "client_secret=YOUR_CONSUMER_SECRET"

詳細な注釈：

https://MyDomainName.my.salesforce.com/services/oauth2/token: あなたの Salesforce 組織の認証エンドポイントです。MyDomainName の部分は組織の「私のドメイン」に置き換えてください。
grant_type=client_credentials: OAuth 2.0 の Client Credentials Flow を使用することを示します。これはサーバー間の認証に適しています。
client_id: Connected App の Consumer Key を指定します。
client_secret: Connected App の Consumer Secret を指定します。

このリクエストが成功すると、以下のような JSON レスポンスが返却されます。この中の access_token の値を後続の API リクエストで使用します。

{
    "access_token": "00D....!...",
    "signature": "...",
    "scope": "...",
    "instance_url": "https://MyDomainName.my.salesforce.com",
    "id": "...",
    "token_type": "Bearer",
    "issued_at": "..."
}

2. 商品情報の検索

取得したアクセストークンを使用して、特定の商品を検索する API を呼び出します。ここでは、"shirt" というキーワードで商品を検索する例を示します。

# GETリクエストを商品検索エンドポイントに送信します。

curl -X GET 'https://MyDomainName.my.salesforce.com/services/data/v58.0/commerce/webstores/YOUR_WEBSTORE_ID/products?q=shirt' \
-H "Authorization: Bearer 00D....!..."

詳細な注釈：

/services/data/v58.0/commerce/...: Commerce API のエンドポイントです。v58.0 は API バージョンを示します。常に最新バージョンを確認することが推奨されます。
YOUR_WEBSTORE_ID: 対象となる Webstore (B2C ストアなど) の ID を指定します。
?q=shirt: クエリパラメータで検索キーワードを指定します。
-H "Authorization: Bearer 00D....!...": HTTP ヘッダーに、ステップ1で取得したアクセストークンを "Bearer" スキーマで指定します。これが認証情報となります。

3. バスケット（カート）への商品追加

次に、特定の商品をバスケットに追加します。これには POST リクエストを使用します。

# POSTリクエストをバスケットアイテム追加エンドポイントに送信します。

curl -X POST 'https://MyDomainName.my.salesforce.com/services/data/v58.0/commerce/webstores/YOUR_WEBSTORE_ID/baskets/YOUR_BASKET_ID/items' \
-H "Authorization: Bearer 00D....!..." \
-H "Content-Type: application/json" \
-d '{
  "items": [
    {
      "productId": "01t....",
      "quantity": 2,
      "type": "Product"
    }
  ]
}'

詳細な注釈：

/baskets/YOUR_BASKET_ID/items: どのバスケットに商品を追加するかを指定します。YOUR_BASKET_ID は事前に作成または取得したバスケットの ID です。
-H "Content-Type: application/json": リクエストボディが JSON 形式であることを示します。
-d '{...}': リクエストボディです。追加したい商品の ID (productId) と数量 (quantity) を JSON 形式で指定します。

これらのサンプルは、Salesforce Commerce API の基本的な利用フローを示しています。実際の連携開発では、これらの API を組み合わせて複雑なビジネスロジックを構築していくことになります。

注意事項

Commerce API を用いた統合を設計・実装する際には、いくつかの重要な点に注意する必要があります。

権限 (Permissions)

API 経由で実行できる操作は、Connected App に関連付けられたユーザーのプロファイルや権限セットに依存します。例えば、商品を検索する権限はあっても、注文を作成する権限がないユーザーで認証した場合、注文作成 API は失敗します。最小権限の原則に従い、連携に必要な最小限の権限のみを付与した専用の連携ユーザーを作成することがベストプラクティスです。

API 制限 (API Limits)

Salesforce Platform 上に構築されているため、Commerce API のコールも組織の合計 API リクエスト制限（24時間あたりのコール数）にカウントされます。大量のデータを扱うバッチ処理や、トラフィックの多いヘッドレスサイトを構築する際は、この制限を考慮する必要があります。API コールを効率化するための工夫（バルク処理、必要なフィールドのみを問い合わせる、など）や、CDN (Content Delivery Network) を利用したキャッシュ戦略が不可欠です。

エラー処理 (Error Handling)

統合エンジニアにとって、堅牢なエラー処理は最も重要な責務の一つです。API コールが失敗した場合、HTTP ステータスコード（例: 400 Bad Request, 401 Unauthorized, 404 Not Found）と、レスポンスボディに含まれるエラー詳細（JSON 形式）を適切に解析し、ログに記録したり、リトライ処理を行ったりするロジックを実装する必要があります。特にアクセストークンの有効期限切れ（401 Unauthorized）を検知し、トークンを再取得してからリクエストを再試行する仕組みは、多くの連携で必須となります。

バージョニング (Versioning)

API エンドポイントにはバージョン番号（例: /v58.0/）が含まれています。Salesforce は定期的に API をバージョンアップするため、将来的な互換性を維持するためにも、特定のバージョンを明示的に指定して開発することが重要です。新しいバージョンがリリースされた際には、変更点を確認し、計画的にアップグレードを行う必要があります。

まとめとベストプラクティス

Salesforce Commerce API は、現代の多様な顧客接点に対応するヘッドレスコマースを実現するための強力なツールです。統合エンジニアとしてこの API を最大限に活用するためには、そのアーキテクチャと Salesforce Platform の基本原則を深く理解することが求められます。

最後に、成功する Commerce API 統合のためのベストプラクティスをいくつか挙げます。

Named Credentials (指定ログイン情報) の活用
Salesforce 内から外部 API を呼び出す、あるいは Commerce API を呼び出す場合、API キーやクライアントシークレットをコード内にハードコーディングするのではなく、Salesforce の「指定ログイン情報」機能を利用して、認証情報を安全に管理・抽象化しましょう。
キャッシュ戦略の導入
特に商品カタログのような、頻繁には変更されないがアクセスが集中するデータについては、API ゲートウェイや CDN、あるいは連携先のミドルウェアでキャッシュを実装し、Commerce Cloud への API コール数を削減しましょう。これにより、パフォーマンス向上と API 制限の消費抑制の両方を実現できます。
包括的なロギングとモニタリング
すべての API リクエストとレスポンス（成功・失敗ともに）を詳細にログとして記録する仕組みを構築してください。リクエスト ID、タイムスタンプ、エンドポイント、ステータスコードなどを記録することで、問題発生時の原因究明が格段に容易になります。
冪等性（Idempotency）の考慮
注文作成のような重要な操作を行う POST リクエストでは、ネットワークエラーなどによるリトライで同じ注文が二重に作成されてしまうリスクがあります。API が冪等性を保証していない場合は、連携クライアント側で一意のトランザクション ID を付与するなど、重複実行を防ぐための工夫が必要です。

Salesforce Commerce API は、単なる機能の提供に留まらず、ビジネスの俊敏性と拡張性を高めるための戦略的な基盤です。このガイドが、皆さんの統合プロジェクトの一助となれば幸いです。

にゃんこのSalesforce日記

このブログを検索