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

カラーミーショップの便利機能にカラーミーショップAPI (Application Programming Interface) があります。カラーミーショップの公式ページに分かりやすい説明が載っていますので、引用してみます。ざっくりイメージを掴んでください。
引用元:機能一覧 - カラーミーショップAPI

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

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

外部アプリケーションを開発するにあたって、カラーミーショップからデータを取って利用する場合が多いんですが、API(=アプリケーションプログラミングインターフェース、出入り口みたいなもの)を通して行うわけです。

今回・次回で、カラーミーショップAPIを使う前準備についてとAPIを使って実際にアプリケーションを作る方法について解説します

今回は、カラーミーショップAPIを使う前準備として、アクセストークンを取得するところまで、手順をひとつずつ丁寧にみていきます。

0. ユーザーIDとパスワードの代わりになるもの

まず最初に、アクセストークンって何?という話からです。

説明のための登場人物は三者います。
・サービスプロバイダー…元々のサービスを提供している会社
・コンシューマー…APIを利用したアプリケーションの開発会社
・ユーザー…サービスを利用している人

さて、ここで。
コンシューマーが開発したアプリケーションを利用するとして、ユーザーはカラーミーショップのログインIDとパスワードをコンシューマーに渡さなければいけないとしたら、セキュリティ上かなり問題があります。

もうすこし限定的な権限のトークン(APIに対する鍵のようなもので、アクセストークンと呼びます)を代わりに渡して、それを持ってカラーミーショップのデータにアクセスしてもらえればと考えます。

このような権限の委譲とその手順を整えたものがOAuthになります。
参考1)APIアクセス権を委譲するプロトコル、OAuthを知る - @IT

1. カラーミーショップAPIに置きなおすと

アクセストークンをどのような手順で取得するのでしょうか。参考1のリンク先に図解がありますが、内容がすこし難しいですね。
厳密ではありませんが、カラーミーショップ周辺に置きなおして、身近なもので考えなおします。

ここでの登場人物も三者です。
・サービスプロバイダーはカラーミーショップ(GMOペパボ)
・コンシューマーはサードパーティーと呼ばれる外部の会社(たとえば、他ショッピングサイトとの在庫連動システムの開発会社)
・ユーザーはショップオーナー(自分)

Process1.
サードパーティーカラーミーショップのAPIを利用してアプリケーションを作成しようと考えました。カラーミーショップのデータを使わせてと連絡して、カラーミーショップはアプリケーションを識別するためのコンシューマキーとなりすまし防止用の電子署名としてコンシューマシークレットの二つを渡します。

Process2.
ショップオーナーサードパーティー製のアプリケーションに興味をもってこのサービスと利用しようと考えます。サードパーティーに使わせてと申し込みます。

Process3.
サードパーティーショップオーナーの権限の一部を委譲してもらうため、カラーミーショップに色々とお願いします。
カラーミーショップはまず、ショップオーナー本人であるかIDとパスワードを確認し、権限の委譲を承認するかどうか意志を確認します。

Process4.
カラーミーショップショップオーナーの承認を得て、サードパーティーに認可コード(鍵のようなもの)を渡します。
同時にショップオーナーサードパーティーの用意したアプリケーションに移動(リダイレクト)します。

Process5.
サードパーティーはリダイレクト先のアプリケーションで、識別用のコンシューマキー・コンシューマシークレットと、認可コード(ショップオーナーの承認)の三つ揃えて、あらためてカラーミーショップに提出します。

Process6.
カラーミーショップは全部揃っていることを確認して、サードパーティーアクセストークンを渡します。

Process7.
サードパーティーは受け取ったアクセストークンを使って、カラーミーショップAPIにリクエストを送ることができるようになります。欲しいデータを取ってきて、アプリケーションで使います。

Process8.
ショップオーナーサードパーティーのアプリケーションを利用できるようになります。

と、こんな感じで、カラーミーショップAPIを利用する前に、ショップオーナーの権限の一部をサードパーティーへ移譲して使ってもらう手続きを行う必要があります。
下記のAPIドキュメントを読む際に、いま何をやっているのか思い出せれば、理解が大分はかどります。

参考2)API ドキュメント - ネットショップの作成・運営なら店舗数No.1のカラーミーショップ

今回はアクセストークンを取得するところ(Process1.~Process6.)まで解説します。
APIドキュメントを補足する解説を書きましたので、以下をご参考にどうぞ。

2. カラーミーショップAPIの導入に必要なもの

カラーミーショップAPIに必要なもの

1. カラーミーデベロッパーアカウント
メールアドレスがあれば、すぐに取得できます。

2. APIのクライアントには以下が必要です
用語がいろいろと難しいですが、WebサーバーがあればOKです。

3. カラーミーデベロッパーアカウントの登録

サードパーティーが作成するアプリケーションでデータを使わせてもらうために、あらかじめカラーミーショップに登録します。

今回は、ショップオーナー自身でアプリケーション作成することを念頭に置いています。その場合はサードパーティー=ショップオーナーという関係になります。

リンクからデベロッパー登録してみましょう。
・登録はこちらカラーミーショップAPIのデベロッパー登録

メールアドレスとパスワードを入力し、[登録する]ボタンを押します。

カラーミーショップから仮登録メールが送信され、「カラーミーデベロッパー仮登録のご案内」という内容のメールが届きます。
登録完了のURLをクリックすると、デベロッパー登録が完了します。カラーミーショップAPIのデベロッパー登録ログイン画面

