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

越境取引代行サービス用受注情報API

1.概要

越境取引代行サービス用受注情報APIには以下の機能があります。

  • 越境取引代行サービス用受注情報の取得
    GET /search.json 検索パラメータを指定して取得
    GET /{#order_no} 受注番号を指定して取得する
  • 越境取引代行サービス用受注情報の変更
    PUT /{#order_no} 受注番号を指定して変更する
    ※変更できるのは「受注状況」,「在庫引当数」,「パッケージ・グループ」です。

2.越境取引代行サービス用受注情報APIの仕様

越境取引代行サービス用受注情報APIの仕様は以下のとおりです。

  • エンドポイント

    https://api.j-goods.net/order/v2/ (httpsのみ)

  • 認証

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

  • レスポンス

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

3.越境取引代行サービス用受注情報APIの利用手順

越境取引代行サービス用受注情報APIを利用するために必要な作業は次のとおりです。

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

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

  2. プログラムの作成

    定められた方法に従ってパラメータを組み立てて送信してください。
    APIエンドポイントは次のとおりです。https://api.j-goods.net/order/v2/ (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/order/v2/」です。
    発送済みの越境取引代行サービス用受注情報を2件取得する処理のサンプルです。

    // リクエストパラメータ
    $request_parameter = array(
        'first' => 1,   // 先頭から取得
        'limit' => 2,    // データを2件だけ取得
        'order_status' => 5,
    );
    // 送る際にはJSON形式にする
    $json = json_encode($request_parameter);
    
    // 受注情報APIのURL
    $url = 'https://api.j-goods.net/order/v2/';
    
    $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
      }

      order_status注文状況整数設定できる整数は以下の表を参照。
      注文状況検索対象
      0注文取消
      1注文受付
      2決済待ち
      3承認待ち
      4返答待ち
      5発送済み
      6発送待ち
      7入荷待ち
      8出荷後取消
      9注文分割
      11再決済待ち
      13振込確認待ち

      指定例

      {
          "order_status": 0
      }

      start_date検索開始日日付文字列yyyy-mm-dd
      target_dateが指定されていない場合はデータの最終更新日時が検索対象となる

      指定例

      {
          "start_date": "2019-01-10"
      }

      end_date検索終了日日付文字列yyyy-mm-dd
      target_dateが指定されていない場合はデータの最終更新日時が検索対象となる

      指定例

      {
          "end_date": "2019-01-10"
      }

      target_date日付検索対象文字列日付検索の対象となるデータを指定する。
      以下のいずれかの文字列を指定する。
      指定する文字列対象となる日付
      order注文日付
      bill請求日付
      settlement支払日付
      approve承認日付
      shipped発送日付
      cancel取消日付
      createデータ作成日付
      update最終更新日付(デフォルト)
      指定しない場合はデータの最終更新日時が検索対象となる。

      指定例

      {
          "target_date": "order"
      }

      item_code商品コード文字列検索したい商品コードを指定する。検索は部分一致。

      指定例

      {
          "item_code": "BOOTS001"
      }

      item_name商品名文字列検索したい商品名を指定する。検索は部分一致。

      指定例

      {
          "item_name": "長靴"
      }

      option_codeオプションコード文字列検索したいオプションコードを指定する。検索は部分一致。

      指定例

      {
          "option_code": "orange_25"
      }

      option_nameオプション名文字列検索したいオプション名を指定する。検索は部分一致。

      指定例

      {
          "option_name": "オレンジ"
      }

    • レスポンス

      JSON形式で返ります。

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

      Orders要素の詳細

      要素 データ種別 説明
      order_no文字列J-goods上で利用する受注番号です。
      customer_name文字列貴社の国内販売先である弊社配送情報(会社名)が挿入される。
      shipping_phone文字列貴社の国内販売先である弊社配送情報(電話番号)が挿入される。
      shipping_country文字列貴社の国内販売先である弊社配送情報(配送国)が挿入される。
      shipping_zipcode文字列貴社の国内販売先である弊社配送情報(郵便番号)が挿入される。
      shipping_state文字列貴社の国内販売先である弊社配送情報(県名)が挿入される。
      shipping_city文字列貴社の国内販売先である弊社配送情報(市区)が挿入される。
      shipping_address1文字列貴社の国内販売先である弊社配送情報(配送先住所1)が挿入される。
      shipping_address2文字列受注番号が挿入される。
      shipping_recipient文字列貴社の国内販売先である弊社配送情報(受取人名)が挿入される。
      order_date日付文字列注文受付日時。書式 : yyyy-mm-dd HH:ii:ss
      bill_date日付文字列決済請求日時。未請求の場合は空欄。書式 : yyyy-mm-dd HH:ii:ss
      settlement_date日付文字列決済完了日時。未決済の場合は空欄。書式 : yyyy-mm-dd HH:ii:ss
      approval_date日付文字列注文承認日時。未承認の場合は空欄。書式 : yyyy-mm-dd HH:ii:ss
      shipped_date日付文字列発送完了日時。未発送の場合は空欄。書式 : yyyy-mm-dd HH:ii:ss
      cancel_date日付文字列注文取消日時。注文が有効の場合は空欄。書式 : yyyy-mm-dd HH:ii:ss
      create_date日付文字列作成日時。この注文データが作成された日時。書式 : yyyy-mm-dd HH:ii:ss
      update_date日付文字列最終更新日時。この注文に関する情報が最後に更新された日時。書式 : yyyy-mm-dd HH:ii:ss
      order_status数値注文状況。
      注文状況検索対象
      0注文取消
      1注文受付
      2決済待ち
      3承認待ち
      4返答待ち
      5発送済み
      6発送待ち
      7入荷待ち
      8出荷後取消
      9注文分割
      11再決済待ち
      13振込確認待ち
      items配列商品情報。詳しい内容はitems要素の詳細を参照。

      items要素の詳細

      要素 データ種別 説明
      index数値商品明細番号。注文商品ごとに1から順番に割り当てられている整数。在庫引当数,パッケージグループを設定する際,商品を特定するために使用。
      package_group数値梱包グループ。梱包が複数になる場合,どの梱包に含まれているかを示す。
      item_code文字列商品番号。
      item_name文字列商品名。
      option_code文字列オプション番号。
      option_name文字列オプション名。
      tracking_code文字列トラッキング変数。
      sub_tracking_code文字列副トラッキング変数。ネクストエンジン,zaiko Robotを利用して在庫管理を行う場合に,必要に応じて設定。受注情報を送信する際,商品を指定するために使用。
      unit_price数値単価。
      qty数値数量。
      sub_total数値小計。
      reserved_qty数値在庫引当数量。

      レスポンスの実例

      {
          "StatusCode": "200",
          "Message": "OK",
          "Total": 1,
          "Count": 1,
          "First": 1,
          "Orders": [
              {
                  "order_no": "1904220004",
                  "customer_name": "株式会社スカイオリジン",
                  "shipping_phone": "052-414-4947",
                  "shipping_country": "日本国",
                  "shipping_zipcode": "453-0013",
                  "shipping_state": "愛知県",
                  "shipping_city": "名古屋市",
                  "shipping_address1": "中村区亀島1-6-8",
                  "shipping_address2": "#1904220004",
                  "shipping_recipient": "天本 晃嗣",
                  "order_date": "2019-04-22 16:49:44",
                  "bill_date": "2019-04-22 16:51:01",
                  "settlement_date": "2019-04-22 16:53:35",
                  "approval_date": null,
                  "shipped_date": null,
                  "cancel_date": null,
                  "create_date": "2019-04-22 16:49:44",
                  "update_date": "2019-04-23 13:16:51",
                  "order_status": 1,
                  "items": [
                      {
                          "index": 1,
                          "item_code": "BOOTS001",
                          "item_name": "カラフル長靴",
                          "option_code": "オレンジ_25cm",
                          "option_name": "色:orange, サイズ:25cm",
                          "tracking_code": "AAAA",
                          "sub_tracking_code": "22",
                          "unit_price": 20007,
                          "qty": 1,
                          "sub_total": 20007,
                          "reserved_qty": 1,
                          "package_group": 1
                      }
                  ]
              }
          ]
      }
  • GET /{#order_no}

    受注番号を指定して越境取引代行サービス用受注情報を取得します。この場合,URLは「https://api.j-goods.net/order/v2/{#order_no}」となります。

    例えば,受注番号「1904010001」の越境取引代行サービス用受注情報を取得する場合のURLは「https://api.j-goods.net/order/v2/1904010001」です。

    • リクエストパラメータ

      ありません。受注番号はURLで指定します。

    • レスポンス

      条件を指定して越境取引代行サービス用受注情報を取得する場合と同じです。こちらの表でご確認ください。

8.越境取引代行サービス用受注情報の更新

9. API利用時の注意点

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

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