1. Home
  2. API案内
  3. API基本ガイド

API基本ガイド

cafe24 APIは、ECプラットフォームをベースに構成され、RESTful方式で簡単・便利に使用できるように提供されます。

このガイドでは、APIを利用するために、基本的に知っておくべき内容をご案内しています。

目次

cafe24 API概要

cafe24 APIは、cafe24 ECプラットフォームと連携しサービスを提供するために、App Storeに入店している開発元やサードパーティソリューションプロバイダなどに提供しております。

cafe24 APIは、RESTfulなアーキテクチャとしてOauth V2ベースの認証システムと標準HTTP Request Method、リソースを予測できるエンドポイントURL、HTTPコードベースのエラーメッセージを提供します。

cafe24 API概要
用語 説明
API アプリケーション・プログラミング・インターフェース(Application Programming Interface)の略で、cafe24ECプラットフォームとアプリケーション、サービス、ライブラリなどの標準化された規約に相互の通信を行うことができるインタフェースを意味します。
RESTfulな方式で提供され、定められた規約(インタフェース、パラメータなど)を通じて通信が行われます。
Admin APIとFront APIに区分されており、Front APIは、認証を受けなくても呼び出しが可能なAPIで構成されています。
Entity cafe24ネットショップのAPIは、各リソースをEntityに区分して提供しています。
各Entityは、ネットショップで管理するリソースの単位を表しています。
サブEntity

サブEntityは、Entityに属する属性の中、N個が存在する属性を別々に分離して作成されたEntityを意味します。
サブEntityは、それ自体では照会したり、登録/修正することができず、常にURLの上位Entityを含む必要があります。


- 使用例

間違った例

GET https://{{mallid}}.cafe24api.com/api/v2/options


正しい例

GET https://{{mallid}}.cafe24api.com/api/v2/products/{#id}/options

サブEntityは、親Entityに属しているため、親Entityが生成される場合はサブEntityも同様に生成され、親Entityが削除される場合はサブEntityも削除されます。
関係型Entity

関係型Entityは、意味的に関係のあるEntity間の関係を表現したもので、もう少しセマンティックなAPIの使用のために作成されたEntityです。
関係型Entityは、特定Entityに属していないが、意味的に「~~に属するEntity(会員のカート、商品のいいね)」で表現することができます。
関係型Entityは、サブEntityとは異なり、Entityに属していない対等な関係で構成されています。


- 使用例

正しい例

