Salesforce Commerce Cloud OCAPI完全攻略：開発者向けヘッドレス連携ガイド

背景と適用シナリオ

現代のEコマース環境は、単一のウェブサイトにとどまらず、モバイルアプリ、ソーシャルメディア、IoTデバイス、デジタルサイネージなど、多岐にわたる顧客接点（タッチポイント）で一貫したショッピング体験を提供することが求められています。このような要求に応えるためのアーキテクチャとして、Headless Commerce (ヘッドレスコマース) が急速に注目を集めています。ヘッドレスコマースとは、フロントエンド（顧客が見る画面）とバックエンド（商品管理、注文処理などのビジネスロジック）を分離するアプローチです。

このアーキテクチャを実現する上で中核となるのが、強力なAPIです。Salesforce Commerce Cloud (以下、Commerce Cloud) は、このニーズに応えるために OCAPI (Open Commerce API、オープンコマースAPI) という堅牢なRESTful API群を提供しています。私はSalesforce開発者として、多くのプロジェクトでOCAPIを活用し、標準のストアフロントの枠を超えたユニークな顧客体験を構築してきました。

OCAPIの主な適用シナリオは以下の通りです。

1. カスタムフロントエンドの構築

React, Vue.js, Angularなどの最新のJavaScriptフレームワークを使用して、完全に独自のユーザーインターフェース（UI）とユーザーエクスペリエンス（UX）を持つストアフロントを構築します。これにより、ブランドの世界観を最大限に表現し、パフォーマンスを極限まで最適化することが可能になります。

2. ネイティブモバイルアプリの開発

iOSやAndroid向けのネイティブアプリから、Commerce Cloudの商品情報の検索、カートへの追加、決済処理などを直接呼び出すことができます。アプリならではのプッシュ通知や位置情報連携といった機能とEコマース機能をシームレスに統合できます。

3. 外部システムとの連携

外部のCMS (コンテンツ管理システム) で管理されているブログ記事やマーケティングコンテンツ内に、OCAPI経由で取得した商品情報を動的に埋め込むことができます。また、POS (Point of Sale) システムや社内基幹システムと注文データや顧客データを連携させる際にも活用されます。

本記事では、Salesforce開発者の視点から、OCAPIの基本的な仕組みと、その活用方法について、具体的なコード例を交えながら詳しく解説していきます。

原理の説明

OCAPIは、Commerce Cloudのプラットフォーム機能にHTTP経由でアクセスするための標準的なインターフェースです。その設計はREST (Representational State Transfer) の原則に準拠しており、リソースはURLで表現され、そのリソースに対する操作はHTTPメソッド (GET, POST, PUT, PATCH, DELETE) で行います。データ形式は主にJSONが使用されます。

OCAPIは、その目的別に大きく3種類のAPIファミリーに分かれています。

1. Shop API

顧客向けの操作、つまりストアフロントで発生するであろうアクションを網羅するAPI群です。例えば、商品検索、商品詳細の取得、バスケット（カート）の操作、顧客登録、ログイン、注文作成などが含まれます。主にカスタムフロントエンドやモバイルアプリから利用されます。

2. Data API

Commerce Cloudのビジネスオブジェクト（カタログ、商品、在庫、価格表、顧客リスト、注文など）への直接的なアクセスと操作を提供します。これは主に、バックオフィス業務や外部システムとのデータ同期、バッチ処理など、管理者向けの用途で使用されます。Shop APIよりも広範なデータへのアクセス権限を持ちます。

3. Meta API

Shop APIおよびData APIで利用可能なリソースやドキュメントを動的に取得するためのAPIです。APIのバージョンごとにどのようなエンドポイントが利用可能か、各エンドポイントがどのような属性をサポートしているかといったメタ情報をプログラムから確認できます。

これらのAPIを利用するには、まずCommerce Cloudの管理画面である Business Manager (ビジネス・マネージャー) でAPIクライアントの設定を行う必要があります。ここでクライアントIDを発行し、そのクライアントにどのAPI（Shop/Data）のどのリソースに対して、どのHTTPメソッド（読み取り/書き込み）を許可するかを詳細に設定します。

