# 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'
```

### 戻り値

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.cs-cart.jp/getting-started/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.