さきほど登録したメールアドレスとパスワードを入力して、ログインしてみましょう。

カラーミーショップAPIのデベロッパー登録のアプリ一覧

アプリケーション一覧が表示されます。追加前なので空です。

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

カラーミーショップAPIの登録ステップ1

1. OAuthアプリケーション登録
こちら からアプリケーション登録を行ってください。

このリンクは上の[アプリケーションを追加する]ボタンと同じページに移動します。どちらからでも大丈夫です。

上入力欄にアプリケーション名、下入力欄にリダイレクトURL(アプリケーションのファイル名とWebサーバー上の置き場所)を入力し、[保存]ボタンを押します。
名前は、今回はあまり重要ではありません(適当で)。

カラーミーショップAPIのデベロッパー登録のアプリ追加

カラーミーショップはクライアントIDとクライアントシークレットを返してくれます(コンシューマキーとコンシューマシークレットと同じ意味です)。カラーミーショップAPIのデベロッパー登録のクライアントID

サードパーティーが作成するアプリケーションの識別用に二つセットで使います。後で必要になりますのでメモしておきます。

[認可]ボタンは押しません(上手く動作しないときの確認テスト用)。

5. カラーミーショップアカウントの認証ページを表示します

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

ここからは、アプリケーションに興味をもったショップオーナーが権限の委譲を認可する手続きになります。

サードパーティーカラーミーショップに、ショップオーナーの本人確認と承認画面の表示をしてもらいます。
APIドキュメントにあるとおり、下のようなコードをブラウザのアドレスバーに入れてやればOKです。

必要なパラメータを仮セットした例

https://api.shop-pro.jp/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&response_type=code&scope=read_products%20write_products

CLIENT_ID、REDIRECT_URLなどはカラーミーショップに渡すパラメータです。上でメモしたものをコピペして、自分のアプリケーション用に書き換えます。
ここでは、クライアントIDはセットしますが、クライアントシークレットはセットしてませんね。

書き換えた後、ブラウザのアドレスバーにコピペすると、カラーミーショップのアプリケーション承認ページ ログイン画面が表示されます。
ログインIDとパスワードで、ショップオーナー本人か確認を行います。早速入力してログインしましょう。
カラーミーショップAPIのクレデンシャル

下のようなページに移動しました。
カラーミーショップAPIのクレデンシャル2

後で[承認する]ボタンを押しますが、いまはまだ押さないでください

「商品・在庫データの参照」「商品・在庫データを追加・更新」と表示されています。APIドキュメントのパラメータ scope(スコープ、与える権限の範囲)で選択可能です。

6. 認可コードを取得

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

APIドキュメントの順番もあって説明が後になりましたが、ショップオーナーが[承認する]ボタンを押す前に、サードパーティーはリダイレクト先のアプリケーションを作っておく必要があります。

今回はアクセストークンを取得するところまでですので、アプリケーションというとすこしおおげさですが。

アプリケーション追加でリダイレクトURLにhttp://example.com/auth.phpと設定しましたので、ファイル名をauth.phpとしてテキストエディタなどを作成します。中身は下記しました(あともうすこしだけ説明が続きます)。

APIドキュメントには「codeという名前のURLパラメータに認可コードが付与されます。」と書いてあります。
これは $code= $_GET['code'] という風にすれば、リダイレクト先のアプリケーションで認可コードが受け取れますよ、ということです。

7. 認可コードとアクセストークンを交換

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

auth.phpとして以下のコードを用意します。APIドキュメントに載っているものにすこし手を入れています。
コードは、認可コード、クライアントID、クライアントシークレットの三つ揃え、パラメータとして、カラーミーショップに提出して、結果を受け取る内容です。

最後のechoの行で、結果を画面表示するようにしています。

http://example.com/auth.php

<?php

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

  $code = $_GET['code'];

  $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 = 'https://api.shop-pro.jp/oauth/token';
  $response_body = file_get_contents($token_url, false, $context);

  echo $response_body; // 追加した行

ファイル (auth.php) が作成出来たらをWebサーバーにアップロードします。アップロード先とリダイレクトURLを揃えます。
以上の作業が終われば、さきほどの[承認する]ボタンを押します。上手くいくと、以下のような結果が表示されます。

結果

{"access_token":"xxxxx","token_type":"bearer","scope":"read_products write_products","created_at":yyyyy}

xxxxxの部分にアクセストークンが表示されます。あとで使いますので、メモしておきます。
アクセストークンは秘密の情報なので、取り扱いにはくれぐれも気を付けてください(他人に見せてはいけませんよ)。

8. おわりに

今回はAPIドキュメントの「1. OAuthアプリケーション登録」~「4. 認可コードとアクセストークンを交換」を丁寧にみていきました。
ようやく、カラーミーショップAPIを利用するためのアクセストークンを取得することができました。

なんでこんな手順が必要なんだろうと疑問に感じるかもしれませんが、サードパーティー=ショップオーナーの一人二役で手順をこなしているせいで、役割がわかりにくいからかもしれません。誰の手順か思い出すと、作業の意味が理解しやすくなります。

残りはAPIドキュメントの「5. アカウントの情報を取得するには」~「6. その他のAPIの呼び出し」になります。
次回はアクセストークンの使い方やアプリケーションの作り方を解説します。

お楽しみにどうぞ。

執筆者

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

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

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