GET https://{{mallid}}.cafe24api.com/api/v2/admin/wishes/{#id}

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products/{#id}/wishes

関係型Entityは、依存している関係ではないので関係あるEntityの作成、修正、削除、照会などに影響を受けません。
エンドポイント

APIを呼び出すことができるMethodとURLを意味します。
エンドポイントのMethod(POST、GET、PUT、DELETE)は、APIの動作を定義し、エンドポイントのURLは、APIの動作を認知的に示します。


- 使用例：商品(Products)Entityを登録する場合

POST https://{{mallid}}.cafe24api.com/api/v2/admin/products
リクエストパラメータ リクエストパラメータは、APIを呼び出すときに一緒に送信する必要がある値を意味します。
検索条件を追加したり、登録/修正する時、該当Entityの属性を定義することができます。
HTTPヘッダ HTTPヘッダには、Webサーバーに送信される要求を説明するメタ情報が含まれます。
APIリクエスト時、HTTPヘッダには、アクセストークンを含む要求する必要があります。(Admin APIの呼び出し時のみ)
レスポンスHTTPヘッダには、APIリクエスト数の制限値を含むさまざまなメタ情報が返されます。

リクエスト(Request)/レスポンス(Response) 形式

cafe24 APIのリクエスト(Request)とレスポンス(Response)の形式は、JSON Formatを対応しています。

リクエスト例

curl -X POST \
  '{endpoint_url}' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{ .... }'

正常レスポンス例

{
    "request": {
        "key": "value",
        "key": "value"
        }
}

正常レスポンス例

{
    "error": {
        "code": "エラーコード",
        "message": "エラーメッセージ",
        "more_info": {
        }
    }
}

個人情報保護のためのcafe24 APIは、HTTPSプロトコルのみ対応します。
Dates属性は、 ISO_8601 Formatに提供します。 ：YYYY-MM-DDTHH：MM：SS + 09：00

Method形式

cafe24の各リソースごとにCreate・Read・Update・Deleteを対応し、標準HTTP Methodを使用してAPIを使用することができます。

Method形式
区分 説明
POST 該当Entityを作成(Create)します。
GET 該当Entityの情報を照会(Read)します。
PUT 該当Entityを修正(Update)します。
DELETE 該当Entityを削除(Delete)します。

Front APIとAdmin API

各エンドポイント(End Point)に基づいてFront APIとAdmin APIをそれぞれ呼び出すことができます。

1. Front API

Front APIは、公開された情報(商品表示情報)やショップ顧客が自分の情報を照会したり、投稿などを作成するときに適しています。
Front APIは、Admin APIに比べて一部情報は限られています。

使用例

https://{{mallid}}.cafe24api.com/api/v2/sampleapi

2. Admin API

Admin APIは、ネットショップの管理者がショップの情報を照会したり、作成・修正・削除するのに適しています。
Admin APIは、Entityの情報をほとんど照会することができ、Oauth2.0方式の認証を通過した場合のみ使用することができます。

使用例

https://{{mallid}}.cafe24api.com/api/v2/admin/sampleapi

API照会使用方法

cafe24 APIは、データを照会する様々な方法を提供しています。
以下は、API照会時に様々なパラメータを使用してさまざまなデータを呼び出すことができる方法を説明しています。

1. 検索条件追加

API照会時、検索条件はエンドポイントにパラメータを追加して検索することができます。
複数の条件を共に検索する場合、「＆」区切り文字を使用して、検索条件を追加することができます。
開始日、終了日などの範囲を検索する場合にも、「＆」区切り文字を使用して検索することができます。

例）特定ブランドの中で、価格が1000円以上の商品を検索したい場合

GET https://{{mallid}}.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000

2.パラメータで複数の条件検索

APIで対応している場合、コンマ(、)を使用して複数の値を同時に検索することができます。
コンマ(、)で追加された検索条件は、OR条件で当該検索条件に該当するすべての値が検索されます。

例）11番、12番、13番商品コードを持っている商品の情報を照会する場合

GET https://{{mallid}}.cafe24api.com/api/v2/products?product_no=11,12,13

3.ショップの情報照会

API照会時に特定shop_noを指定すると、ショップの情報を照会することができます。
特定shop_noを指定しない場合、1番ショップ(基本ショップ)の情報を照会します。

例）パラメータに入力する方法

GET https://{{mallid}}.cafe24api.com/api/v2/products?shop_no=2

4.詳細照会と単件照会

多くのEntityは、URLにEntityのIDを明示して詳細照会することができます。
詳細検索は、Entityのみ照会することができますが、リスト照会する場合より多くのエントリが返されます。

例）128番の商品を詳細照会する方法

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products/128

リスト照会で例のようにパラメータを利用して単件を照会することができますが、この場合、リスト照会の単件照会としてリスト照会と同じ情報が照会されます。

例）128番商品をパラメータを利用して単件照会する場合

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?product_no=128

5. Pagination

リスト照会時、照会する項目が多すぎるとすべての結果が一度に照会されない場合があります。
一度に結果をより多く照会したい場合、「limit」パラメータを使用して照会件数を拡張することができます。
「limit」パラメータを使用しない場合、「limit」の基本値のみ照会されます。

例）商品を一度に100点照会する

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?limit=100

「limit」パラメータで拡張できる照会件数は、各APIごとに定義された「最大値」のみ拡張することができます。
もし「limit最大値」ですべてのデータを照会することができない場合、「offset」パラメータを使用することができます。

例）201番目の商品から300番目の商品まで照会する

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?limit=100&offset=201

6. Fieldパラメータ

APIの照会値のうち、特定の値だけ照会したいときは、fieldパラメータを使って、該当値を照会することができます。

例）商品照会時、商品名と商品番号のパラメータのみを照会する

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?fields=product_name,product_no

7. Embedパラメータ

商品照会時、商品に属するサブEntity(例：品目、在庫)を一緒に照会する場合は、「embed」パラメータを使うと、サブEntityのデータを一緒に照会することができます。
「embed」パラメータは、対応するAPIでのみ使用が可能です。

例）商品照会時、在庫と品目データを一緒に照会する

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?embed=variants,inventories

APIリクエスト数の制限ポリシー

cafe24 APIは、「Leaky Bucket」アルゴリズムで動作します。Leaky Bucketアルゴリズムは、パフォーマンスのために異常に多くのAPIリクエストのみに制限されて、通常のAPIリクエストは、特別な制約なしに利用できる効果があります。
cafe24 APIは、APIリクエストをBucketに保存します。Bucketは、ショップあたり最大10回になると、APIの呼び出しが制限されます。
Bucketは、1秒に1回ずつ減少し、減少した分再度APIの呼び出しを行うことができます。

 

- もしAppが1秒に1回ずつAPIを呼び出す場合、API呼び出しを何の制約なしに継続して使用することができます。
- 瞬間的に1秒以内に10回以上のコールが発生した場合、429エラー(Too Many Request)を返します。

 

HeaderにX-Api-Call-Limitを確認すると429エラーを回避することができます。
このショップでどれほどAPIを呼び出したのか、そしてBucketの残量がどのぐらい残っているかを確認することができます。

例）HeaderのX-Api-Call-Limitを確認

X-Api-Call-Limit : 1/10
該当値は、時間が経つにつれて減少します。もし、その値が「9/10」なら、3秒を待つと「6/10」に減少します。