futureshop APIv2について

物流システム、および店舗様でご利用の基幹システムにて、出荷処理・受注処理を行えるよう、商品データや受注データを取得できる以下のAPIをご用意しています。

形式は、json形式です。
本ページにて、お申込み方法と共通仕様をご確認後、各APIの説明ページにて詳細をご覧ください。

ECサイトやアプリでの画面表示の用途にはご利用いただけません。

futureshop API連携に対応している、発送・出荷・倉庫連携などの物流サービスはこちら

商品関連

商品検索API

在庫関連

受注・受注処理関連

実店舗情報関連

会員情報関連

会員検索API以外は、futureshop omni-channelご利用店舗様はご利用いただけません。

ポイント関連

※futureshop omni-channelご利用店舗様はご利用いただけません。
※ポイントオプションご利用店舗様のみご利用いただけます。

ご利用のお申込みと流れについて

※【FS】：フューチャーショップを指します。

【店舗様・開発者様】お申込みフォームより開発者登録
お申込みフォーム内の利用規約を必ずご確認の上、お申し込みください。
お申し込みいただいた後、2~3営業日で検証環境用のAPI接続情報をご案内いたします。
【FS】検証環境用API情報のお渡し
検証はトライアル店舗にて行っていただきます。
現在ご利用のない場合はトライアル店舗もあわせてお渡しいたします。
【店舗様/開発者様】検証環境で開発・検証
トライアル店舗でお使いになりたいAPIをお試しください。
検証環境用のAPIは公開しているすべてのAPIをお試しいただけます。
【店舗様/開発者様】稼働中店舗での利用申込み
ご利用になる店舗様で利用するAPIをお申し込みください（futureshop管理画面）。
お申し込みいただいた後、2~3営業日で本番環境用のAPI接続情報をご案内いたします。
＜実店舗在庫表示機能に関連するAPIの場合＞
別途オプション費用のご入金が必要です。詳細はお申込み後にご案内いたします。
お申し込み画面
［コマースクリエイター利用店舗様］：システム＞各種申し込み
［コマースクリエイター未利用店舗様］：管理TOP＞管理トップ＞各種申し込み

【FS】本番環境用API情報のお渡し
４でお申し込みいただいたAPIを利用できるAPI接続情報をご案内いたします。
【店舗様/開発者様】稼働中店舗での利用開始
検証環境で試していただいたAPI接続情報を５でお渡ししたAPI接続情報に変更し、運用を開始してください。

futureshop APIv1（旧API/XML形式）も、ご利用の目的、用途により併用いただくことが可能です。

ただし、本マニュアル上のfutureshop APIv2（新API/json形式）とは仕様が異なります。
また、今後はfutureshop APIv2（新API/json形式）へ統一を進めてまいりますため、futureshop APIv1（旧API/XML形式）が廃止される可能性がございます。あらかじめご了承ください。

futureshop APIv1（旧API/XML形式）について
以下をご用意しております。ご利用の際にはPDFマニュアルをお渡しいたします。

受注ステータス更新
入金ステータス更新
発送ステータス更新
送り状番号更新
在庫更新

新旧APIの機能について：futureshop APIv1/v2　機能比較表をご参照ください。

※futureshop APIv1（旧API/XML形式）をご利用の際には、機密保持契約の締結が必要です。事前にお問い合わせください。

futureshop API の概要

本リファレンスは、futrueshopシステム情報の一部を操作するための開発者用ドキュメントです。
本リファレンスの内容は予告なしに変更することがあります。

バージョン	更新日
version2.0	API更新履歴一覧（2021.09.29～）をご覧ください。

はじめに

APIをご利用いただくにあたり、事前にクライアントID、およびクライアントシークレットの発行が必要です。
クライアントIDの発行には接続元IPとして固定IPをご用意いただく必要があります。

基本仕様

APIの呼び出しはクライアントID単位で１秒間に１回となります。
リクエスト、レスポンス共にJSON形式を用い、文字コードはUTF-8 となります。

共通リクエストヘッダー

ヘッダー名	値
X-SHOP-KEY	店舗キー

Authorizationヘッダー

アクセストークンをHTTPヘッダーに含む形で送信するため、GET/POST/PUTなど任意のHTTPメソッドでもリクエストが送信でき、アクセストークンとウェブAPI固有のパラメータ分離できるのが特徴です。
特別な理由がない限りAuthorizationヘッダーを使ったWeb APIリクエスト方式を推奨します。

用語について

