REST API

CS-Cart ではバージョン 4 以降、ECサイトやマーケットプレイスサイトと接するための API を提供しています。

APIは、以下のライセンスの全てで、管理者に登録したユーザーでの利用が出来ます。

  • CS-Cart Store Builder Plus
  • CS-Cart Store Builder Ultimate
  • CS-Cart Multi-Vendor Standard
  • CS-Cart Multi-Vendor Plus
  • CS-Cart Multi-Vendor Ultimate
  • CS-Cart Multi-Vendor Unlim

また、CS-Cart Multi-Vendor Plus、CS-Cart Multi-Vendor Ultimate、CS-Cart Multi-Vendor Unlimでは、出品者に登録したユーザーでの利用も可能です。

概要

  • RESTfulである。
  • HTTP Basic 認証を使用し、管理者のメールアドレス（CS-Cart Multi-Vendor PlusやUltimateでは出品者も可能）をログインとして使用し、自動生成された API キーをパスワードとして使用します。
  • ユーザーグループ定義の権限に依存します。ユーザーグループの割り当てはオブジェクト内で直接定義されます。
  • HTTP 1.1 を使用して REST を実装します。オブジェクトの表示と変更には 4 つのメソッドが使用できます。
    • GET：オブジェクトデータを取得する
    • PUT：オブジェクトデータを更新する
    • POST：新しいオブジェクトを作成する
    • DELETE： オブジェクトの削除
  • JSON 形式でデータを受け入れて返します。
  • サポートされるエンティティ
    • Auth
    • Blocks
    • Carts
    • Call Requests
    • Categories
    • Discussions
    • Languages
    • Langvars
    • Orders
    • Pages
    • Payment Methods
    • Products
    • Product Features
    • Product Variations
    • Product Variation Groups
    • Product Options
    • Product Option Combinations
    • Product Option Exceptions
    • Settings
    • Shipments
    • Shipping Methods
    • Statuses
    • Stores
    • Taxes
    • Users
    • Usergroups
    • Vendors
  • API レスポンスエラー

ご注意：出品者に登録したユーザーが利用できるのは、このうち、Categories、Orders、Products のみとなります。

便利なツール

cURL は、HTTP リクエストを簡単に送信できるクロスプラットフォームのコマンドラインアプリケーションです。UNIX ベースのシステムでは、通常、デフォルトで簡単なcurlコマンドを使用できます。

このガイドのすべての例は cURL コマンドとして示されています。

Postman は、人気のある Google Chrome ブラウザの拡張機能です。同様の拡張機能がすべての一般的な Web ブラウザに存在します。

APIアクセスの有効化

API アクセスはユーザーごとに有効化/無効化されます。

ユーザーの API アクセスを有効にするには、以下の手順で行います。

管理画面の上部メニューから「お客様 > 管理者」をクリック。

管理者一覧
管理者一覧

API アクセスを有効化する管理者アカウントを開きます (例：admin@example.com )

「API アクセス」タブに切り替えて、 「API の利用を許可」を「ON」に切り替えます。

最後に右上の「保存」ボタンをクリック。

自動生成された API キーは、このユーザーが API にアクセスするためにメールアドレスとともに使用します。

URL 

API リクエストは、特定の URL に送信される通常の HTTP リクエストです。

デフォルトでは、CS-Cart は API 1.0 を使用し、URL は次のように構築されます。

  • http://example.com/api/:object — 特定のタイプのすべてのオブジェクトを参照します
  • http://example.com/api/:object/:id — 単一のオブジェクトを参照します
  • http://example.com/api/:object/:id/:nested_object: — 特定のオブジェクトのすべてのネストされたオブジェクトを参照します
  • http://example.com/api/:object/:id/:nested_object/:id — 特定のオブジェクトの単一のネストされたオブジェクトを参照します

たとえば、http://example.com/api/product/1/features は、ID 1 の商品のデータを参照できます。

CS-Cart がインストールされているサーバでmod_rewriteが無効になっている場合は、別の URL を使用する必要があります。

  • http://example.com/api.php?_d=:object&ajax_custom=1 — 特定のタイプのすべてのオブジェクトを参照します
  • http://example.com/api.php?_d=:object/:id&ajax_custom=1 — 単一のオブジェクトを参照します
  • http://example.com/api.php?_d=:object/:id/:nested_object&ajax_custom=1 — 特定のオブジェクトのすべてのネストされたオブジェクトを参照します
  • http://example.com/api.php?_d=:object/:id/:nested_object/:id&ajax_custom=1 — 特定のオブジェクトの単一のネストされたオブジェクトを参照します

