EC事業者様の海外販売をJ-goods(弊社提供の貴社専用越境ECサイト)でお手伝い

カテゴリ情報API

1.概要

カテゴリ情報APIには以下の機能があります。

2.カテゴリ情報APIの仕様

カテゴリ情報APIの仕様は以下のとおりです。

  • エンドポイント

    https://api.j-goods.net/category/v1/ (httpsのみ)

  • 認証

    OAuth2プロトコルによる認証(クライアント・クレデンシャルズフロー)

  • レスポンス

    JSON形式でレスポンスを返します。詳細は各メソッドの「レスポンス」をご確認ください。

3.カテゴリ情報APIの利用手順

カテゴリ情報APIを利用するために必要な作業は次のとおりです。

  1. クライアントID,クライアント・シークレットの取得

    J-goods上で取得できます。

  2. プログラムの作成

    定められた方法に従ってパラメータを組み立てて送信してください。
    APIエンドポイントは次のとおりです。https://api.j-goods.net/category/v1/ (httpsのみ)

  3. プログラムの実行

    プログラムを実行して,カテゴリ情報を操作します。

4.クライアントID等の取得

カテゴリ情報APIを利用するためには,クライアントID,クライアント・シークレットを取得する必要があります。

このクライアントID,クライアント・シークレット他のAPIと共通となっています。すでにクライアントID,クライアント・シークレットを取得している場合は,そのクライアントID,クライアント・シークレットを利用してください。

  1. 事業者様用マイページにログイン後,メニューの「登録情報変更」リンクをクリックしてください。

    登録情報変更リンクをクリック
  2. API認証キー」のリンクをクリックしてください。

    API認証キー
  3. API認証キー設定画面が表示されます。ここでクライアントID,クライアント・シークレットを取得,確認することができます

    認証用パスワードの指定

    クライアントIDの確認ボタンをクリックしてください。ダイアログが表示され,クライアントID,クライアント・シークレットを作成したり,確認したりすることができます。

  4. 確認ダイアログが表示されます。

    確認ダイアログ

    追加ボタンをクリックするとクライアントIDが生成されます。

  5. クライアントIDとクライアント・シークレットが生成されます。

    確認ダイアログ面

    クライアントIDとクライアント・シークレットを削除する場合は削除ボタンをクリックします。
    変更ボタンをクリックすると,クライアント・シークレットを変更できます。

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

APIを利用するには,取得したクライアントIDとクライアント・シークレットを用いてアクセストークンを取得する必要があります。

  1. エンドポイント

    アクセストークンを取得するためのエンドポイントは以下のとおりです(全API共通)。
    https://api.j-goods.net/token

  2. リクエストパラメータ

    アクセストークンを取得するために送信するパラメータは以下のとおりです(全API共通)。

    client_id 必須 上記で取得したクライアントID
    client_secret 必須 上記で取得したクライアント・シークレット
    grant_type 必須 "client_credentials"

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

    アクセストークンを取得する処理のサンプルです。

    // TOKEN用エンドポイント
    $url = 'https://api.j-goods.net/token';
    // クライアントID
    $client_id = 'ci_xxxxxxxxxxxxxxxxxxxxxxxxxxx';
    // クライアント・シークレット
    $client_secret = 'sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
    
    // エンドポイントにPOSTメソッドでパラメータを送信する
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_POST, TRUE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
        'client_id' => $client_id,
        'client_secret' => $client_secret,
        'grant_type' => 'client_credentials',
    )));
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    
    // アクセスTOKENの有効期限は1時間
    $buf = curl_exec($ch);
    // JSON形式でTOKENが返されるので配列に変換
    $token = json_decode($buf, true);
    // TOKENの表示
    print_r($token);
                        

    APIを呼び出す際,取得したアクセストークンを Authorization ヘッダーBearer スキームに指定します。

6.リクエストパラメータの作成

