cafe24 APIは、ECプラットフォームをベースに構成され、RESTful方式で簡単・便利に使用できるように提供されます。
このガイドでは、APIを利用するために、基本的に知っておくべき内容をご案内しています。
cafe24 APIは、cafe24 ECプラットフォームと連携しサービスを提供するために、App Storeに入店している開発元やサードパーティソリューションプロバイダなどに提供しております。
cafe24 APIは、RESTfulなアーキテクチャとしてOauth V2ベースの認証システムと標準HTTP Request Method、リソースを予測できるエンドポイントURL、HTTPコードベースのエラーメッセージを提供します。
用語 | 説明 |
---|---|
API | アプリケーション・プログラミング・インターフェース(Application Programming Interface)の略で、cafe24ECプラットフォームとアプリケーション、サービス、ライブラリなどの標準化された規約に相互の通信を行うことができるインタフェースを意味します。 RESTfulな方式で提供され、定められた規約(インタフェース、パラメータなど)を通じて通信が行われます。 Admin APIとFront APIに区分されており、Front APIは、認証を受けなくても呼び出しが可能なAPIで構成されています。 |
Entity | cafe24ネットショップのAPIは、各リソースをEntityに区分して提供しています。 各Entityは、ネットショップで管理するリソースの単位を表しています。 |
サブEntity | サブEntityは、Entityに属する属性の中、N個が存在する属性を別々に分離して作成された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です。 - 使用例 正しい例 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を意味します。 - 使用例:商品(Products)Entityを登録する場合 POST https://{{mallid}}.cafe24api.com/api/v2/admin/products |
リクエストパラメータ | リクエストパラメータは、APIを呼び出すときに一緒に送信する必要がある値を意味します。 検索条件を追加したり、登録/修正する時、該当Entityの属性を定義することができます。 |
HTTPヘッダ | HTTPヘッダには、Webサーバーに送信される要求を説明するメタ情報が含まれます。 APIリクエスト時、HTTPヘッダには、アクセストークンを含む要求する必要があります。(Admin APIの呼び出し時のみ) レスポンスHTTPヘッダには、APIリクエスト数の制限値を含むさまざまなメタ情報が返されます。 |
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
cafe24の各リソースごとにCreate・Read・Update・Deleteを対応し、標準HTTP Methodを使用してAPIを使用することができます。
区分 | 説明 |
---|---|
POST | 該当Entityを作成(Create)します。 |
GET | 該当Entityの情報を照会(Read)します。 |
PUT | 該当Entityを修正(Update)します。 |
DELETE | 該当Entityを削除(Delete)します。 |
各エンドポイント(End Point)に基づいてFront APIとAdmin APIをそれぞれ呼び出すことができます。
Front APIは、公開された情報(商品表示情報)やショップ顧客が自分の情報を照会したり、投稿などを作成するときに適しています。
Front APIは、Admin APIに比べて一部情報は限られています。
使用例
https://{{mallid}}.cafe24api.com/api/v2/sampleapi
Admin APIは、ネットショップの管理者がショップの情報を照会したり、作成・修正・削除するのに適しています。
Admin APIは、Entityの情報をほとんど照会することができ、Oauth2.0方式の認証を通過した場合のみ使用することができます。
使用例
https://{{mallid}}.cafe24api.com/api/v2/admin/sampleapi
cafe24 APIは、データを照会する様々な方法を提供しています。
以下は、API照会時に様々なパラメータを使用してさまざまなデータを呼び出すことができる方法を説明しています。
API照会時、検索条件はエンドポイントにパラメータを追加して検索することができます。
複数の条件を共に検索する場合、「&」区切り文字を使用して、検索条件を追加することができます。
開始日、終了日などの範囲を検索する場合にも、「&」区切り文字を使用して検索することができます。
例)特定ブランドの中で、価格が1000円以上の商品を検索したい場合
GET https://{{mallid}}.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000
APIで対応している場合、コンマ(、)を使用して複数の値を同時に検索することができます。
コンマ(、)で追加された検索条件は、OR条件で当該検索条件に該当するすべての値が検索されます。
例)11番、12番、13番商品コードを持っている商品の情報を照会する場合
GET https://{{mallid}}.cafe24api.com/api/v2/products?product_no=11,12,13
API照会時に特定shop_noを指定すると、ショップの情報を照会することができます。
特定shop_noを指定しない場合、1番ショップ(基本ショップ)の情報を照会します。
例)パラメータに入力する方法
GET https://{{mallid}}.cafe24api.com/api/v2/products?shop_no=2
多くの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
リスト照会時、照会する項目が多すぎるとすべての結果が一度に照会されない場合があります。
一度に結果をより多く照会したい場合、「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
APIの照会値のうち、特定の値だけ照会したいときは、fieldパラメータを使って、該当値を照会することができます。
例)商品照会時、商品名と商品番号のパラメータのみを照会する
GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?fields=product_name,product_no
商品照会時、商品に属するサブEntity(例:品目、在庫)を一緒に照会する場合は、「embed」パラメータを使うと、サブEntityのデータを一緒に照会することができます。
「embed」パラメータは、対応するAPIでのみ使用が可能です。
例)商品照会時、在庫と品目データを一緒に照会する
GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?embed=variants,inventories
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」に減少します。