カラーミーショップAPIの使い方を丁寧に解説します (実践編)

カラーミーショップAPIのアイキャッチ

カラーミーショップでは、機能を拡張するためのAPIを公開しています。APIを使って、既存の提供機能にない機能やアプリを開発したり、外部サービスとの連携を実装することができます。ご利用料金は無料。どなたでもご活用いただけるサービスです。

引用元:機能一覧 – カラーミーショップAPI

カラーミーショップの便利機能 カラーミーショップAPIの使い方を解説しています(全二回)。

前回APIドキュメントの前半部分、「1. OAuthアプリケーション登録」~「4. 認可コードとアクセストークンを交換」を解説しました。
今回は残りの後半部分、「5. アカウントの情報を取得するには」~「6. その他のAPIの呼び出し」を解説します。

復習ですが、カラーミーショップAPI(出入口)とアクセストークン(鍵)の関係になります。
今回はより実践的に、アクセストークンの使い方やアプリケーションの作り方を解説します。

アクセストークン取得のおさらい

サービスプロバイダー、コンシューマー、ユーザーの三者によるやりとりで、コンシューマーは無事アクセストークンを取得しました。

「2. カラーミーショップアカウントの認証ページを表示します」
「3. 認可コードを取得」
「4. 認可コードとアクセストークンを交換」

この三つの手順では、カラーミーショップに対してリクエストを送ったり、PHPを書いて処理したりして、手間のかかる作業を行いました。

実は、一度にまとめて処理するように書けるものでして、APIドキュメントの「6. その他のAPIの呼び出し」の「アプリケーションのWebサーバのサンプル」にあるコードがそうです。

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

<?php

define("OAUTH2_SITE", 'https://api.shop-pro.jp');
define("OAUTH2_CLIENT_ID",'XXXXX');      // クライアントIDを入力します。
define("OAUTH2_CLIENT_SECRET", 'XXXXX'); // クライアントシークレットを入力します。
define("OAUTH2_REDIRECT_URI", 'http://example.com/index.php'); // リダイレクトURL

$code = $_GET['code'];
// 認可ページへリダイレクトする
if (empty($code)) {
    $params = array(
        'client_id'     => OAUTH2_CLIENT_ID,
        'redirect_uri'  => OAUTH2_REDIRECT_URI,
        'response_type' => 'code',
        'scope'         => 'read_products write_products read_sales write_sales'
    );
    $auth_url = OAUTH2_SITE . '/oauth/authorize?' . 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'    => 'authorization_code',
    '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 . '/oauth/token';
$response_body = file_get_contents($token_url, false, $context);
$response_json = json_decode($response_body);

echo $response_body; // 追加した行

コードの前半部分が「2. カラーミーショップアカウントの認証ページを表示します」「3. 認可コードを取得」で、コードの後半部分が「4. 認可コードとアクセストークンを交換」になります。

追加した最終行(echo)で、アクセストークンを画面に出力しています。

使い方は、アプリケーション登録後に、上のコードに自分用のパラメータ(クライアントID、クライアントシークレット、リダイレクトURL)をセットして、ウェブサーバーにアップロードして、ブラウザから実行し、承認すると、アクセストークンが表示されます。

前回は各手順を理解するためにひとつずつ進めていきましたが、わかってしまえばこっちのほうが大分楽です。

アプリケーション作成前の注意点など

APIドキュメントに大事なことがいくつか書いてありますので、抜き出してみます。

委譲する権限

「2. カラーミーショップアカウントの認証ページを表示します」でscope(委譲の範囲)について記述があります。アプリケーションに必要な分だけ与えるようにしましょう。カラーミーショップAPIのスコープ

アクセストークンの有効期限はありません

毎回、アクセストークンを取得する必要はありません。
「アプリケーション側で保存しておくようにしてください」と記述がありますので、アプリケーション内に埋め込んで使います(データベースを使っているアプリケーションでは、アクセストークンを取得するコードをincludeで呼び出して、戻り値をデータベース上に保存するのだと思います)。

APIの呼び出し制限

API の呼び出し回数は 1 アクセストークンあたり 120 リクエスト/分 を目安にしてください。現在は超過したときの制限はありませんが、将来制限をする可能性もあります。

また、他の利用者に影響のあるような高頻度のアクセスを検知した場合、予告なくリクエストを制限させていただく場合があります。

引用元:APIの呼び出し制限

たとえば、1,500アクセス/日のページで、約1アクセス/分の計算になります。
カラーミーショップAPIにリクエストを送る場合、一度にどのくらいのリクエスト数なら余裕なのか、検討しておきましょう。

カラーミーショップAPI を使ってできること

受注、商品、顧客、設定情報などの参照。受注、商品などの更新。おすすめ情報(recommend、new arrivalなど) の削除、など。

参考1)カラーミーショップ API インターフェイス v1