APIを利用するには定められた方法に従ってリクエストパラメータを作成する必要があります。

  1. リクエストパラメータの設定

    リクエストパラメータはJSON形式で送信します。各パラメータについては各メソッドの「リクエストパラメータ」の項をご覧ください。

  2. Authorizationヘッダの設定

    AuthorizationヘッダのBearerスキームに取得したアクセストークンを付与します。

  3. リクエストパラメータの送信

    送信先は「https://api.j-goods.net/category/v1/」です。
    カテゴリ情報を2件取得する処理のサンプルです。

    // リクエストパラメータ
    $request_parameter = array(
        'first' => 1,   // 先頭から取得
        'limit' => 2    // データを2件だけ取得
    );
    // 送る際にはJSON形式にする
    $json = json_encode($request_parameter);
    
    // カテゴリ情報APIのURL
    $url = 'https://api.j-goods.net/category/v1/';
    
    $ch = curl_init();
    
    // ヘッダーに取得したアクセストークンを設定する
    $header = [
        'Authorization: Bearer ' . $token['access_token'],
        'Content-Type: application/json',
    ];
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET'); // 商品情報の取得はGETメソッド
    curl_setopt($ch, CURLOPT_POSTFIELDS, $json);    // JSON形式のリクエストパラメータを設定
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HEADER, true);
    
    $response = curl_exec($ch);
    
    // レスポンスヘッダーの大きさを取得
    $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    // ヘッダー部分
    $header = substr($response, 0, $header_size);
    // ボディ部分
    $body = substr($response, $header_size);
    
    curl_close($ch);
    
    // JSON形式でデータが返ってくるので,配列の形式にデーコード
    $json =  json_decode($body, true);
    // 取得したデータを表示
    print_r($json);
                        
  4. レスポンスの取得

    レスポンスもJSON形式で返ってきます。レスポンスの詳細は各メソッド「レスポンス」の項をご覧ください。

