メニュー
GMOペパボ株式会社
API ドキュメント

はじめに

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

現在、以下の機能がAPIから利用できます。

  • 受注
    • 検索
    • 更新
    • 入金/配送等のステータスの更新
    • 配送先情報の更新
    • 配送手数料の更新
  • 顧客
    • 検索
  • 商品
    • 検索
    • カテゴリ情報の取得
    • 更新
      • 商品名の更新
      • 型番の更新
      • 表示ステータスの更新
      • 在庫の更新
      • 価格の更新
      • 簡易説明の更新
      • 説明の更新
      • スマートフォンショップ用説明の更新
      • カテゴリの更新
  • 設定情報の参照
    • 決済設定の参照
    • 配送設定の参照
    • ギフト設定の参照

必要なもの

  1. カラーミーデベロッパーアカウント
  2. APIのクライアントには以下が必要です
    • RESTfulなHTTPリクエスト
    • JSONのパースやシリアライズ
    • 認可コードの受け取り
      • カラーミーの認可ページからのHTTPリクエストを受けられるWebサーバ
      • または、スマートホンアプリのWebView

利用手順

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

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

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

※スマートホンのWebViewを利用する場合は、リダイレクトURLに urn:ietf:wg:oauth:2.0:oob を入力します。

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

https://api.shop-pro.jp/oauth/authorize に、必要なパラメータをつけてGETリクエストを行ってください。 カラーミーショップアカウントの認証を行うHTMLページが表示されます。

パラメータ名 有効な値
client_id アプリケーション詳細画面で確認できるクライアントID
response_type "code" を指定
scope 以下のうち、アプリケーションが利用したい機能をスペース区切りで指定
"read_products" = 商品データを参照
"write_products" = 在庫データを更新
"read_sales" = 受注・顧客データを参照
"write_sales" = 受注データを更新
redirect_uri アプリケーション登録時に入力したリダイレクトURLと同一のものを指定

(例

https://api.shop-pro.jp/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&response_type=code&scope=read_products%20write_products
  1. URLにアクセスすると、認可ページが表示されます。カラーミーショップアカウントを持つ利用者は、このページで、アプリケーションがショップのデータにアクセスすることを許可します。
  2. 初めて認可ページへ訪れる利用者は、カラーミーショップのID・パスワードの入力を求められます。

3. 認可コードを取得

利用者が認可ページにて承認ボタンを押下すると、カラーミーショップから認可コードが発行されるので、アプリケーションで認可コードを取得します。

Webサーバを用いる場合

  • redirect_uri に指定したURLへリダイレクトされます。
    • 承認された場合、 code という名前のURLパラメータに認可コードが付与されます。
    • 承認がキャンセルされた場合、またはエラーの場合、error パラメータにエラーの内容を表す英数字の文字列が付与されます。

WebViewを用いる場合

  • api.shop-pro.jp 上の結果ページへリダイレクトされます。
    • 承認された場合
      • 例) https://api.shop-pro.jp/oauth/authorize/569bc6eXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX へリダイレクトされます。URLのパスの最後が認可コードになっています。
    • 承認がキャンセルされた場合
      • https://api.shop-pro.jp/oauth/authorization_failed?error=XXXX&error_description=XXXX へリダイレクトされます。
      • error パラメータにエラーの内容を表す英数字の文字列が付与されます。

※認可コードの有効期限は10分間のみです。

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

認可コードを使って、アクセストークンを取得します。 以下のようなPOSTリクエストを、https://api.shop-pro.jp/oauth/token へ送ります。

リクエストパラメータ

パラメータ名 有効な値
client_id アプリケーション詳細画面に表示されているクライアントID文字列
client_secret アプリケーション詳細画面に表示されているシークレット文字列
code 1の手順で取得した認可コード文字列
grant_type "authorization_code" を指定
redirect_uri アプリケーション登録時に入力したリダイレクトURL
  • curlでの例
    $ curl -X POST \
    -d'client_id=CLIENT_ID' \
    -d'client_secret=CLIENT_SECRET' \
    -d'code=CODE' \
    -d'grant_type=authorization_code'   \
    -d'redirect_uri=REDIRECT_URI'  \
    'https://api.shop-pro.jp/oauth/token'
    
  • phpでの例
    <?php 
    $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);
    
  • Rubyでの例
    require 'rest-client'  # gem install rest-client
    
    parameters = 'client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI'
    RestClient.post 'https://api.shop-pro.jp/oauth/token', parameters
    

レスポンス

リクエストが成功すると、以下のようなレスポンスがJSONで返ります。