認証には OAuth 2.0 が採用されています。APIリクエストを行う前に、まず認証エンドポイントに対してクライアントIDとシークレットを使ってリクエストを送信し、Access Token (アクセストークン) を取得します。その後、取得したアクセストークンをHTTPリクエストのAuthorizationヘッダーに含めることで、各APIエンドポイントへのアクセスが許可されます。この仕組みにより、安全なAPI通信が保証されます。

示例代码

ここでは、最も一般的なシナリオの一つである、Shop APIを使用して特定の商品情報を取得するプロセスをコード例と共に示します。cURLコマンドを使用した例ですが、どのプログラミング言語でも同様のHTTPリクエストを実装することで実現できます。

ステップ1: アクセストークンの取得

OCAPIを呼び出す前に、認証を行いBearerトークンを取得する必要があります。これは、Business Managerで設定したAPIクライアントIDを使用して、`oauth2/access_token` エンドポイントにPOSTリクエストを送信することで行います。

注: 以下のコードはSalesforce公式ドキュメントで解説されている認証フローに基づいています。

# B2C Commerceテナントの認証サーバーにPOSTリクエストを送信
# {your_hostname} は、e.g., "zzrl-001.dx.commercecloud.salesforce.com" のようなインスタンスのホスト名に置き換える
# {your_client_id} はBusiness Managerで設定したAPIクライアントのIDに置き換える

curl -X POST \
  https://{your_hostname}/dw/oauth2/access_token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -u '{your_client_id}:{your_client_password}' \
  -d 'grant_type=client_credentials'

成功すると、以下のようなJSONレスポンスが返ってきます。この中の `access_token` の値を次のステップで使用します。

{
    "access_token": "eyJfdiI6IjIifQ...a_very_long_token_string...",
    "token_type": "Bearer",
    "expires_in": 1799
}

ステップ2: 商品情報の取得

取得したアクセストークンを使用して、Shop APIのProductsリソースにGETリクエストを送信し、商品情報を取得します。`Authorization` ヘッダーに `Bearer {access_token}` の形式でトークンを指定することが重要です。

注: 以下のコードは `developer.salesforce.com` の `Products Resource` に関するドキュメントに基づいています。

# Shop APIのProductsエンドポイントにGETリクエストを送信
# {your_hostname} はインスタンスのホスト名
# {your_site_id} は対象となるサイトのID (e.g., "RefArch")
# v23_1 の部分はAPIバージョン。常に最新の安定版を指定することが推奨される
# {product_id} は取得したい商品のID (e.g., "25595225M")
# {your_access_token} はステップ1で取得したトークン

curl -X GET \
  'https://{your_hostname}/s/{your_site_id}/dw/shop/v23_1/products/{product_id}?client_id={your_client_id}' \
  -H 'Authorization: Bearer {your_access_token}' \
  -H 'Accept: application/json'

リクエストが成功すると、指定した商品の詳細情報がJSON形式で返されます。以下はレスポンスの一例です。

{
    "id": "25595225M",
    "name": "Long Sleeve T-Shirt",
    "currency": "USD",
    "price": 39.99,
    "long_description": "A comfortable long sleeve t-shirt, perfect for layering.",
    "image_groups": [
        {
            "images": [
                {
                    "alt": "Long Sleeve T-Shirt, , large",
                    "link": "https://.../images/large/PG.10221714.JJ864XX.PZ.jpg",
                    "title": "Long Sleeve T-Shirt, "
                }
            ],
            "view_type": "large"
        }
    ],
    "inventory": {
        "ats": 100,
        "orderable": true,
        "preorderable": false,
        "stock_level": 100
    },
    "type": {
        "master": true
    },
    "variants": [
        {
            "orderable": true,
            "price": 39.99,
            "product_id": "701644329203M",
            "variation_values": {
                "color": "JJ864XX",
                "size": "9LG"
            }
        }
        // ... 他のバリエーション
    ]
}