7.カテゴリ情報の取得

  • GET /search.json

    条件を指定してカテゴリ情報を取得します。

    • リクエストパラメータ

      ○:必須項目

      パラメータ 説明 必須 データ種別 備考
      first先頭データ整数(≧ 1)いくつ目のデータから返すかを指定。省略した場合は1が指定されたものとみなす。

      指定例

      {
          "first": 1
      }

      limit取得件数1以上50以下の整数取得するデータの件数を指定。省略した場合は「50」が指定されたものと見なす。

      指定例

      {
          "limit": 20
      }

      keywordキーワード文字列検索対象は,カテゴリ名,カテゴリID,親カテゴリID。

      指定例

      {
          "keyword": "coffee"
      }

      parent_category_id親カテゴリID文字列指定した文字列を親カテゴリIDに含むカテゴリを検索する。

      指定例

      {
          "parent_category_id": "coffee"
      }

      hierarchy階層1から5の整数指定した階層のカテゴリを検索する。

      指定例

      {
          "hierarchy": 4
      }

    • レスポンス

      JSON形式で返ります。

      要素 データ種別 説明
      StatusCode文字列リクエストが成功したかどうかを示すコード。
      Message文字列リクエストが成功したかどうかを示す文字列。
      Count整数返されたデータの件数。
      Total整数条件に適合するデータの総件数。
      First整数先頭のデータが何件目を示す。
      Categories配列カテゴリデータ。詳しい内容はCategories要素の詳細を参照。

      Categories要素の詳細

      要素 データ種別 説明
      store_code文字列店コード
      hierarchy整数カテゴリの階層。最上位が「1」,最下位は「5」
      parent_category_id文字列親カテゴリのパス。
      category_id文字列カテゴリID。
      show_children整数

      メニュー上に子カテゴリを表示するかどうかを示す。

      0:非表示,1:表示。

      memo文字列メモ。カテゴリに関する情報を記載。
      create_timestamp日付文字列作成日時。
      update_timestamp日付文字列更新日時
      invisible整数

      非表示設定。メニュー上にカテゴリを表示するかどうかを示す。

      0:表示,1:非表示。

      なお非表示に設定しても,表示されないのはカテゴリだけであり,非表示カテゴリに含まれる商品は「未分類」として表示される。

      category文字列カテゴリのパス
      category_name連想配列

      カテゴリ名。

      jp:日本語のカテゴリ名,en:英語のカテゴリ名,kr:韓国語のカテゴリ名,zh:中国語のカテゴリ名。


      レスポンスの実例

      {
          "StatusCode": "200",
          "Message": "OK",
          "First": 1,
          "Count": 2,
          "Total": 2,
          "Categories": [
              {
                  "store_code": "000017",
                  "hierarchy": 4,
                  "parent_category_id": "\/1-1\/1-2\/1-3",
                  "category_id": "1-4",
                  "show_children": 0,
                  "memo": null,
                  "create_timestamp": "2019-04-25 15:29:34",
                  "update_timestamp": null,
                  "invisible": 0,
                  "category": "\/1-1\/1-2\/1-3\/1-4",
                  "category_name": {
                      "jp": "Level-4"
                  }
              },
              {
                  "store_code": "000017",
                  "hierarchy": 5,
                  "parent_category_id": "\/1-1\/1-2\/1-3\/1-4",
                  "category_id": "1-5",
                  "show_children": 0,
                  "memo": null,
                  "create_timestamp": "2019-04-25 15:29:34",
                  "update_timestamp": null,
                  "invisible": 0,
                  "category": "\/1-1\/1-2\/1-3\/1-4\/1-5",
                  "category_name": {
                      "jp": "Level-5"
                  }
              }
          ]
      }
  • GET /{#category_id}

    カテゴリIDを指定してカテゴリ情報を取得します。この場合,URLは「https://api.j-goods.net/category/v1/{#category_id}」となります。

    例えば,カテゴリID「coffee」のカテゴリ情報を取得する場合のURLは「https://api.j-goods.net/category/v1/coffee」です。

    • リクエストパラメータ

      ありません。カテゴリIDはURLで指定します。

    • レスポンス

      条件を指定してカテゴリ情報を取得する場合と同じです。こちらの表でご確認ください。

8.カテゴリ情報の登録

  • POST /category.json

    条件を指定してカテゴリ情報を登録します。複数のカテゴリをまとめて登録することも可能です(一度に50件まで)。

    • リクエストパラメータ

      パラメータ 説明 必須 データ種別 備考
      category_idカテゴリID必須文字列半角英数字(ハイフンも可)50文字以内で指定。

      指定例

      {
          "category_id": "coffee"
      }

      parent_category_id親カテゴリID必須文字列空文字,または半角英数字(ハイフンも可)50文字以内で指定。空文字を指定した場合は,最上位のカテゴリとなる。

      指定例

      {
          "parent_category_id": "coffee"
      }

      category_nameカテゴリ名必須連想配列日本語のカテゴリは必須。各言語とも50文字以内で設定する。
      jp:日本語のカテゴリ名,en:英語のカテゴリ名,kr:韓国語のカテゴリ名,zh:中国語のカテゴリ名。

      指定例

      {
          "category_name": {
              "jp": "コーヒー",
              "en": "coffee"
          }
      }

      show_children子カテゴリ表示整数子カテゴリを表示するかどうかの指定。0:表示しない,1:表示する。

      指定例

      {
          "show_children": 1
      }

      invisible非表示設定整数カテゴリをメニューに表示するかどうかの指定。0:表示する,1:表示しない。
      非表示に設定しても,表示されないのはカテゴリだけであり,非表示カテゴリに含まれる商品は「未分類」として表示される。

      指定例

      {
          "invisible": 1
      }

      memoメモ文字列カテゴリに関するメモを150文字以内で設定する。この情報は画面に表示されない。

      指定例

      {
          "memo": "コーヒーに関するカテゴリ"
      }

    • リクエスト処理のサンプル

      $append_category = array(
          // 複数のカテゴリを登録することが可能(1度に登録できるのは50個まで)
          // カテゴリ1
          [
              'category_id' => 'category-1',
              'parent_category_id' => '',
              'category_name' => array(
                  'jp' => 'カテゴリ-1',
                  'en' => 'category-1',
              ),
              'show_children' => 0,
              'invisible' => 0,
              'memo' => 'カテゴリその1',
          ],
          // カテゴリ2
          [
              'category_id' => 'category-2',
              'parent_category_id' => 'category-1',
              'category_name' => array(
                  'jp' => 'カテゴリ-2',
                  'en' => 'category-2',
              ),
              'show_children' => 0,
              'invisible' => 0,
              'memo' => 'カテゴリその2(階層2)',
          ],
      );
      // 送る際にはJSON形式にする
      $json = json_encode($append_category);
      
      // カテゴリ情報APIのURL
      $url = 'https://api.j-goods.net/category/v1/';
      
      $ch = curl_init();
      
      // ヘッダーに取得したアクセストークンを設定する
      $header = [
          'Authorization: Bearer ' . $token['access_token'],
          'Content-Type: application/json',
      ];
      curl_setopt($ch, CURLOPT_URL, $url);
      curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
      curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST'); // カテゴリ情報の登録はPOSTメソッド
      curl_setopt($ch, CURLOPT_POSTFIELDS, $json);     // JSON形式のリクエストパラメータを設定
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HEADER, true);
      
      $response = curl_exec($ch);
      
      // レスポンスヘッダーの大きさを取得
      $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
      // ヘッダー部分
      $header = substr($response, 0, $header_size);
      // ボディ部分
      $body = substr($response, $header_size);
      
      curl_close($ch);
      
      // JSON形式でデータが返ってくるので,配列の形式にデーコード
      $json = json_decode($body, true);
      // 取得したデータを表示
      print_r($json);
                          
    • レスポンス

      JSON形式で返ります。

      認証エラー
      -- 要素 データ種別 説明
      --StatusCode文字列リクエストが成功したかどうかを示すコード。
      --Message文字列リクエストが成功したかどうかを示す文字列。
      パラメータエラー
      親要素 子要素 データ種別 説明
      resultStatusCode文字列リクエストが成功したかどうかを示すコード。
      category_id文字列エラーが発生したカテゴリID。
      Message文字列リクエストが成功したかどうかを示す文字列。
      Messages配列(文字列)エラー情報。必要に応じて返される。返されない場合もある。
      登録成功
      親要素 子要素 データ種別 説明
      resultStatusCode文字列リクエストが成功したかどうかを示すコード。
      Message文字列リクエストが成功したかどうかを示す文字列。
      Categories配列カテゴリデータ。詳しい内容はCagetories要素の詳細を参照。

      レスポンスの実例

      {
          "result": [
              {
                  "StatusCode": "200",
                  "Message": "OK",
                  "Categories": [
                      {
                          "store_code": "000017",
                          "hierarchy": 1,
                          "parent_category_id": "",
                          "category_id": "category-1",
                          "show_children": 0,
                          "memo": "カテゴリその1",
                          "create_timestamp": "2019-04-25 22:53:23",
                          "update_timestamp": null,
                          "invisible": 0,
                          "category_name": {
                              "jp": "カテゴリ-1",
                              "en": "category-1"
                          }
                      }
                  ]
              },
              {
                  "StatusCode": "200",
                  "Message": "OK",
                  "Categories": [
                      {
                          "store_code": "000017",
                          "hierarchy": 2,
                          "parent_category_id": "\/category-1",
                          "category_id": "category-2",
                          "show_children": 0,
                          "memo": "カテゴリその2(階層2)",
                          "create_timestamp": "2019-04-25 22:53:23",
                          "update_timestamp": null,
                          "invisible": 0,
                          "category_name": {
                              "jp": "カテゴリ-2",
                              "en": "category-2"
                          }
                      }
                  ]
              }
          ]
      }