ただし、API 2.0 を推奨します。API 2.0 では、URL は次の構造になります。

  • http://example.com/api/2.0/:object — 特定のタイプのすべてのオブジェクトを参照します
  • http://example.com/api/2.0/:object/:id — 単一のオブジェクトを参照します
  • http://example.com/api/2.0/:object/:id/:nested_object: — 特定のオブジェクトのすべてのネストされたオブジェクトを参照します
  • http://example.com/api/2.0/:object/:id/:nested_object/:id — 特定のオブジェクトの単一のネストされたオブジェクトを参照します

認証

各リクエストはユーザーのメールアドレスと API キーで認証される必要があります。API リクエストで認証データを送信するには 3 つの方法があります。

--userパラメーター経由(これはすべての例で使用されています)

curl --user admin@example.com:APIkey -X GET 'http://example.com/api/users/'

URL をインラインで渡します。

curl --basic -X GET 'http://admin%40example.com:APIkey@example.com/api/users/'

メールアドレスの@は %40 に変換して下さい。

リクエストヘッダー内

curl --header 'Authorization: Basic <base64-encoded email:APIkey pair>=' -X GET 'http://example.com/api/users/'

メールアドレスとAPIキーはbase64にエンコードする必要があります。

メールアドレスと API キー を base64 にエンコードするPHPのサンプルコード


$token = base64_encode("email:APIkey");
$authHeaderString = 'Authorization: Basic ' . $token;

データの取得：GET 

オブジェクトデータを取得するには、GET HTTP リクエストをオブジェクトを参照するURLに送信します。

リクエストの例

ID 1 の商品に関するデータを取得します。

curl --user admin@example.com:APIkey -X GET 'http://example.com/api/products/1'

フィルタリング

追加の URL パラメーターを送信して、詳細なデータを取得することができます。

たとえば、送料無料ではないすべての商品を取得する。

curl --user admin@example.com:APIkey -X GET 'http://example.com/api/products?free_shipping=N'

条件は組み合わせることができます。

company_id1のすべてのダウンロード可能な商品を取得。

curl --user admin@example.com:APIkey -X GET 'http://example.com/api/products?is_edp=Y&company_id=1'

戻り値

一致するオブジェクト (productsキーなど) のJSON配列と検索クエリ (searchキー) またはエラーが戻ってきます。

一致するオブジェクトの値は、オブジェクト ID をキーとした配列として戻ってきます。

サポートされているすべてのオブジェクトのフィールドの完全なリストについては、API オブジェクトのページを参照してください。

データ更新：PUT

オブジェクトデータを更新するには、該当するオブジェクトを参照する URL に PUT HTTP リクエストを送信します。

特定のオブジェクト ID を参照する URL のみを使用できます (つまり、すべての商品を一度に更新することはできません)。

送信されるデータは、オブジェクトフィールドのキーと値の JSON 配列である必要があります (例：{'fieldName1: value1, fieldName2: value2}）

サポートされているすべてのオブジェクトのフィールドの完全なリストについては、API オブジェクトのページを参照してください。

Content-Typeのヘッダーは、必ずapplication/jsonを設定する必要があります。そうしないと、デフォルトのtext/plainが宣言され、リクエストは失敗します。

リクエストの例

ID 1 を持つ商品の名前を更新します。

curl --user admin@example.com:APIkey --header 'Content-Type: application/json' -d '{"product": "New Product Name"}' -X PUT 'http://example.com/api/products/1'

戻り値

更新されたオブジェクト ID (例：{"product_id":"1"}またはエラー)。

オブジェクトの作成：POST

オブジェクトを作成するには、対応するオブジェクトタイプを参照する URL に POST HTTP リクエストを送信します。

オブジェクトタイプ全体を参照する URL のみを使用できます(IDは使用できません)。

送信されるデータは、オブジェクトフィールドのキーと値の JSON 配列である必要があります (例：{'fieldName1: value1, fieldName2: value2}）

一部のフィールドはオブジェクトの作成に必須です。

サポートされているすべてのオブジェクトのフィールドの完全なリストについては、API オブジェクトのページを参照してください。

Content-Typeのヘッダーは、必ずapplication/jsonを設定する必要があります。そうしないと、デフォルトのtext/plainが宣言され、リクエストは失敗します。

リクエストの例

「My Awesome Product」という名前の新しい製品を作成します。

curl --user admin@example.com:APIkey --header 'Content-Type: application/json' -d '{"product": "My Awesome Product"}' -X POST 'http://example.com/api/products'

戻り値

作成されたオブジェクト ID (例：{"product_id":"1"}またはエラー)。

オブジェクトの削除：DELETE

オブジェクトを削除するには、該当するオブジェクトを参照する URL に DELETE HTTP リクエストを送信します。

特定のオブジェクト ID を参照する URL のみを使用できます （一度に全ての商品を削除することは出来ません）。

リクエストの例

ID 12 の製品を削除します。curl –user admin@example.com :APIkey -X DELETE ‘http://example.com/api/products/12’

戻り値

空のボディを持つ 204 応答。