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
      }

      transaction_idトランザクションID文字列決済時に付与されたトランザクションID。
      半角英数字および半角記号

      指定例

      {
          "transaction_id": "O-xxHxxxxxMyyyyy"
      }

      tracking_no追跡番号文字列発送時に付与された追跡番号。
      半角英数字および半角記号

      指定例

      {
          "tracking_no": "EN1235456789AB"
      }

      shipping_method配送方法文字列以下のいずれかの文字列を指定する。
      EMS ePacket ePacket-L AIR SAL SURFACE FedEx DHL UPS SAGAWA YAMATO

      指定例

      {
          "shipping_method": "EMS"
      }

      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"
      }

      shipping_country_code配送国国名コード文字列配送先住所の国名コードを指定する。ISOで定められた国名コード

      指定例

      {
          "shipping_country_code": "CN"
      }

      customer_name顧客名文字列検索したい顧客の名前を指定する。検索は部分一致。

      指定例

      {
          "customer_name": "Mike"
      }

      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文字列受注番号
      customer_name文字列顧客氏名。
      shipping_phone文字列配送先電話番号。
      注文状況が「注文取消(0)」,「注文受付(1)」,「決済待ち(2)」,「出荷後取消(8)」,「注文分割(9)」の場合は空欄。
      shipping_country文字列配送国。
      shipping_zipcode文字列配送先郵便番号。
      注文状況が「注文取消(0)」,「注文受付(1)」,「決済待ち(2)」,「出荷後取消(8)」,「注文分割(9)」の場合は空欄。
      shipping_state文字列配送先州省県郡。
      注文状況が「注文取消(0)」,「注文受付(1)」,「決済待ち(2)」,「出荷後取消(8)」,「注文分割(9)」の場合は空欄。
      shipping_city文字列配送先市区町村。
      注文状況が「注文取消(0)」,「注文受付(1)」,「決済待ち(2)」,「出荷後取消(8)」,「注文分割(9)」の場合は空欄。
      shipping_address1文字列配送先住所1。
      注文状況が「注文取消(0)」,「注文受付(1)」,「決済待ち(2)」,「出荷後取消(8)」,「注文分割(9)」の場合は空欄。
      shipping_address2文字列配送先住所2。
      注文状況が「注文取消(0)」,「注文受付(1)」,「決済待ち(2)」,「出荷後取消(8)」,「注文分割(9)」の場合は空欄。
      shipping_recipient文字列受取人名
      注文状況が「注文取消(0)」,「注文受付(1)」,「決済待ち(2)」,「出荷後取消(8)」,「注文分割(9)」の場合は空欄。
      article_total数値商品代金合計
      delivery_total数値配送料合計
      insurance_fee数値輸送保険料
      shipping_fee数値発送手数料
      discount数値割引
      tax数値税金
      additional_charge数値追加手数料
      total数値合計金額
      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振込確認待ち
      payment_method文字列決済方法。
      文字列決済方法
      paypalPayPalによる決済
      card(stripe)カードによる決済
      alipay(stripe)Alipayによる決済(Stripe経由)
      wechat pay(stripe)Wechat Payによる決済(Stripe経由)
      全額ポイント決済ポイントによる決済
      外為送金外為送金による決済
      transaction_id文字列トランザクションID。全額ポイントによる決済の場合は「ポイント決済のため無し」という文字列が,外為送金による支払いの場合は「外為送金のため無し」という文字列返る。
      settlement_total数値決済金額。未出荷の場合は空欄。
      used_point数値利用ポイント。未出荷の場合は空欄。
      issued_point数値獲得ポイント。未出荷の場合は空欄。
      items配列商品情報。詳しい内容はitems要素の詳細を参照。
      deliveries配列配送情報。詳しい内容はdeliveries要素の詳細を参照。

      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数値在庫引当数量。

      deliveries要素の詳細

      要素 データ種別 説明
      package_no数値梱包番号。
      shipping_method文字列配送方法。
      以下のいずれかの文字列。EMS ePacket ePacket-L AIR SAL SURFACE FedEx DHL UPS SAGAWA YAMATO
      tracking_no文字列追跡番号。未出荷の場合は空欄
      shipping_schedule文字列発送予定日。

      特定の日時:yyyy-mm-dd
      (例)2013-04-01

      決済完了後○日以内:0000-00-XX(XXは07~20,25,30,45,60,90のいずれかの値)
      (例)0000-00-07 決済完了後7日以内

      package_weight数値梱包重量。
      download_url文字列日本郵便荷札。日本郵便用荷札(PDF)のURL。未作成の場合は空欄。

      レスポンスの実例

      {
          "StatusCode": "200",
          "Message": "OK",
          "Total": 14,
          "First": 1,
          "Count": 2,
          "Orders": [
              {
                  "order_no": "1804290001",
                  "customer_name": "Ulzorvc Pcwn",
                  "shipping_phone": "+xxxxyyyyyyzzzzz",
                  "shipping_country": "China",
                  "shipping_zipcode": "23000",
                  "shipping_state": "Gcnaw",
                  "shipping_city": "Lmghmqbb Rnjgmlvxdcql Cwgbs",
                  "shipping_address1": "Bmnobdfzgg Exbrxn",
                  "shipping_address2": null,
                  "shipping_recipient": "Bihfojph Pcogw",
                  "article_total": 6000,
                  "delivery_total": 1400,
                  "insurance_fee": 0,
                  "shipping_fee": 0,
                  "discount": 0,
                  "tax": 0,
                  "additional_charge": 0,
                  "total": 7400,
                  "order_date": "2018-04-29 10:03:39",
                  "bill_date": "2018-04-29 10:04:24",
                  "settlement_date": "2018-04-29 10:06:28",
                  "approval_date": "2018-04-29 10:07:53",
                  "shipped_date": "2018-04-29 10:11:04",
                  "cancel_date": null,
                  "create_date": "2018-04-29 10:03:39",
                  "update_date": "2019-04-27 18:27:30",
                  "order_status": 5,
                  "payment_method": "PayPal",
                  "transaction_id": "Codtllnornnavtggbxw",
                  "settlement_total": 7400,
                  "used_point": 0,
                  "issued_point": 500,
                  "items": [
                      {
                          "index": 1,
                          "item_code": "10943378",
                          "item_name": "サントリーボス240ml(48本)",
                          "option_code": "",
                          "option_name": "",
                          "tracking_code": "",
                          "sub_tracking_code": "",
                          "unit_price": 6000,
                          "qty": 1,
                          "sub_total": 6000,
                          "reserved_qty": 1,
                          "package_group": 1
                      }
                  ],
                  "deliveries": [
                      {
                          "package_no": 1,
                          "shipping_method": "EMS",
                          "tracking_no": "RD365340417IV",
                          "shipping_schedule": "0000-00-07",
                          "package_weight": 500,
                          "download_url": null
                      }
                  ]
              },
              {
                  "order_no": "1808060001",
                  "customer_name": "Ucohftj Hian",
                  "shipping_phone": "+xxxxyyyyyyzzzzz",
                  "shipping_country": "China",
                  "shipping_zipcode": "23000",
                  "shipping_state": "Yobht",
                  "shipping_city": "Jthopzwh Vgzmclzyupdt Hixjd",
                  "shipping_address1": "Qygvycvets Sajuhx",
                  "shipping_address2": null,
                  "shipping_recipient": "Rrevxrvn Ctpgy",
                  "article_total": 15000,
                  "delivery_total": 1120,
                  "insurance_fee": 0,
                  "shipping_fee": 0,
                  "discount": 0,
                  "tax": 0,
                  "additional_charge": 0,
                  "total": 16120,
                  "order_date": "2018-08-06 21:45:54",
                  "bill_date": "2018-08-06 21:47:48",
                  "settlement_date": "2018-08-06 21:52:33",
                  "approval_date": "2018-08-06 21:55:26",
                  "shipped_date": "2018-08-06 23:15:18",
                  "cancel_date": null,
                  "create_date": "2018-08-06 21:45:54",
                  "update_date": "2019-04-27 18:27:30",
                  "order_status": 5,
                  "payment_method": "PayPal",
                  "transaction_id": "Bcjdfrpqrucqtslhhga",
                  "settlement_total": 15620,
                  "used_point": 500,
                  "issued_point": 0,
                  "items": [
                      {
                          "index": 1,
                          "item_code": "10943110",
                          "item_name": "タリーズコーヒー250ml(24缶)",
                          "option_code": "",
                          "option_name": "",
                          "tracking_code": "",
                          "sub_tracking_code": "",
                          "unit_price": 3000,
                          "qty": 5,
                          "sub_total": 15000,
                          "reserved_qty": 5,
                          "package_group": 1
                      }
                  ],
                  "deliveries": [
                      {
                          "package_no": 1,
                          "shipping_method": "ePacket-L",
                          "tracking_no": "EF11683362PP",
                          "shipping_schedule": "0000-00-07",
                          "package_weight": 1250,
                          "download_url": " https:\/\/www.api-mypage.post.japanpost.jp\/webapi\/servlet\/DOWNLOAD?fName=xx...xx"
                      }
                  ]
              }
          ]
      }
  • 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回である(アクセス制限あり)。