カラーミーショップAPIのエンドポイント(たとえば、https://api.shop-pro.jp/v1/shop.json)やHTTPメソッド(GET、POST、PUT、DELETE)が掲載されています。
用意されているものを利用できるだけで、なんでもできるというわけではありません。

カラーミーショップAPIのエンドポイント

アクセストークンの使い方

カラーミーショップAPIの認証手順5

カラーミーショップAPIとのやりとりは毎回、APIドキュメントに例示されているこのコードです。

phpでの例

<?php
$request_options = array(
    'http' => array(
    'method' => 'GET',
    'header'=> "Authorization: Bearer 62971343fdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\r\n"
    )
);
$context = stream_context_create($request_options);

$url = 'https://api.shop-pro.jp/v1/shop.json';
$response_body = file_get_contents($url, false, $context);

「https://api.shop-pro.jp/v1/shop.json」がショップの基本情報を取得できるエンドポイントになります。HTTPメソッドはGET(=参照)を指定しています。
エンドポイントにリクエストを送る際に、アクセストークンもパラメータとして一緒に送ってやるわけです。

エンドポイントとHTTPメソッドを変更すると、欲しいデータの取得や更新などが可能です。

結果は$responce_bodyに、下のレスポンスに書いてあるようなJSONと呼ばれる書式で返ってきます。

カラーミーショップAPIのショップ情報

エンドポイントを指定するURLに、上例のようなリクエストパラメータを付けると、結果はidとtitleの項目に絞って返ってきます。

カラーミーショップAPIを何に利用するの?

アクセストークンの使い方は一通りOKだと思います。
さて、カラーミーショップAPIを実際に利用するとして、どんな使い方が考えられるでしょうか。
おおまかに分けて、二通りあります。

業務効率化

受注管理用に必要データを整形し出力したり、普段の業務を自動化・省力化したり。

ウェブサイトに表示

関連商品のようなものを表示して回遊性を上げたり。
独自タグがないために出力できない項目をページに表示したり。
受注を集計したランキングや、楽天市場で見かける注文速報みたいなの。

カラーミーショップにデータを渡す方法

業務効率化のアプリケーションの場合は、PHPでコードを書いて、プログラムを実行して、結果をecho関数で画面に出力すればいいんですが、もう一方、カラーミーショップに表示するようにするにはどうすればいいでしょうか?

カラーミーショップに表示する処理の流れはこんな感じ。
1. カラーミーショップからプログラムを実行
2. プログラムで結果を取ってくる
3. 結果をカラーミーショップに渡す
4. カラーミーショップで受け取って表示

2はショップ情報を取ってきた上のサンプルコードと基本的に同じです。
今回は新たに、1、4(カラーミーショップ側)、3(PHPプログラム側)を作ります。

サンプルコード(保有ポイント表示)

サンプルとして、カラーミーショップに会員の保有ポイントを表示するコードを書きました。
動作しないときは、以下の三つをご確認ください。
・カラーミーショップの管理画面で「ショップ作成>会員機能>会員専用ページを使用する」
・会員ログインしていない
・アクセストークンのスコープ

カラーミーショップ側

<{if $members_login_flg == true}>
<div id="dispPoint"></div>
<script type="text/javascript">
$.getJSONP = function(url,callback,param) {
    return $.ajax({
    url:  url,
    dataType:"jsonp",
    success:callback
    });
}
$.getJSONP("http://example.com/getPoint.php?id=" + <{$members_id}>, onDataHandler)
function onDataHandler(response) {
    $("#dispPoint").html("保有ポイント:" + response.point);
}
</script>
<{/if}>

getPoint.php

<?php
$request_options = array(
    'http' => array(
        'method'  => 'GET',
        'header'  => "Authorization: Bearer XXXXXXXXXXXXXXXXXXX\r\n"
    )
);
$context = stream_context_create($request_options);
$url = 'https://api.shop-pro.jp/v1/customers/' . $_GET['id'] . '.json';
$response_body = file_get_contents($url, false, $context);
$response_json = json_decode($response_body, true);

$output = array(
    'point' => $response_json['customer']['points']
);
header( 'Content-Type: text/javascript; charset=utf-8' );
echo $_GET['callback'] . '(' . json_encode($output). ')';

おわりに

ウェブサイトに表示するサンプルが、実践編のキモになります。
クロスドメイン制約、Ajax、JSONP、jQueryがキーワードになってきますので、興味があれば、検索して調べてください。サンプルがいくつも見つかると思います。

説明すべきかと思いましたが、検索すると資料も多かったので省略します。
下記の参考記事が読みやすかったので、挙げておきます。

参考2)なぜJSONPだとクロスドメイン制約を超えられるのか? - 射撃しつつ前転

追記)状況によっては、PHPで書いたページをiframeで読み込んでもいいと思います。

執筆者

えいじ@naeco.jp この記事を書いた人

メーカー系情報システム部門出身で、第一種情報処理技術者
個人事業主/カラーミー歴11年目/カラーミーショップ公認パートナー。
カスタマイズやモールへの出店作業 (CSV) をお手伝いしています。

ご相談・お問い合わせはこちら