ヘルプ

目次

各種申請に関するヘルプ（ショッピングAPIを利用したい）

• 各種申請に関するヘルプ（ショッピングAPIを利用したい）

ショッピングAPI導入までの流れ

• ショッピングAPI導入までの流れについて
• ショッピングAPIのサンプルコードについて

「Yahoo! ID連携」に関連するヘルプ

• アクセストークンの取得方法（v2）

「公開鍵認証」に関連するヘルプ

• 公開鍵認証について
• 「公開鍵」による認証について
• 公開鍵認証が利用可能（有効）なAPI
• 公開鍵認証の申請方法
• 公開鍵の有効期限について
• 公開鍵の更新方法について
• 公開鍵の利用方法
• テスト環境での公開鍵の利用について

テスト環境に関連するヘルプ

• テスト環境に関連するヘルプ

Yahoo! ショッピングAPI共通エラーコードについて

• Yahoo! ショッピングAPI共通エラーコード一覧

よくあるご質問

• 「Client ID（アプリケーションID）」はどこで確認ができますか？
• リクエスト元IPの変更・追加について
• APIのコール数制限緩和について
• テスト環境の利用申請をしたが、メールが届かない。
• リフレッシュトークンの有効期限切れ前に再認可について
• 各種申請の承認を早めてほしい

---

各種申請に関するヘルプ（ショッピングAPIを利用したい）

各種申請に関するヘルプは以下リンクからご覧ください。

• 各種申請に関するヘルプ（ショッピングAPIを利用したい）

ショッピングAPI導入までの流れ

ショッピングAPI導入までの流れについて

詳細はこちらのページをご確認ください。

ショッピングAPIのサンプルコードについて

PHP版のサンプルコードをご用意しております。
※恐れ入りますが、その他言語のサンプルの用意はございません。

• Yahoo!ID連携（アクセストークン取得）
  https://developer.yahoo.co.jp/webapi/shopping/help/#accesstoken
• 注文API
  https://developer.yahoo.co.jp/webapi/shopping/order/sample.html
• 定期購入API
  https://developer.yahoo.co.jp/webapi/shopping/subscription/sample.html
• 商品API
  https://developer.yahoo.co.jp/webapi/shopping/item/sample.html
• 在庫API
  https://developer.yahoo.co.jp/webapi/shopping/stock/sample.html
• 画像API
  https://developer.yahoo.co.jp/webapi/shopping/image/sample.html

「Yahoo! ID連携」に関連するヘルプ

アクセストークンの取得方法（v2）

トークン取得の流れ

　
1. 「Authorizationエンドポイント」にリクエストする。
2. リダイレクトされたペ－ジのパラメータから「認可コード（code）」を取得する。
3. 「Tokenエンドポイント」にリクエストをしてトークン情報を取得する。
   ※トークン情報の中に"アクセストークン"が含まれます。

1. 「Authorizationエンドポイント」にリクエストする。

   「Authorizationエンドポイント」にリクエストをします。
   例）"redirect_uri"に「https://www.yahoo.co.jp/」を指定した場合

   https://auth.login.yahoo.co.jp/yconnect/v2/authorization?response_type=code&client_id=<Client ID（アプリケーションID）>&redirect_uri=https%3A%2F%2Fwww.yahoo.co.jp%2F&scope=openid+profile&bail=1

   ご注意ください

   "redirect_uri"に指定する値は、Client ID（アプリケーションID）に紐づく「コールバックURL」である必要があります。
   こちらのページから「コールバックURL」をご確認ください。

2. リダイレクトされたペ－ジのパラメータから「認可コード（code）」を取得する。

   認証後、指定したURLにリダイレクトされます。
   その際に下記のようなパラメータを付加しています。

   例）https://www.yahoo.co.jp/?code=abcdefgh
   赤字の部分が「認可コード（code）」です。
   

   認可コードの詳細はこちらをご確認ください。

