目次

※APIを使ってできること

現在、以下の機能がAPIから利用できます。
※スマートフォンのWebViewからの利用には現在のところ対応していません。

  • 受注API
    • 検索

APIを使うための準備

APIデベロッパーアカウントの発行

デベロッパーアカウントは、アシスト店長の管理画面にログイン後、「環境設定>外部アプリ連携」メニューより登録が可能です。

1. APIのクライアントには以下が必要です

  • RESTfulなHTTPリクエスト
  • JSONのパースやシリアライズ
  • 認可コードの受け取りが可能なこと。楽楽リピートAPI認可ページからのHTTPリクエストを受けられるWebサーバ

2. API利用の流れ

API利用の流れは以下の通りです。

利用手順

以下の手順で、OAuth2プロトコルでの認証をします。

1. OAuthアプリケーション登録

アシスト店長の管理画面にログイン後、「環境設定>外部アプリ連携」メニューより登録を行ってください。

※リダイレクトURLには御社WEBサーバー上で認証情報を受け取るURLを指定して下さい。

2. 認証ページ表示

https://{ドメイン名}/api/oauth/authorize.phpに、必要なパラメータをつけてGETリクエストを行ってください。 アカウントの認証を行うHTMLページが表示されます。

パラメータ名有効な値
response_type“code”を指定
redirect_uriアプリケーション登録時に入力したリダイレクトURLと同一のものを指定
client_idアプリケーション詳細画面で確認できるクライアントID
stateCSRF対策の為の安全かつ重複しにくいランダム文字列
scope予約パラメータです。現在は指定できません。
アプリケーションが利用したい機能をスペース区切りで指定します。
“read_sales” = 受注データを参照

例)

https://{ドメイン名}/api/oauth/authorize.php?client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&response_type=code&state=a397aabc602f7e296db23b0717edd1fda06c345f

・URLにアクセスすると、認可ページが表示されます。
・アシスト店長アカウントを持つ利用者は、このページで、アプリケーションがショップのデータにアクセスすることを許可します。
・初めて認可ページへ訪れる利用者は、アシスト店長の管理者ログインID・パスワードの入力を求められます。

3. 認可コードの取得

リダイレクトURLに指定したURLで、認可コードが取得できます。

例)

https://{御社ツールドメイン名}/getAuth.php?code=xxxxxxxxx&state=zzzzzzzzz

codeの値が認可コードになります。

4. アクセストークン取得

認可コードを利用して、アクセストークンを取得します。

https://{アシスト店長ドメイン名}/api/oauth/token.php に対してPOSTリクエストを行います。

リクエストパラメータ

パラメータ名有効な値
client_idアプリケーション詳細画面で確認できるクライアントID
client_secretアプリケーション詳細画面に表示されているシークレット文字列
code認可コード文字列
grant_type“client_credentials” を指定

レスポンスデータ

パラメータ名有効な値
access_tokenアクセストークン
expires_in有効期限
refresh_tokenリフレッシュトークン
  • 認可コードをアクセストークンに交換できるのは1度だけです。
  • アプリケーション側で保存しておくようにしてください。
  • アクセストークンの有効期限は、発行から100日間です。

5. API情報の呼び出し

アクセストークンつきで HTTP リクエストを行うことで、アシスト店長API にアクセスすることができます。

リクエストボディのJSONに日本語が含まれる場合は 文字コードはUTF-8、\uNNNN 形式でエンコードされている必要があります。

Authorizationヘッダに以下の形式でアクセストークンを付与し、APIへのリクエストを行います。

Authorization: Bearer {アクセストークン}

サンプルコード

※以下はサンプルです。URLやパラメータは便宜変更・修正してください。

アプリケーションのWebサーバのサンプル

<?php

define("OAUTH2_SITE", 'https://{アシスト店長ドメイン}');
define("OAUTH2_CLIENT_ID",'XXXXX');      // クライアントIDを入力します。
define("OAUTH2_CLIENT_SECRET", 'XXXXX'); // クライアントシークレットを入力します。
define("OAUTH2_REDIRECT_URI", 'http://example.com/index.php');

$code = $_GET['code'];
$state = sha1(uniqid(mt_rand(), true));
// 認可ページへリダイレクトする
if (empty($code)) {
    $params = array(
        'client_id'     => OAUTH2_CLIENT_ID,
        'redirect_uri'  => OAUTH2_REDIRECT_URI,
        'response_type' => 'code',
        'state'         => $state
    );
    $auth_url = OAUTH2_SITE . '/api/oauth/authorize.php?' . http_build_query($params);
    header('Location: ' . $auth_url);
    exit;
}

// 認可後
$params = array(
    'client_id'     => OAUTH2_CLIENT_ID,
    'client_secret' => OAUTH2_CLIENT_SECRET,
    'code'          => $code,
    'grant_type'    => 'client_credentials',
    'redirect_uri'  => OAUTH2_REDIRECT_URI
);
$request_options = array(
    'http' => array(
        'method'  => 'POST',
        'content' => http_build_query($params)
    )
);
$context = stream_context_create($request_options);

$token_url = OAUTH2_SITE . '/api/oauth/token.php';
$response_body = file_get_contents($token_url, false, $context);
$response_json = json_decode($response_body);

アクセストークンを用いたGETリクエストのサンプル

<?php

$arrParam = array();
$arrParam['serial_order_id'] = '5'


$api_url = 'https://{アシスト店長ドメイン}/api/v1/orders.php?' . http_build_query($arrParam);
$api = new HTTP_Request($api_url, $option);
// POSTで送信
$api->setMethod(HTTP_REQUEST_METHOD_GET);
// Header設定
$api->addHeader('Authorization', "Bearer {アクセストークン}");
// HTTPリクエスト実行 
$response_api = $api->sendRequest();
$status_code = $api->getResponseCode();
$response_body_api = $api->getResponseBody();
$response_body_api = json_decode($response_body_api);
?>

リフレッシュトークンサンプル
※アクセストークンが失効した際にご利用ください。

<?php

$token_url = 'https://aspXXX.raku2cube.com/XXX' . '/oauth/token.php';

// オプション指定
$option = array( 
    'timeout'           => '10', // タイムアウトの秒数指定 
    'allowRedirects'    => true, // リダイレクトの許可設定(true/false) 
    'maxRedirects'      => 3,        // リダイレクトの最大回数 
); 

$params = array(
    'grant_type'    => 'refresh_token',
    'client_id'  => 'クライアントID',
    'client_secret' => 'クライアントシークレット',
    'refresh_token'  => 'リフレッシュトークン'
);
$request_options = array(
    'http' => array(
        'method'  => 'POST',
        'content' => http_build_query($params)
    )
);

$http = new HTTP_Request($token_url, $option); 

$context = stream_context_create($request_options);

// POSTで送信
$http->setMethod(HTTP_REQUEST_METHOD_POST);

$response_body = file_get_contents($token_url, false, $context);

?>