パートナーAPI

OAuth2.0認証

📘

OAuth 2.0は、/adsエンドポイントでのみ使用できます

APIを介して注文のレポートを統合する場合は、/ordersエンドポイントを基本認証および秘密のAPIキーと統合する必要があります。

クライアントIDおよびクライアントシークレット

先ほどの client_id と client_secret は、テクニカルアカウントマネージャーから提供されます。クライアントシークレットはプライベートなものであり、共有しないでください。

アクセストークンのリクエスト

アクセストークンを取得するには、 client_id と client_secretを含むリクエストを送信する必要があります。そのために小売業者は、CitrusAd認可サーバーのエンドポイントにPOSTリクエストを行う必要があります。

https://$BASE_URL/v1/oauth2/token

📘

/oauth2/token 該当するトークンだけが提供されます。これらのトークンを使用して、さまざまな統合エンドポイントとやり取りすることになります。

リクエストにはBasic認証が必要であり、これは、小売業者の client_id と client_secret をbase64エンコードしたものを含む、Authorizationリクエストヘッダーを介して送信されます。

Authorization: "Basic" + base64encode(client_id + ":" + client_secret)

HTTPリクエスト本文に application/x-www-form-urlencoded の形式で以下のパラメータを追加する必要があります。

grant_type=client_credentials

リクエストは以下のようになります。

POST https://$BASE_URL/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64 encoded id+key>
grant_type=client_credentials

アクセストークンの受信

レスポンスには以下の情報が含まれます

  • access_token：CitrusAdのAPIを呼び出す際に使用するアクセストークン
  • expires_in：アクセストークンの有効期限までの時間（秒）
  • token_type：返されたトークンのタイプです。この場合、常にBearerとなります

レスポンス例は以下の通りです

{
  "access_token": "xxxxx.yyyyy.zzzzz",
  "expires_in": 3600,
  "token_type": "Bearer"
}

トークンの使用

生成したアクセストークンをリクエストのAuthorizationヘッダーに追加するだけで、CitrusAd APIのエンドポイントに対して呼び出しが実行されます
Authorization: “Bearer “ <access_token>

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Bearer <access_token>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
         ["category:Cupboard/Snacks"]
    ],
    "options": {
                             "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3
}

リクエストエラー

無効なクライアント

リクエストで送信された client_id や client_secret が正しくない場合、次のようなレスポンスが返されます。

{
  "error": "invalid_client"
}

正しい認証情報を使用していることを確認します。 client_id と client_secret を再確認し、/tokenエンドポイントを呼び出すときにBasic認証を正しく使用していることを確認してください。
##無効なリクエスト
リクエストに必須パラメータがない場合や、無効なパラメータ値が含まれている場合、パラメータが複数回含まれている場合、またはその他の不正な形式の場合には、無効なリクエストエラーが認可サーバーから返されます。

{
  "error": "invalid_request"
}

次を確認します。

  • リクエスト本文に grant_type=client_credentials のみ含めます
  • リクエストヘッダーに正しい Content-Type を設定します