3. 「Tokenエンドポイント」にリクエストをしてトークン情報を取得する。

   「新規取得」する場合

   2）で取得した「認可コード（code）」をリクエストパラメータ"code"にそのままセットします。

   サンプルコード（PHP）

   <?php
   
     define('APPID',        '＜Client ID（アプリケーションID）＞');
     define('SECRET',       '＜シークレット＞');
     define('CALLBACK_URL', '＜コールバックURL＞');
     define('TOKEN_URL',    'https://auth.login.yahoo.co.jp/yconnect/v2/token');
   
     $header = [
         'Content-Type: application/x-www-form-urlencoded',
         'Authorization: Basic ' . base64_encode(APPID . ':' . SECRET),
     ];
   
     $param = array(
         'code'         => ＜認可コード（code）＞,
         'grant_type'   => 'authorization_code',
         'redirect_uri' => CALLBACK_URL,
     );
   
     // 任意でオプションの追加をしてください。
     $ch = curl_init(TOKEN_URL);
     curl_setopt($ch, CURLOPT_CUSTOMREQUEST,  'POST');
     curl_setopt($ch, CURLOPT_HTTPHEADER,     $header);
     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
     curl_setopt($ch, CURLOPT_POST,           true);
     curl_setopt($ch, CURLOPT_POSTFIELDS,     http_build_query($param));
   
     $response = curl_exec($ch);
     curl_close($ch);
   
     // 任意でレスポンスデータの判定処理を追加してください。
     $token = json_decode($response, true);
   
     // 実行した結果は下記に別枠で記載しております。
     var_dump($token);
   
   ?>

   以下のようなフォーマットでトークン情報が返されます。

   $ php get_token.php
   -----------------------------------------------------------------------------------------------
   Array
   (
       [access_token] => ＜こちらに「アクセストークン」がセットされています。＞
       [token_type] => bearer
       [expires_in] => 3600
       [id_token] => ＜こちらに「アイディートークン」がセットされています。＞
       [refresh_token] => ＜こちらに「リフレッシュトークン」がセットされています。＞
   )

   「更新」する場合

   取得済みのトークン情報には「リフレッシュトークン（refresh_token）」が含まれています。
   リフレッシュトークンをリクエストパラメータ"refresh_token"にセットをして
   「Tokenエンドポイント」にリクエストをしていただくと、更新されたトークン情報が返ってきます。

   サンプルコード（PHP）

   <?php
   
     define('APPID',     '＜Client ID（アプリケーションID）＞');
     define('SECRET',    '＜シークレット＞');
     define('TOKEN_URL', 'https://auth.login.yahoo.co.jp/yconnect/v2/token');
   
     $header = [
         'Content-Type: application/x-www-form-urlencoded',
         'Authorization: Basic ' . base64_encode(APPID . ':' . SECRET),
     ];
   
     // リフレッシュトークンは「新規取得」時のレスポンスに含まれています。
     $param = array(
         'refresh_token'  => ＜リフレッシュトークン＞,
         'grant_type'     => 'refresh_token',
     );
   
     // 任意でオプションの追加をしてください。
     $ch = curl_init(TOKEN_URL);
     curl_setopt($ch, CURLOPT_CUSTOMREQUEST,  'POST');
     curl_setopt($ch, CURLOPT_HTTPHEADER,     $header);
     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
     curl_setopt($ch, CURLOPT_POST,           true);
     curl_setopt($ch, CURLOPT_POSTFIELDS,     http_build_query($param));
   
     $response = curl_exec($ch);
     curl_close($ch);
   
     // 任意でレスポンスデータの判定処理を追加してください。
     $token = json_decode($response, true);
   
   ?>

   リクエストパラメータ"grant_type"にセットする内容で処理が分かれています。
   詳細はこちらをご確認ください。

   grant_type	種別
   authorization_code	新規取得
   refresh_token	更新

公開鍵認証について

「公開鍵」による認証について

公開鍵認証を利用したAPIアクセスで、リフレッシュトークンの有効期限の短縮を抑制

Yahoo! ID連携で取得できる、アクセストークンおよびリフレッシュトークンには発行日時を起点とした有効期限が存在します。

公開鍵認証なしで特定のAPIをリクエストすると、リフレッシュトークンの有効期限が発行から「12時間」と通常よりも短く制限されますが、公開鍵認証を利用することで、制限されず通常通り「4週間」の有効期限でリクエストできます。
特定のAPI以外のリクエストでは、公開鍵認証なしでも有効期限が短く制限されることはありません。

「公開鍵認証」を利用しない場合
特定のAPIのリクエストに限っては、
リフレッシュトークンの有効期限は「12時間」に制限されます。
12時間ごとに再認可をしてトークン情報を更新していただく必要があります。