このJSONデータを解析することで、カスタムフロントエンドやモバイルアプリで商品名、価格、画像、在庫状況などを表示することができます。

注意事項

OCAPIを本番環境で安定して利用するためには、いくつかの重要な点に注意する必要があります。

権限 (Permissions)

最も一般的な問題は権限設定の不備です。Business Managerの `Administration > Site Development > Open Commerce API Settings` で、APIクライアントごとにアクセス許可を細かく設定する必要があります。例えば、商品情報を読み取るだけなら、`Shop API` の `products` リソースに対して `GET` のみを許可します。必要最小限の権限を付与する「最小権限の原則」に従うことがセキュリティ上、非常に重要です。

API制限 (API Limits)

Salesforceプラットフォームの安定性を保つため、OCAPIにはコール数に関する制限（レートリミット）が設けられています。短時間に大量のリクエストを送信すると、`429 Too Many Requests` というステータスコードが返され、一時的にAPIが利用できなくなります。これを避けるため、クライアントアプリケーション側で適切なキャッシュ戦略を実装したり、エラー発生時にリトライ処理（指数バックオフ付き）を組み込んだりする設計が不可欠です。

エラーハンドリング (Error Handling)

API連携では、ネットワークの問題や不正なリクエスト、サーバー側のエラーなど、予期せぬ事態が常に起こり得ます。OCAPIはエラー発生時に、HTTPステータスコードと、問題の詳細を記述したFaultドキュメント（JSON形式）を返します。例えば、`401 Unauthorized` はトークンが無効であることを、`404 Not Found` はリソースが見つからないことを示します。アプリケーション側でこれらのレスポンスを適切に解釈し、ユーザーに分かりやすいフィードバックを返したり、ログに記録したりする処理を必ず実装してください。

バージョン管理 (Versioning)

OCAPIのエンドポイントURLには `vYY_M` (e.g., `v23_1`) という形式でバージョンが含まれています。Salesforceは定期的にAPIをアップデートしますが、下位互換性が保証されない変更が含まれることもあります。APIバージョンをURLに明示的に含めることで、将来のアップデートによって既存の連携が突然壊れることを防げます。新しいバージョンがリリースされた際は、ドキュメントで変更点を確認し、計画的に移行作業を行うことが推奨されます。

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

Salesforce Commerce CloudのOCAPIは、開発者がヘッドレスコマースや高度なシステム連携を実現するための強力なツールです。その柔軟性と拡張性により、企業は顧客に対して独自のデジタル体験を提供し、競争優位性を築くことができます。

最後に、開発者としてOCAPIを扱う上でのベストプラクティスをいくつか紹介します。

適切なAPIの選択:
顧客体験に関わる機能はShop APIを、バックエンドのデータ操作はData APIをと、用途に応じて明確に使い分けることが重要です。
ペイロードの最適化:
レスポンスに含まれるデータ量を減らすため、`fields` パラメータを使用して必要な項目だけを取得するようにしましょう。また、関連データを一度に取得したい場合は `expand` パラメータを慎重に利用します。
キャッシュ戦略の導入:
商品カタログなど、頻繁に更新されないデータはクライアント側や中間層でキャッシュすることで、APIコール数を削減し、パフォーマンスとユーザー体験を向上させることができます。
認証情報の安全な管理:
APIクライアントのIDとパスワードは機密情報です。ソースコードにハードコーディングせず、サーバーの環境変数やセキュアな認証情報管理サービス（AWS Secrets Manager, Azure Key Vault 등）を利用して安全に保管してください。
ドキュメントの活用:
Salesforce Developer Centerには、OCAPIの各エンドポイントに関する詳細なドキュメントとAPIエクスプローラーが用意されています。開発を始める前に、必ず公式ドキュメントに目を通し、仕様を正確に理解することが成功への近道です。

この記事が、Commerce Cloudでの開発に取り組む皆様の一助となれば幸いです。

にゃんこのSalesforce日記

このブログを検索