> For the complete documentation index, see [llms.txt](https://apidocs.cs-cart.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.cs-cart.jp/getting-started/readme.md).

# APIの概要

## CS-Cart API概要

* [RESTful](http://ja.wikipedia.org/wiki/REST)である
* 管理者のメールアドレスと自動生成されるAPIキーを利用した `HTTP Basic認証` を利用します。
* APIはユーザーグループで定義された権限に依存しています。ユーザーグループの割り当てはオブジェクトに直接定義されています。
* RESTを使用するために `HTTP1.1` を使用しています。

以下の4つのメソッドによってデータの表示やオブジェクトの修正が可能です。

* `GET` —オブジェクトデータの取得
* `PUT` オブジェクトデータの更新
* `POST` —オブジェクトの新規作成
* `DELETE` —オブジェクト削除

`データの受け渡しは、JSONフォーマットで行います。`

## お役立ちツール

[cURL](http://ja.wikipedia.org/wiki/CURL)は簡単にHTTPリクエストを送信することができるクラスプラットフォームのコマンドラインアプリケーションです。UNIXベースのシステムでは、`curl`コマンドはデフォルトで利用可能です。

{% hint style="success" %}
TIPS

このガイドの全ての例はcURLコマンドとして書かれています。
{% endhint %}

## REST Console

[`REST Console`](https://apidocs.cs-cart.jp/getting-started/chrome.google.com/webstore/detail/rest-console/cokgbflfommojglbmbpenpphppikmonn)は人気のあるGoogle Chromeブラウザ用の拡張機能です。\
(同様の拡張機能は他の一般的なWebブラウザにも存在します)

＜画像＞

## APIアクセスのアクティベーション

APIアクセスはユーザーごとに有効／無効の切り替えが可能です。

APIアクセスを有効にするには：

1. CS-Cartの管理画面にログイン
2. `お客様→管理者` へ進む
3. APIアクセスを有効にするアカウントの詳細を開く
4. `APIアクセス`のタブに切り替え、`APIの利用を許可`にチェックを入れる
5. `保存` をクリック

APIキーが自動的に生成され、このユーザーのEメールとAPIキーを使ってCS-CartのAPIにアクセスが可能となります。

## URLs

APIのリクエストは特定のURLに通常のHTTPリクエストとして送信します。

CS-CartのAPIの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の商品のデータを参照できます。

{% hint style="warning" %}
注意

CS-Cartがインストールされたサーバーで`mod_rewrit`が無効になっている場合は、これらの例と異なるURLを使用しなければなりません：

* `<http://example.com/api.php?_d=:object&ajax_custom=1>` - 特定のタイプの全オブジェクトを参照
* <http://example.com/api.php?_d=:object/:id&ajax_custom=1`—refer> - 個々のオブジェクトを参照
* <http://example.com/api.php?_d=:object/:id/:nested_object&ajax_custom=1`—refer> - 特定のオブジェクトの入れ子になった全オブジェクトを参照
* <http://example.com/api.php?_d=:object/:id/:nested_object/:id&ajax_custom=1`—refer> - 特定のオブヘクトの入れ子になった個々のオブジェクトを参照
  {% endhint %}

## 認証

それぞれのリクエストは、ユーザーのメールアドレスとAPIキーを使って認証されなければなりません。

APIリクエストに認証データを送信するには以下の3つの方法があります：

`--user`パラメーター経由（全ての例はこの例で書かれています）

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

URL内でインラインで渡す：

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

{% hint style="info" %}
ヒント

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

### リクエストヘッダー

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

{% hint style="info" %}
HINT

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

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

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

## GET : データの参照

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

### リクエストの例

ID1の商品についてのデータを取得する：

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

### フィルタリング

フィルタリングを行うために追加のURLパラメーターを送信することができます。\
例えば、`送料無料でない商品をすべて取得する`：

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

フィルタリングの条件を組み合わせることが可能です。\
`company_id`が１の出品者の商品かつ、ダウンロード可能な商品をすべて取得します：

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

### 戻り値

条件に一致したオブジェクト(例：`商品のキー` )のJSON配列と検索クエリ(`検索キー`)またはエラーが返ってきます。

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

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

## PUT : データの更新

オブジェクトデータを更新するには、オブジェクトに対応するURLに`PUT` HTTPを送信します。

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

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

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

{% hint style="success" %}
重要

`Content-Type` のヘッダーは必ず `application/json` をセットして下さい。宣言が無い場合はデフォルトの `text/plain` が宣言され、リクエストは失敗します。
{% endhint %}

リクエスト例： ID1の商品の名前を更新する：

```shell
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のオブジェクトの各ページを参照してください。

{% hint style="success" %}
重要

`Content-Type` のヘッダーは必ず `application/json` をセットして下さい。宣言が無い場合はデフォルトの `text/plain` が宣言され、リクエストは失敗します。
{% endhint %}

### リクエスト例

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

```shell
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の持つ商品を削除する：

```shell
curl --user admin@example.com:APIkey -X DELETE 'http://example.com/api/products/12'
```

### 戻り値

操作が成功してもレスポンスはありません。