「公開鍵認証」を利用する場合
リフレッシュトークンの有効期限は「4週間」です。
4週間ごとに再認可をしてトークン情報を更新していただく必要があります。

※再認可・・・Yahoo! JAPAN IDでログインをして「認可コード（code）」を取得します。
※トークン情報・・・アクセストークンとリフレッシュトークンを指します。

リフレッシュトークンの有効期限が切れると

リフレッシュトークンの有効期限が切れると同時にアクセストークンも期限切れの扱いとなるため、以下のようなレスポンスを返します。

<?xml version='1.0' encoding='UTF-8' ?>
<Error>
<Message>AccessToken has been expired. This API session is shorter than another API.</Message>
<Code>px-04102</Code>
</Error>

ご注意ください

• 公開鍵認証の利用は必須ではありません。公開鍵認証なしでもAPIをご利用いただけます。
• 公開鍵認証は一部のAPIのみに有効です。
  ※次項【 公開鍵認証が利用可能（有効）なAPI 】をご確認ください。
• トークンの有効期限を返すようなAPI等の機能は用意しておりません。

公開鍵認証が利用可能（有効）なAPI

「公開鍵認証」は一部のAPIにのみ有効です。

下記APIに限り「公開鍵認証」が利用可能です。
こちらのAPIを利用しない場合は「公開鍵認証」を利用していただく必要はありません。

• 注文検索API
• 注文詳細API
• 注文内容変更API
• メッセージ投稿API
• 質問詳細API
• 質問一覧API
• 定期購入親注文詳細取得API
• 定期購入情報変更API
• 定期購入情報変更履歴詳細API

公開鍵認証なしで上記APIを利用した場合「リフレッシュトークン」の有効期限は「最大12時間」です。

公開鍵認証の申請方法

申請について

公開鍵認証は、Yahoo! ショッピング出店ストアのみ申請が可能です。

公開鍵を希望の方は、「ストアクリエイターPro > 設定 > 暗号鍵管理」からお申し込みください。
申請後すぐに公開鍵の発行が可能となります。

※公開鍵の発行・取得には、「ツール管理権限」が必要です。

公開鍵の有効期限について

公開鍵の有効期限は発行した月より「1年間」です。
公開鍵の有効期限は「ストアクリエイターPro > 設定 > 暗号鍵管理」よりご確認頂けます。

公開鍵の更新方法について

有効期限切れ1，2か月前の計2回メールで通知を行っています。
　メール件名： 【重要】本番環境 ショッピングAPI公開鍵更新のお願い：Yahoo!ショッピング
ご使用になられている公開鍵の有効期限が切れる前に、新しい公開鍵のご発行をお願いいたします。

公開鍵は最大5つまで発行することが可能です。
公開鍵のステータスは最大二つまで有効にすることができます。

※「ツール管理権限」を持った方に通知されます。

詳細については下記ページをご確認ください。
ストアクリエイターPro > 設定 > 暗号鍵管理

公開鍵の利用方法

ご注意ください

• コマースパートナー提供のツールをご利用中の場合は、ツール提供元の指示に従って設定をしてください。
• 「注文API」、「お問い合わせ管理API」または「定期購入API」にリクエストする際のオプションとしてセットしてください。
※上記API以外のリクエスト時に公開鍵を利用した場合、セットされている鍵情報は無視されます。（エラーとして返しません。）

手順

1. 公開鍵ファイルの作成
   
   • public.keyというファイル名で任意のディレクトリにファイルを作成する ( 例 Windowsの場合: C:\Users\store\public.key )
   • 発行した公開鍵の項目で「コピー」をクリックし、作成したファイルに値を貼り付ける
2. 認証情報の作成
   ストアアカウントとunixtimestampを:で結合する。
   
   • unixtimestampは、現在時刻から10分以内のものをご使用下さい。10分以上経過したunixtimestampを利用されると、認証エラーとなります。
3. 2.で作成した認証情報を公開鍵で暗号化します。
   認証情報(sellerId:unixtimestamp)を公開鍵で暗号化(PKCS1PADDING)し、BASE64エンコードする。
4. 暗号化した認証情報をリクエストヘッダーに載せてリクエストする。
   
   • X-sws-signature: 3.で暗号化した認証情報
   • X-sws-signature-version: 1(取得した公開鍵のバージョンを指定)