{"access_token":"d461ab8XXXXXXXXXXXXXXXXXXXXXXXXX","token_type":"beare
r","expires_in":null,"refresh_token":null,"scope":""}

access_token プロパティに格納されている値が、アクセストークンです。 アクセストークンを取得すれば、カラーミーショップ API にアクセスする準備は完了です。

  • アクセストークンの有効期限はありません。アプリケーション側で保存しておくようにしてください。
  • 認可コードをアクセストークンに交換できるのは1度だけです。
  • アクセストークンは、許可済みアプリケーション一覧画面から失効させることができます。

5. アカウントの情報を取得するには

  • 取得したアクセストークンを使って、/v1/shop.json へリクエストを送ると、アカウント情報のJSONを取得できます。
  • アクセストークンは、以下のようなHTTPヘッダーで送信します。
    Authorization: Bearer 0908dXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    

サンプルコード

  • ruby (oauth2 gem) の例
    # coding: utf-8
    require 'oauth2'
    
    client = OAuth2::Client.new(nil, nil, site: 'https://api.shop-pro.jp')
    access_token = OAuth2::AccessToken.new client, '62971343fd1bcXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
    
    access_token.get '/v1/shop.json'
    
  • 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);
    
  • curlの例
    curl -H'Authorization: Bearer 62971XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' https://api.shop-pro.jp/v1/shop.json
    

6. その他のAPIの呼び出し

  • アクセストークンつきで HTTP リクエストを行うことで、カラーミーショップ API にアクセスすることができます。
  • リクエスト、レスポンス、どちらも JSON でやりとりを行います。
  • 各 API は、URL と HTTP メソッドで操作を表します。
    • GET 参照
    • POST 新規登録
    • PUT 更新
    • DELETE 削除
  • POST,PUTの際には、ヘッダにContent-Type: application/jsonをつけ、 リクエストボディにJSONを送信します。
    • リクエストボディのJSONに日本語が含まれる場合は 文字コードはUTF-8、\uNNNN 形式でエンコードされている必要があります。
  1. Authorizationヘッダに以下の形式でアクセストークンを付与し、各APIへのリクエストを行います。
    Authorization: Bearer 0908dXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    
  2. 各APIの仕様はこちらのページを参照してください。

サンプルコード

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

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

  • PHP
    <?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');
    
    $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);
    
  • ruby (sinatra, oauth2) でのWebサーバ
    $ gem install oauth2
    $ gem install sinatra
    
    require "sinatra"
    require "oauth2"
    
    enable :sessions
    
    OAUTH2_SITE          = 'https://api.shop-pro.jp'
    OAUTH2_CLIENT_ID     = 'XXXXXXXXXXXXXXXXX'
    OAUTH2_CLIENT_SECRET = 'XXXXXXXXXXXXXXXXX'
    OAUTH2_REDIRECT_URI  = 'http://localhost:4567/callback'
    
    client = OAuth2::Client.new(OAUTH2_CLIENT_ID, OAUTH2_CLIENT_SECRET, :site => OAUTH2_SITE)
    
    get '/sign_in' do
      redirect client.auth_code.authorize_url(:redirect_uri => OAUTH2_REDIRECT_URI,
                                              :scope => "read_products write_products read_sales write_sales")
    end
    
    get '/sign_out' do
      session[:access_token] = nil
      redirect '/sign_in'
    end
    
    get '/callback' do
      new_token = client.auth_code.get_token(params[:code], :redirect_uri => OAUTH2_REDIRECT_URI)
      session[:access_token] = new_token.token
    end
    
    # アクセストークンオブジェクトを用いてAPIコールをすることができます。
    get '/get_sales' do
      access_token = OAuth2::AccessToken.new client, session[:access_token]
      access_token.get('/v1/sales.json').body
    end
    

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

  • curl
    curl -X PUT -H'Authorization: Bearer 62971XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' -H'Content-Type: application/json' -d'{"product":{"variants":[{"option1_value":"ややしっとり","option2_value":"S","stocks":10}]}}' https://api.shop-pro.jp/v1/products/39405572.json
    
  • php
    <?php
    $attributes = array("product" =>
        array("variants" => array(
                array("option1_value" => "ややしっとり", "option2_value" => "S", "stocks" => 20)
            )
        )
    );
    
    $request_options = array(
        'http' => array(
            'method'  => 'PUT',
            'header'=> "Authorization: Bearer 62971343fdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\r\n" . "Content-Type: application/json\r\n",
            'content' => json_encode($attributes)
        )
    );
    $context = stream_context_create($request_options);
    
    $url = 'https://api.shop-pro.jp/v1/products/39405572.json';
    $response_body = file_get_contents($url, false, $context);
    ?>
    
  • ruby (oauth2 gem)
    # coding: utf-8
    require 'oauth2'
    
    client = OAuth2::Client.new(nil, nil, site: 'https://api.shop-pro.jp')
    access_token = OAuth2::AccessToken.new client, '62971343fd1bcXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
    
    attributes = {
      product: {
        variants:[
          {option1_value: "ややしっとり", option2_value: "S", stocks: 10}
        ]
      }
    }
    
    access_token.put '/v1/products/39405572.json', body: attributes