9.カテゴリ情報の更新

10.カテゴリ情報の削除

  • DELETE /category.json

    条件を指定してカテゴリ情報を削除します。複数のカテゴリをまとめて削除することも可能です(一度に50件まで)。

    • リクエストパラメータ

      パラメータ 説明 必須 データ種別 備考
      category_idカテゴリID必須文字列

      削除するカテゴリのカテゴリIDを指定する。

      親カテゴリ(子カテゴリが存在するカテゴリ)は削除できない。したがって複数のカテゴリを削除する場合は,必ず子カテゴリから順番に削除すること。

      指定例

      {
          "category_id": "coffee"
      }

    • リクエスト処理のサンプル

      // リクエストパラメータ
      $delete_category = array(
          // 複数のカテゴリを登録することが可能(1度に登録できるのは50個まで)
          // 削除する場合は必ず下位のカテゴリから削除する。
          // カテゴリ2
          [
              'category_id' => 'category-2',
          ],
          // カテゴリ1
          [
              'category_id' => 'category-1',
          ],
      );
      // 送る際にはJSON形式にする
      $json = json_encode($delete_category);
      
      // カテゴリ情報APIのURL
      $url = 'https://api.j-goods.net/category/v1/';
      
      $ch = curl_init();
      
      // ヘッダーに取得したアクセストークンを設定する
      $header = [
          'Authorization: Bearer ' . $token['access_token'],
          'Content-Type: application/json',
      ];
      curl_setopt($ch, CURLOPT_URL, $url);
      curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
      curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); // カテゴリ情報の削除はDELETEメソッド
      curl_setopt($ch, CURLOPT_POSTFIELDS, $json);       // JSON形式のリクエストパラメータを設定
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HEADER, true);
      
      $response = curl_exec($ch);
      
      // レスポンスヘッダーの大きさを取得
      $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
      // ヘッダー部分
      $header = substr($response, 0, $header_size);
      // ボディ部分
      $body = substr($response, $header_size);
      
      curl_close($ch);
      
      // JSON形式でデータが返ってくるので,配列の形式にデーコード
      $json = json_decode($body, true);
      // 取得したデータを表示
      print_r($json);
                          
    • レスポンス

      JSON形式で返ります。

      認証エラー
      -- 要素 データ種別 説明
      --StatusCode文字列リクエストが成功したかどうかを示すコード。
      --Message文字列リクエストが成功したかどうかを示す文字列。
      パラメータエラー
      親要素 子要素 データ種別 説明
      resultcategory_id文字列対象となったカテゴリID。
      StatusCode文字列リクエストが成功したかどうかを示すコード。
      Message文字列リクエストが成功したかどうかを示す文字列。
      Messages配列(文字列)エラー情報。必要に応じて返される。返されない場合もある。
      成功
      親要素 子要素 データ種別 説明
      resultcategory_id文字列対象となったカテゴリID。
      StatusCode文字列リクエストが成功したかどうかを示すコード。
      Message文字列リクエストが成功したかどうかを示す文字列。

      レスポンスの実例

      {
          "result": [
              {
                  "category_id": "category-2",
                  "StatusCode": "200",
                  "Message": "OK"
              },
              {
                  "category_id": "category-1",
                  "StatusCode": "200",
                  "Message": "OK"
              }
          ]
      }
  • DELETE /{#category_id}

    カテゴリIDを指定してカテゴリ情報を削除します。この場合,URLは「https://api.j-goods.net/category/v1/{#category_id}」となります。

    • リクエストパラメータ

      ありません。

    • レスポンス

      JSON形式で返ります。

      認証エラー
      要素 データ種別 説明
      StatusCode文字列リクエストが成功したかどうかを示すコード。
      Message文字列リクエストが成功したかどうかを示す文字列。
      パラメータエラー
      要素 データ種別 説明
      category_id文字列対象となったカテゴリID。
      StatusCode文字列リクエストが成功したかどうかを示すコード。
      Message文字列リクエストが成功したかどうかを示す文字列。
      Messages配列(文字列)エラー情報。必要に応じて返される。返されない場合もある。
      成功
      子要素 データ種別 説明
      category_id文字列対象となったカテゴリID。
      StatusCode文字列リクエストが成功したかどうかを示すコード。
      Message文字列リクエストが成功したかどうかを示す文字列。

      レスポンスの実例

      {
          "category_id": "category-2",
          "StatusCode": "200",
          "Message": "OK"
      }

11. API利用時の注意点

利用時には以下の点にご留意ください。

  1. パラメータの文字コードは必ずUTF-8でなければならない。
  2. オプションを追加で登録する際,共通項目は他のオプションと同じ値を設定しなければならない。
  3. APIを呼び出せるのは1秒に付き20回である(アクセス制限あり)。