※１Client ID（アプリケーションID）で複数店舗（ストアアカウント）を管理している場合、
　ストアアカウント毎に鍵発行・作成をお願いいたします。

レスポンス

公開鍵認証の結果は、レスポンスヘッダー(X-SWS-Authorize-Status)で返却されます。

X-SWS-Authorize-Statusの値	結果
authorized	公開鍵認証に成功
none	認証ヘッダー(X-sws-signature)が付与されていない
expired-key-version	指定された公開鍵の有効期限切れ
invalid-key-version	認証キーバージョンヘッダー(X-sws-signature-version)が不正
not-found-key-version	指定された公開鍵バージョンが存在しない
invalid-key-status	指定された公開鍵のステータスが不正
expired-timestamp	認証ヘッダー(X-sws-signature)に付与されているtimestampが有効期限切れ
invalid-timestamp	認証ヘッダー(X-sws-signature)に付与されているtimestampの値が不正
invalid-sellerid	認証ヘッダー(X-sws-signature)に付与されているSellerIdの値が不正
invalid-authorize-value	認証ヘッダー(X-sws-signature)のフォーマットが不正
unauthorized	公開鍵認証に失敗

※APIの実行結果として得られるHTTPステータスコードは、公開鍵認証の結果に依存せず、
　APIの実行結果に準じたコードが返却されます。
　（例：有効期限切れの公開鍵が指定された認証情報を載せて注文詳細APIをリクエストした
　　場合、レスポンスヘッダー(X-SWS-Authorize-Status)へ公開鍵の有効期限切れを示す認証
　　失敗の値が返却されますが、注文詳細API自体の実行が成功している際は、
　　HTTPステータスコードには正常系（200）が返却されます）
※レスポンスボディーについても、HTTPステータスコード同様に公開鍵認証の結果に依存せず、
　APIの実行結果に準じたレスポンスボディーが返却されます。
※公開鍵認証が不要なAPIでは、レスポンスヘッダー(X-SWS-Authorize-Status)は
　返却されません。

サンプルコード（PHP）

<?php

$sellerId = {ストアアカウント};
$publicKeyPath = "./public.key"; //ストアクリエイターPro上で発行した公開鍵のパス ( 例 Windowsの場合: C:\\Users\\store\\public.key ) 
$keyVersion = "1"; //ストアクリエイターPro上で発行した公開鍵のバージョン
 
// 認証情報作成(ストアアカウントとunixtimestampを:で結合する)
$authenticationValue = $sellerId . ":" . time();
 
// 公開鍵の読み込み
$publicKey = openssl_pkey_get_public(file_get_contents($publicKeyPath));
 
// 認証情報の暗号化実行

openssl_public_encrypt($authenticationValue, $encryptedAuthenticationValue, $publicKey);
 
// 認証情報のBase64エンコード実行

$encodedAuthenticationValue = base64_encode($encryptedAuthenticationValue);


 
// リクエストヘッダーの設定

$requestHeaders = array(
        
         "Authorization: Bearer". {アクセストークン},
        
         "X-sws-signature:". $encodedAuthenticationValue,
        
         "X-sws-signature-version:". 1(発行した公開鍵のバージョンを指定)

);


 
// HTTP通信準備

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, {APIのURL});
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $requestHeaders);
curl_setopt($ch, CURLOPT_HEADER, true);
 
// HTTP通信実行
$response = curl_exec($ch);
 
// 結果表示
echo($response);

?>

サンプルコード（Java）