用語	説明
店舗キー	futureshopシステム契約時に付与される店舗毎に一意のキー
クライアントID	依頼により店舗毎に発行されるAPI用のID
クライアントシークレット	依頼により店舗毎に発行されるAPI用のパスワード
アクセストークン	API実行時の認証キーとして用いられるパスワード（認証APIにて取得）

HTTPコード

API呼び出し時に問題がある場合は、HTTPコード、またはレスポンスにエラー原因を返します。
返される可能性があるHTTPコードは以下の通りです。

HTTPコード	説明
400	Bad Request店舗キーが設定されていない場合に返されます。
401	Unauthorized 認証APIにて取得するアクセストークンが無効、または有効期限が切れた場合に返されます。認証APIからアクセストークンを再取得してください。
403	Forbidden APIの操作権限が無い場合に返されます。
404	Not Found 指定されたリソースが見つからない場合に返されます。
405	Method Not Allowed 許可されていないHTTPメソッドからのリクエストの場合に返されます。
409	Conflict リクエスト内容に矛盾が生じた場合に返されます。詳細はレスポンスをご確認下さい。
415	Unsupported Media Type Content-Typeにapplication/jsonが設定されていない場合に返されます。
422	Unprocessable Entity リクエスト内容に問題があった場合に返されます。詳細はレスポンスをご確認下さい。
429	Too Many Requests 連続したリクエストを検知した場合に返されます。リクエストは１秒間に１回になるよう、ご調整下さい。
500	Internal Server Error 内部的な問題によってデータを返すことができない場合に返されます。
503	Service Temporarily Unavailable メンテナンス中の場合に返されます。

認証API

クライアントIDとクライアントシークレットにてログインする事でアクセストークンを取得します。
取得したアクセストークン用いて各種APIをご利用いただけます。
アクセストークンの有効期間は１時間です。

エンドポイント

https://{APIドメイン}/oauth/token

リクエスト

HTTPメソッド

POST

Authorizationヘッダー

basic認証：ユーザー名にクライアントID、パスワードにクライアントシークレットを設定する。

必須パラメータ

「Content-Type:application/x-www-form-urlencoded」を指定して送信して下さい。

キー	値
grant_type	client_credentials

レスポンス

キー	内容	説明
access_token	アクセストークン	各種APIのAuthorizationに設定
token_type	トークンタイプ
expires_in	有効時間	発行から1時間有効：返却値は秒数

{
    "access_token":"be85ae2a-e7f7-4ca3-b439-fbbbb55f854d",
    "token_type":"bearer",
    "expires_in":3600
}

サンプルコード（php）

<?php

$shopKey = '#####店舗キー#####';
$apiClient = '#####クライアントID#####';
$apiSecret = '#####クライアントシークレット#####';

$header = [
    "X-SHOP-KEY:{$shopKey}",
    'Authorization: Basic ' . base64_encode("{$apiClient}:{$apiSecret}")
];

$url = 'https://{#####APIドメイン#####}/oauth/token';
$param = array(
'grant_type' => 'client_credentials'
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST,  'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER,     $header);
curl_setopt($ch, CURLOPT_URL,            $url);
curl_setopt($ch, CURLOPT_POST,           true);
curl_setopt($ch, CURLOPT_POSTFIELDS,     http_build_query($param));

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

サンプルコード（ruby）

require 'net/http'
require 'uri'
require 'openssl'

uri = URI.parse("https://{#####APIドメイン#####}/oauth/token")
request = Net::HTTP::Post.new(uri)
request.basic_auth("#####クライアントID#####", "#####クライアントシークレット#####")
request["X-SHOP-KEY"] = "#####店舗キー#####"
request.set_form_data(
  "grant_type" => "client_credentials",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

アクセストークンによる認証

認証（/oauth/token）以外のAPIでは認証キーとして、/oauth/tokenにて取得したワンタイムパスワードを用います。

サンプルコード（php）

<?php
// 認証APIのaccess_tokenを設定
$accessToken = "###########";
$shopKey = '#####店舗キー#####';

$header = [
    "X-SHOP-KEY:{$shopKey}",
    'Authorization: Bearer ' . $accessToken
];
$url = 'https:// {#####APIドメイン#####} /admin-api/v1/inventory?types= regular ';

$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

サンプルコード（ruby）

## 認証APIのaccess_tokenを設定
token = "####################"

uri = URI.parse("https:// {#####APIドメイン#####} /admin-api/v1/inventory?types= regular,planned")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer " + token
request["X-SHOP-KEY"] = "#####店舗キー#####"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end