import javax.crypto.Cipher;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.security.KeyFactory;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
​
public class SampleApplication {
​
    public static void main(String arg[]) {
​
        try {
            Path keyFilePath = Paths.get("./public.key");//ストアクリエイターPro上で発行した公開鍵のパス ( 例 Windowsの場合: C:\\Users\\store\\public.key ) 
            String sellerId = {ストアアカウント};
​
            // 現在日時取得
            long unixTime = System.currentTimeMillis() / 1000L;
​
            // 認証情報作成(ストアアカウントとunixtimestampを:で結合する)
            byte[] authenticationValue = String.format("%s:%d", sellerId, unixTime).getBytes();
​
            // pem形式の公開鍵読み込み
            String publicKeyPem = Files.readString(keyFilePath);
​
            // pem形式からder形式に変換するにあたり、不要部分を削除
            publicKeyPem = publicKeyPem
                    .replace("-----BEGIN PUBLIC KEY-----\n", "")  // (Windowsの場合: \n -> \r\n)
                    .replace("-----END PUBLIC KEY-----", "")
                    .replace("\n", "");                           // (Windowsの場合: \n -> \r\n)

            // 公開鍵インスタンス生成
            X509EncodedKeySpec keySpec = new X509EncodedKeySpec(Base64.getDecoder().decode(publicKeyPem));
            KeyFactory keyFactory = KeyFactory.getInstance("RSA");
            RSAPublicKey publicKey = (RSAPublicKey) keyFactory.generatePublic(keySpec);
​
            // 暗号化インスタンス生成
            Cipher encryptorWithPublicKey = Cipher.getInstance("RSA/ECB/PKCS1Padding");
            encryptorWithPublicKey.init(Cipher.ENCRYPT_MODE, publicKey);
​
            // 認証情報の暗号化実行
            byte[] encryptedAuthenticationValue = encryptorWithPublicKey.doFinal(authenticationValue);
​
            // 認証情報のBase64エンコード実行
            byte[] encodedAuthenticationValue = Base64.getEncoder().encode(encryptedAuthenticationValue);
​
            // HTTP通信準備
            HttpClient client = HttpClient.newHttpClient();
            HttpRequest request = HttpRequest
                    .newBuilder(uri)
                    .header("Authorization", "Bearer {アクセストークン}")
                    .header("X-sws-signature", new String(encodedAuthenticationValue))
                    .header("X-sws-signature-version", "1")
                    .build();
​
            // HTTP通信実行
            HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
​
            // 結果表示
            System.out.println("response header : " + response.headers().toString());
            System.out.println("response : " + response.body());
​
        } catch (Exception exception) {
            // エラーが出た場合にエラー内容を表示
            exception.printStackTrace();
        }
    }
}

テスト環境での公開鍵の利用について

テスト環境でも、公開鍵認証は利用可能です。

テスト環境に関連するヘルプ

テスト環境に関連するヘルプは以下リンクからご覧ください。

• テスト環境に関連するヘルプ

Yahoo! ショッピングAPI共通エラーコードについて

Yahoo! ショッピングAPI共通のエラーコードについては以下リンクからご覧ください。

• Yahoo! ショッピングAPI共通エラーコード一覧

よくあるご質問

「よくある質問」ページも合わせてご確認ください。

「Client ID（アプリケーションID）」が確認できるページはありますか。

Yahoo! JAPAN IDでログインした状態で「アプリケーションの管理」ページをご確認ください。

リクエスト元IPアドレスの変更・追加したい。

リクエスト元IPアドレスの変更・追加をご希望の場合は、
再度「ショッピングAPI利用申請フォーム」から申請をお願いします。

※既に「注文API」、「お問い合わせ管理API」または「定期購入API」をご利用中のお客様が対象です。
※設定完了まで約1週間～10日程度お時間をいただいております。

APIコール数の制限緩和をしたい。

1日50,000リクエストを超える場合は、Client ID（アプリケーションID）を追加してご対応ください。

※1Client ID（アプリケーションID）につき、1日5万リクエストまでの制限がかけられております。

テスト環境の利用申請をしたが、メールが届かない。

過去に利用申請をしている場合、メール配信を行っておりません。
発行済みのテスト環境の詳細については、新規発行時に配信しているメールをご確認ください。
件名：【重要】テスト環境利用申請者の方へご案内：Yahoo!ショッピング
※１つのYahoo!JAPAN IDにつき、利用できるテスト環境は１つのみです。

リフレッシュトークンの有効期限切れ前に再認可をしてトークンを取得したが、返ってきたトークン情報が変わっていない。

有効期限切れ前に再認可をしてトークンを取得した場合、トークン情報（文字列）に変更はありません。
文字列は同一のものですが、有効期限に関しては延長されておりますので引き続きご利用ください。
下記仕様変更の影響でリフレッシュトークンが変更されます。
【Yahoo! ID連携】リフレッシュトークン再取得時の仕様変更のお知らせ

各種申請の承認を早めてほしい。

大変恐れ入りますが、このような作業は承っておりません。
承認まではお時間をいただいておりますので、ご了承ください。

その他よくある質問はこちら
よくある質問