以下のリンクから各サービスごとのAPIガイドを確認することができます。

Cafe24 Storeに出店しアプリサービスの提供を行っている開発・制作会社向けのOpen APIです。

Admin API
Cafe24ショップにおける商品・注文・会員・掲示板などの情報を照会・作成・修正・削除する際に使用できるAPIです。

詳細を見る
Front API
ショップに登録されている商品の情報を照会する際や「カートに入れる」機能を利用する際に使用できます。

詳細を見る
D.Collection API
D.Collectionプログラムに参加しているショップのショップ情報および商品情報を照会し、対象ショップの販売を促すことを目的とするサービスを制作する際に使用できるAPIです。

詳細を見る
Cafe24 Analytics API (Beta)
ショップのユーザー行動データ提供を目的とするサービスを制作する際に使用できるAPIです。

바로가기

non-print

Admin API

Introduction

Cafe24 API

cafe24のショップAPIは、cafe24のショップと連動してサービスを提供するアプリストアパートナー、サードパーティソリューション提供者などに提供するAPIです。

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

API Diagram

リソース間の関係を表したダイアグラムを通して、Cafe24 APIの全体的な構造を確認することができます。

Request/Response Format

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

要求例題(検索)

要求例題(登録/修正)

正常応答例題

{
  "resource": {
      "key": "value",
      "key": "value"
   }
}

エラー応答例題

{
  "error": {
      "code": "error code",
      "message": "error message",
      "more_info": {
      }
  }
}

Method

リソース別にCreate、Read、Update、Deleteを提供し、標準HTTP Methodを使ってAPIを使用することができます。

POST : リソースを生成(Create)します。
GET : リソースの情報を検索(Read)します。
PUT : リソースを修正(Update)します。
DELETE : リソースを削除(Delete)します。

Admin API Intro

Admin APIはショップの管理者によるショップ情報の検索、生成、修正、削除に適合しています。Admin APIはリソースの情報の大半を検索することができ、OAuth2.0方式の別途認証をパスした場合のみ使用できます。

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

API Status Code

Code	発生事例	エラーの解決方法
200	GET成功、PUT成功、DELETE成功時
201	POST成功時
207	多重要求登録時、ステータスが客体別に異なる場合	エラーの状況を客体別に確認し、状況によって対応します。
400	サーバーが要求を理解できない 1) Content-Typeの指定が間違っている 2) application/typeがjsonではない	要求時に「Content-Type」がapplication/jsonになっているか確認します。
400	要求API URLにハングルまたは記号をエンコードせずにそのまま使った場合	要求API URLにハングルまたは記号をURLエンコードしたか確認します。
401	1) Access Token がない状況で呼び出した場合 2) Access Tokenが有効ではない場合 3) Access Tokenが満了した場合 4) 不明なクライアントの場合	有効な手続きを踏んで発行されたAccess Tokenを使っているか確認します。
401	Front APIの使用時にclient_idを入力していない場合	有効なクライアントIDを使っているか確認します。
403	1) Access Tokenはあるが、Scopeに対する権限がない 2) FrontAPIで見る権限がない場合	APIを呼び出す権限があるか、APIのScopeまたはショップの設定を確認します。
403	httpsプロトコルではない場合	API要求時にhttpsで要求したか確認します。
403	新バージョンの商品管理を使うショップではない場合	新バージョンの商品管理にショップを更新しないと使用できません。
403	(Admin API呼び出し時)ショップでそのアプリが削除された場合	ショップにアプリがインストールされているか確認し、アプリを再インストールします。
403	(Front API呼び出し時)ショップでそのアプリが削除された場合	ショップにアプリがインストールされているか確認し、アプリを再インストールします。
404	1) API URLを間違って呼び出した場合 2) リソースが見つからない場合 3) {#id}がない場合	エンドポイントURLにエラーがないか、API文書を参考に確認します。
409	同じリソースで同じ内容を更新する場合	編集するデータをリクエストしてください。
422	検索/処理を要求した時、値が決まっているスペックと違う場合 1) 必須パラメーター抜け 2) 決まっているスペックと違う場合	API文書を参考に必須パラメーターが入力されていないか、有効でない値が入力されているか確認します。
429	クライアントのAPI要求がBucketを超過した場合	API最大許容要求件数を超過しないようにしばらくしてからもう一度要求します。
500	内部サーバーエラー、不明なエラー	一時的にエラーが発生しました。しばらくしてからもう一度お試しください。
503	現在のサーバーがダウンした場合	開発者センターにお問い合わせください。
503	サーバーがダウンした場合。APIが使用できない	開発者センターにお問い合わせください。
504	要求時間を超過した場合(Timeout)	一時的にエラーが発生し、応答が遅れています。しばらくしてからもう一度お試しください。

How to use GET API

cafe24のAPIはデータを検索する多様な方法を提供しています。

次はAPIの検索時に多様なパラメーターを使って多様な方法でデータを呼び出す方法を説明しています。

1. 検索条件の追加

検索を行う際、エンドポイントにパラメーターを追加すると検索条件を追加することができます。

複数の条件に一致する結果を見つけたい場合、「&」を使用して検索条件を追加することができます。

APIで対応している場合、タイムゾーンを使用して日付･時間の検索も可能です。

  検索条件の追加  
 例) 特定のブランドの商品の中で、商品の販売価格が1,000円以上の商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000

例) 商品登録日の範囲を指定して商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?created_start_date=2018-01-03&created_end_date=2018-02-03

例) 商品修正日の範囲を指定して商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?updated_start_date=2018-01-03T14:01:26+09:00&updated_end_date=2018-02-03T14:01:26+09:00 

2. カンマ(，)を使用した複数の値の検索

APIで対応している場合、カンマ(，)を使用して複数の値を同時に検索することができます。 (ただし、入力する項目の数は100件以下に調整してください。)

カンマ(，)で追加した検索条件はOR条件となり、条件を満たすすべての値が検索されます。

  カンマ(，)を使用した複数の値の検索  
 例) 特定の商品番号を指定して商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?product_no=11,12,13

例) 特定の商品番号と商品コードを指定して商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?product_no=11,12,13&product_code=P000000X,P000000W 

3. 越境ECショップ情報の検索

特定の越境ECショップ番号を明示することで、該当するショップの情報を検索することができます｡

越境ECショップ番号を明示しない場合は基本ショップの情報が検索されます。

  越境ECショップ情報の検索  
 例) 特定の越境ECショップの商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?shop_no=2 

4. 詳細検索と単独(1件)検索

リソースのIDを明示することで詳細検索を行うことができます。

詳細検索では1件のリソースのみを対象に検索を行うことが可能ですが、リスト検索より多くの項目が返されます。

  詳細検索と単独(1件)検索  
 例) 特定の商品番号を指定して商品の詳細検索を行う場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products/128


例) 特定の商品番号を指定して商品の単独(1件)検索を行う場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products?product_no=128 

5. Pagination

検索結果が多い場合、指定された「limit」のデフォルト値に基づいて結果が返されます。

「limit」パラメーターを利用して検索件数を増やすことが可能ですが、値が各APIに定義されている上限(最大値)を超えることはできません。

「limit」を利用する際の最大値ですべてのデータを検索できない場合、「offset」パラメーターで問題を解決することができます。

  Pagination  
 例) 100点の商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products?limit=100


例) 201番目から300番目までの商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products?limit=100&offset=200 

6. 特定項目の検索

「fields」パラメーターを利用すると、特定の項目のみを検索することができます

  特定項目の検索  
 例) 「商品名」と「商品番号」項目のみを検索する場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products?fields=product_name,product_no 

7. サブリソースの検索

APIで対応している場合、「embed」パラメーターを利用することでサブリソースのデータを一緒に検索することができます。

  サブリソースの検索  
 例) 商品を検索する際において「品目」と「在庫」のデータを一緒に検索する場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products/570?embed=variants,inventories 

API Limit

cafe24のAPIは「Leaky Bucket」アルゴリズムで動きます。Leaky Bucketアルゴリズムは性能を高めるために非正常的に多いAPI要求のみ制限し、日常的なAPI要求は特に制限なく使えます。

cafe24のAPIはAPI要求をBucketに蓄積しておきます。Bucketはショップ当たり「呼び出し件数制限」を超過するとAPI呼び出しが制限されます。Bucketは1秒に2回ずつ減少し、減少した分だけ再度API呼び出しができます。

アプリが1秒に2回ずつAPIを呼び出す場合は特に制限なくAPI呼び出しを使い続けることができます。
瞬間的に1秒以内に「呼び出し件数制限」以上のコールが発生する場合は、429エラー(Too Many Request)を返還します。
Bucket限度内の呼び出しであっても、該当のショップにて同一IPによる1秒あたり10回以上の呼び出しが発生した場合、異常な呼び出しとみなされることがあります。

Headerに「X-Api-Call-Limit」を確認すると429 エラーを避けることができます。ショップのAPI呼び出し件数とBucketの余裕分を確認することができます。

X-Api-Call-Limit : 1/40

Versioning

Version yyyy-mm-dd

以前のバージョンと互換性のない変更事項に対して、日付形式でバージョンを提供します。

custom headers "X-Cafe24-Api-Version"を利用して希望のバージョンを指定することができ、バージョンを指定せずAPIにリクエストする場合は、アプリのバージョンで動作します。

アプリのバージョンは、以下の方法で確認及び変更することができます。

管理コンソールにログイン > Apps > アプリ管理 > 開発関連情報 > 認証情報のバージョン管理

バージョンの満了期間は、最新バージョンがリリースされた時点から最大１年となります。

該当のバージョンの満了後は、満了日の時点でリリース日が最も古いバージョンで動作します。

例示コード(要求)

Authentication

Get Authentication Code

トークン発行要求時に使われたcodeは再使用できず、コード発行後1分が経過すると満了します。

{mallid} : ショップのIDを入力します。
{client_id} : 開発者センターで作成したアプリのclient_idを入力します。
{state} : 偽変造を防止するために入力する値にコード返還時に同じ値が返還されます。
{redirect_uri} : 開発者センターで作成したアプリのRedirect URLを入力します。
{scope} : アクセストークンでアクセスするリソースサーバーの権限を入力することができます。

アクセストークンの発行のためにはまずアクセスコードを要求しなければなりません。アクセスコードはクライアントがウェブアプリケーションの形態である場合に利用されます。コードの要求はcURLではなくウェブブラウザーで行わなければなりません。

  例示コード(要求)  
 GET 'https://{mallid}.cafe24api.com/api/v2/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}&scope={scope}' 
  例示コード(応答)  
 HTTP/1.1 302 Found
Location: {redirect_uri}?code={authorize_code}&state={state} 

Get Access Token

発行された認証コードを使用し、実際にAPIの呼び出しができるユーザートークン(Access Token、Refresh Token)をもらうことができます。

{mallid}: ショップのIDを入力します。
{client_id}: 開発者センターで作成したアプリのclient_idを入力します。
{client_secret}: 開発者センターで作成したアプリのclient_secretを入力します。
{code}: 発行されたコードを入力します。
{redirect_uri}: 開発者センターで作成したアプリのRedirect URLを入力します。

access_token: アクセストークンで、クライアントがリソースサーバーにアクセスする時に使われます。

refresh_token: アクセストークン満了後に再発行するために使うトークンです。

例示コード(要求)

例示コード(応答)

HTTP/1.1 200 OK
{
    "access_token": "0iqR5nM5EJIq..........",
    "expires_at": "2021-03-01T14:00:00.000",
    "refresh_token": "JeTJ7XpnFC0P..........",
    "refresh_token_expires_at": "2021-03-15T12:00:00.000",
    "client_id": "BrIfqEKoPxeE..........",
    "mall_id": "yourmall",
    "user_id": "test",
    "scopes": [
        "mall.read_order",
        "mall.read_product",
        "mall.read_store",
        "...etc...",
    ],
    "issued_at": "2021-03-01T12:00:00.000"
}

Get Access Token using refresh token

アクセストークンは発行後2時間が経過すると使えません。リソースサーバーにアクセスするためにはアクセストークン満了後に再発行が必要です。すでにアクセストークンが発行された場合はrefresh_tokenを使ってアクセストークンの再発行が可能です。

refresh tokenは2週間有効で、refresh token満了前に要求すると更新されたaccess tokenと更新されたrefresh tokenが一緒に返還されます。既存のrefresh tokenは満了処理され、使用できません。

発行された認証コードを使って実際にAPIの呼び出しができるユーザートークン(Access Token、Refresh Token)をもらうことができます。

{mallid} : ショップのIDを入力します。
{domain}:ショップのドメインを入力します。
{client_id} : 開発者センターで作成したアプリのclient_idを入力します。
{client_secret}: 開発者センターで作成したアプリのclient_secretを入力します。
{refresh_token}:トークン発行時にもらったrefresh_tokenを入力します。

access_token : アクセストークンで、クライアントがリソースサーバーにアクセスする時に使われます。

refresh_token : アクセストークン満了後に再発行するために使うトークンです。

例示コード(要求)

例示コード(応答)

HTTP/1.1 200 OK
{
    "access_token": "21EZes0dGSfN..........",
    "expires_at": "2021-03-01T15:50:00.000",
    "refresh_token": "xLlhWztQHBik............",
    "refresh_token_expires_at": "2021-03-15T13:50:00.000",
    "client_id": "BrIfqEKoPxeE..........",
    "mall_id": "yourmall",
    "user_id": "test",
    "scopes": [
        "mall.read_order",
        "mall.read_product",
        "mall.read_store",
        "...etc...",
    ],
    "issued_at": "2021-03-01T13:50:00.000"
}

Revoke Access Token

特定のアクセストークンを取り消すことができます。

アクセストークンが取り消された場合、要求されたアクセストークンのリフレッシュトークンも同時に取り消されます。

{mallid} : ショップのIDを入力します。
{domain}: ショップのドメインを入力します。
{client_id} : 開発者センターで作成したアプリのclient_idを入力します。
{client_secret}: 開発者センターで作成したアプリのclient_secretを入力します。
{token} : 取り消すアクセストークンを入力してください。

例示コード(要求)

例示コード(応答)

HTTP/1.1 200 OK

REST API

Front API

Introduction

Cafe24 API

Front API Intro

Front APIは公開されている情報(商品表示情報)またはショップの顧客が本人の情報を検索したり投稿を作成したりする場合に適合しています。Front APIはAdmin APIに比べて一部の情報は制限されています。

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

API Diagram

リソース間の関係を表したダイアグラムを通して、Cafe24 APIの全体的な構造を確認することができます。

Request/Response Format

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

要求例題(検索)

要求例題(登録/修正)

正常応答例題

{
  "resource": {
      "key": "value",
      "key": "value"
   }
}

エラー応答例題

{
  "error": {
      "code": "error code",
      "message": "error message",
      "more_info": {
      }
  }
}

API Status Code

Code	発生事例	エラーの解決方法
200	GET成功、PUT成功、DELETE成功時
201	POST成功時
207	多重要求登録時、ステータスが客体別に異なる場合	エラーの状況を客体別に確認し、状況によって対応します。
400	サーバーが要求を理解できない 1) Content-Typeの指定が間違っている 2) application/typeがjsonではない	要求時に「Content-Type」がapplication/jsonになっているか確認します。
400	要求API URLにハングルまたは記号をエンコードせずにそのまま使った場合	要求API URLにハングルまたは記号をURLエンコードしたか確認します。
401	1) Access Token がない状況で呼び出した場合 2) Access Tokenが有効ではない場合 3) Access Tokenが満了した場合 4) 不明なクライアントの場合	有効な手続きを踏んで発行されたAccess Tokenを使っているか確認します。
401	Front APIの使用時にclient_idを入力していない場合	有効なクライアントIDを使っているか確認します。
403	1) Access Tokenはあるが、Scopeに対する権限がない 2) FrontAPIで見る権限がない場合	APIを呼び出す権限があるか、APIのScopeまたはショップの設定を確認します。
403	httpsプロトコルではない場合	API要求時にhttpsで要求したか確認します。
403	新バージョンの商品管理を使うショップではない場合	新バージョンの商品管理にショップを更新しないと使用できません。
403	(Admin API呼び出し時)ショップでそのアプリが削除された場合	ショップにアプリがインストールされているか確認し、アプリを再インストールします。
403	(Front API呼び出し時)ショップでそのアプリが削除された場合	ショップにアプリがインストールされているか確認し、アプリを再インストールします。
404	1) API URLを間違って呼び出した場合 2) リソースが見つからない場合 3) {#id}がない場合	エンドポイントURLにエラーがないか、API文書を参考に確認します。
409	同じリソースで同じ内容を更新する場合	編集するデータをリクエストしてください。
422	検索/処理を要求した時、値が決まっているスペックと違う場合 1) 必須パラメーター抜け 2) 決まっているスペックと違う場合	API文書を参考に必須パラメーターが入力されていないか、有効でない値が入力されているか確認します。
429	クライアントのAPI要求がBucketを超過した場合	API最大許容要求件数を超過しないようにしばらくしてからもう一度要求します。
500	内部サーバーエラー、不明なエラー	一時的にエラーが発生しました。しばらくしてからもう一度お試しください。
503	現在のサーバーがダウンした場合	開発者センターにお問い合わせください。
503	サーバーがダウンした場合。APIが使用できない	開発者センターにお問い合わせください。
504	要求時間を超過した場合(Timeout)	一時的にエラーが発生し、応答が遅れています。しばらくしてからもう一度お試しください。

How to use GET API

cafe24のAPIはデータを検索する多様な方法を提供しています。

次はAPIの検索時に多様なパラメーターを使って多様な方法でデータを呼び出す方法を説明しています。

1. 検索条件の追加

検索を行う際、エンドポイントにパラメーターを追加すると検索条件を追加することができます。

複数の条件に一致する結果を見つけたい場合、「&」を使用して検索条件を追加することができます。

APIで対応している場合、タイムゾーンを使用して日付･時間の検索も可能です。

  検索条件の追加  
 例) 特定のブランドの商品の中で、商品の販売価格が1,000円以上の商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000

例) 商品登録日の範囲を指定して商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?created_start_date=2018-01-03&created_end_date=2018-02-03

例) 商品修正日の範囲を指定して商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?updated_start_date=2018-01-03T14:01:26+09:00&updated_end_date=2018-02-03T14:01:26+09:00 

2. カンマ(，)を使用した複数の値の検索

カンマ(，)で追加した検索条件はOR条件となり、条件を満たすすべての値が検索されます。

  カンマ(，)を使用した複数の値の検索  
 例) 特定の商品番号を指定して商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?product_no=11,12,13

例) 特定の商品番号と商品コードを指定して商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?product_no=11,12,13&product_code=P000000X,P000000W 

3. 越境ECショップ情報の検索

特定の越境ECショップ番号を明示することで、該当するショップの情報を検索することができます｡

越境ECショップ番号を明示しない場合は基本ショップの情報が検索されます。

  越境ECショップ情報の検索  
 예) 特定の越境ECショップの商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/products?shop_no=2 

4. 詳細検索と単独(1件)検索

リソースのIDを明示することで詳細検索を行うことができます。

詳細検索では1件のリソースのみを対象に検索を行うことが可能ですが、リスト検索より多くの項目が返されます。

  詳細検索と単独(1件)検索  
 例) 特定の商品番号を指定して商品の詳細検索を行う場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products/128


例) 特定の商品番号を指定して商品の単独(1件)検索を行う場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products?product_no=128 

5. Pagination

検索結果が多い場合、指定された「limit」のデフォルト値に基づいて結果が返されます。

「limit」パラメーターを利用して検索件数を増やすことが可能ですが、値が各APIに定義されている上限(最大値)を超えることはできません。

「limit」を利用する際の最大値ですべてのデータを検索できない場合、「offset」パラメーターで問題を解決することができます。

  Pagination  
 例) 100点の商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products?limit=100


例) 201番目から300番目までの商品を検索する場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products?limit=100&offset=200 

6. 特定項目の検索

「fields」パラメーターを利用すると、特定の項目のみを検索することができます

  特定項目の検索  
 例) 「商品名」と「商品番号」項目のみを検索する場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products?fields=product_name,product_no 

7. サブリソースの検索

APIで対応している場合、「embed」パラメーターを利用することでサブリソースのデータを一緒に検索することができます。

  サブリソースの検索  
 例) 商品を検索する際において「品目」と「在庫」のデータを一緒に検索する場合
GET https://{mallid}.cafe24api.com/api/v2/admin/products/570?embed=variants,inventories 

API Limit

アプリが1秒に2回ずつAPIを呼び出す場合は特に制限なくAPI呼び出しを使い続けることができます。
瞬間的に1秒以内に「呼び出し件数制限」以上のコールが発生する場合は、429エラー(Too Many Request)を返還します。
Bucket限度内の呼び出しであっても、該当のショップにて同一IPによる1秒あたり10回以上の呼び出しが発生した場合、異常な呼び出しとみなされることがあります。

Headerに「X-Api-Call-Limit」を確認すると429 エラーを避けることができます。ショップのAPI呼び出し件数とBucketの余裕分を確認することができます。

X-Api-Call-Limit : 1/40

Versioning

Version yyyy-mm-dd

以前のバージョンと互換性のない変更事項に対して、日付形式でバージョンを提供します。

アプリのバージョンは、以下の方法で確認及び変更することができます。

管理コンソールにログイン > Apps > アプリ管理 > 開発関連情報 > 認証情報のバージョン管理

バージョンの満了期間は、最新バージョンがリリースされた時点から最大１年となります。

該当のバージョンの満了後は、満了日の時点でリリース日が最も古いバージョンで動作します。

例示コード(要求)

REST API

D.Collection API

Introduction

D.Collection API

D.Collection APIは、Cafe24ショップの販売を促すことを目的とするマーケティング・広告サービスおよびその関連サービスの制作に携わっている、Cafe24の承認を得たパートナー会社にのみ提供されます。

当APIを通して取得した情報を事前に承認を得ていないチャンネル(またはメディア)または目的のために使用することはできません。

D.Collection APIは、Basic Auth基盤の認証システムと標準HTTP Request Method、リソースの予測ができるエンドポイントURL, HTTPコード基盤のエラーメッセージを提供します。

Request/Response Format

APIのリクエストおよびレスポンスはJSON Formatに対応しています。
個人情報などのセキュリティ保護のため、D.Collection APIはHTTPSプロトコルにのみ対応しています。
Dates属性は ISO_8601 フォーマットで提供されます。： YYYY-MM-DDTHH:MM:SS+09:00
決済通貨は、 ISO_4217 標準に準拠してリクエストされます。

要求例題(検索)

正常応答例題

{
  "resource": {
      "key": "value",
      "key": "value"
   }
}

エラー応答例題

{
  "error": {
      "code": "error code",
      "message": "error message",
      "more_info": {
      }
  }
}

Method

各リソースごとにReadに対応しており、標準HTTP MethodでAPIを使用することができます。

GET : 該当するリソースの情報を照会(Read)します。

D.Collection API Intro

D.Collection APIは、D.Collectionプログラムに参加しているショップの情報の照会に適しています。 D.Collection APIでは、該当のリソースに対するほぼ全ての情報を照会することができます。D.Collection APIを使用するには、Basic Auth方式による別途の認証が必要となります。

  使用例  
 ショップの照会 : https://dcollection-api.cafe24.com/api/shops
商品の照会 : https://dcollection-api.cafe24.com/api/products?dcollection_product_category={dcollection_product_category} 

API Status Code

Code	発生事例	エラーの解決方法
200	GETの成功時
401	1) APIが要求するAccess Tokenがない状態で呼び出しを行った場合 2) APIが要求するAccess Tokenが有効ではない場合 3) 認証をリクエストしたclient権限が有効でない場合	有効なAccess Tokenを使用したリクエストであるかどうかを確認します。
404	1) API URLの呼び出しに間違いがあった場合 2) リソースが見つからない場合	API Docsを参考にし、エンドポイントURLに間違いがないかを確認します。
422	照会・処理リクエストの際において、使用された値が仕様で決まっている値と異なる場合 1) 必須パラメーターの漏れがあった場合 2) パラメーターの値が無効な形式(タイプ)であった場合	API Docsを参考にし、必須パラメーターの入力漏れや無効な形式(タイプ)の値を使用したかどうかなどを確認します。
429	クライアントのAPIリクエスト数が上限(1分あたり最大40件)を超えた場合	APIリクエスト数が上限を超えないよう、しばらく時間をおいてから再度リクエストを行います。
500	内部サーバーエラー、不明なエラー	Cafe24 Developersまでお問い合わせください。
503	サーバーが過負荷でダウンした場合	Cafe24 Developersまでお問い合わせください。
504	リクエストの処理に時間がかかり、タイムアウトとなった場合	一時的なエラーが発生したため、処理に時間がかかっている状態です。しばらく時間をおいてから再度お試しください。

How to use GET API

cafe24のAPIはデータを検索する多様な方法を提供しています。

次はAPIの検索時に多様なパラメーターを使って多様な方法でデータを呼び出す方法を説明しています。

1. 検索条件の追加

検索を行う際、エンドポイントにパラメーターを追加すると検索条件を追加することができます。

複数の条件に一致する結果を見つけたい場合、「&」を使用して検索条件を追加することができます。

APIで対応している場合、タイムゾーンを使用して日付･時間の検索も可能です。

  検索条件の追加  
 例) 特定のショップ名に該当するショップの照会
GET https://dcollection-api.cafe24.com/api/shops?shop_name=nelly

例) 特定のショップ名および特定の属性に該当するショップの照会
GET https://dcollection-api.cafe24.com/api/shops?shop_name=nelly&shop_properties=hartebeest

例) 特定のカテゴリに該当する商品の照会
GET https://dcollection-api.cafe24.com/api/products?dcollection_product_category=C200802

例) 特定のカテゴリおよび特定のショップ名に該当する商品の照会
GET https://dcollection-api.cafe24.com/api/products?dcollection_product_category=C200802&shop_name=안다르 

2. カンマ(，)を使用した複数の値の検索

カンマ(，)で追加した検索条件はOR条件となり、条件を満たすすべての値が検索されます。

  カンマ(，)を使用した複数の値の検索  
 例) 特定のショップ名(複数指定可)に該当するショップの照会
GET https://dcollection-api.cafe24.com/api/shops?shop_name=nelly,reseda

例) 特定のカテゴリまたは特定の商品名(複数指定可)に該当する商品の照会
GET https://dcollection-api.cafe24.com/api/products?dcollection_product_category=C200802&product_name=안다르,에어쿨링 

3. Pagination

検索結果が多い場合、指定された「limit」のデフォルト値に基づいて結果が返されます。

「limit」パラメーターを利用して検索件数を増やすことが可能ですが、値が各APIに定義されている上限(最大値)を超えることはできません。

「limit」を利用する際の最大値ですべてのデータを検索できない場合、「offset」パラメーターで問題を解決することができます。

  Pagination  
 예) 100点店舗を検索する場合
GET https://dcollection-api.cafe24.com/api/shops?limit=100
 店舗
예) 100点の商品を検索する場合
GET https://dcollection-api.cafe24.com/api/products?dcollection_product_category=C200802&limit=100

예) 201番目から300番目までの店舗を検索する場合
GET https://dcollection-api.cafe24.com/api/shops?limit=100&offset=200

예) 201番目から300番目までの商品を検索する場合
GET https://dcollection-api.cafe24.com/api/products?dcollection_product_category=C200802&limit=100&offset=200 

API Limit

dcollection APIは、LaravelミドルウェアのThrottle機能を使用し、1つのIPでは1分あたり最大40件のリクエストのみ実行できるよう、呼び出し件数の制限を設けています。

呼び出し1回あたり1件の呼び出し可能件数が消費され、1分間で40回以上のリクエストがあった場合、429エラー(Too Many Request)が返されます。

429エラーが返されないようにするには、Headerで「X-RateLimit–Limit」と「X-RateLimit–Remaining」を確認してください。

X-Api-Call-Limit : 1/40

D.Collection API

Cafe24 Analytics API (Beta)

Introduction

Cafe24 Analytics API (Beta)

Cafe24 Analytics APIは、Cafe24ショップのユーザー行動データ提供によってデータ提供サービスを制作する、Cafe24の承認を得た協力会社にのみ提供されるAPIです｡

当APIを通して取得した情報を事前に承認を得ていないチャンネル(またはメディア)および目的のために使用することはできませんのでご注意ください。

2023年以前のデータはEC Admin > 統計 > アクセス統計のデータを基に提供され、2023年以降のデータはEC Admin > 統計 > Cafe24 アナリティクスのデータを基に提供されます。

Cafe24 Analytics APIは、OAuth 2.0基盤の認証システムと標準HTTP Request Method、リソースの予測が可能なエンドポイントURL、HTTPコード基盤のエラーメッセージを提供します。

Request/Response Format

APIのリクエストおよびレスポンスはJSON Formatに対応しています。
個人情報保護のため、Cafe24 Analytics APIはHTTPSプロトコルにのみ対応しています。
Dates属性は ISO_8601 フォーマットで提供されます。：YYYY-MM-DDTHH:MM:SS+09:00

要求例題(検索)

正常応答例題

{
  "resource": {
      "key": "value",
      "key": "value"
   }
}

エラー応答例題

{
  "error": {
      "code": "error code",
      "message": "error message",
      "more_info": {
      }
  }
}

Method

各リソースはReadに対応しており、標準HTTP MethodでAPIを使用することができます。

GET：該当するリソースの情報を照会(Read)します。

Cafe24 Analytics API Intro

Cafe24 Analytics APIはショップのユーザー行動データ照会に適したAPIです。 Cafe24 Analytics APIでは、該当のリソースに対するほぼ全ての情報を照会することができます。また、Cafe24 Analytics APIを使用するには、OAuth 2.0方式による別途の認証が必要となります。

  使用例  
 PV(ページビュー) : https://ca-api.cafe24data.com/visitors/pageview?mall_id=몰아이디&shop_no=1&start_date=2023-02-01&end_date=2023-02-10
アクセス数 : https://ca-api.cafe24data.com/visitors/view?mall_id=몰아이디&shop_no=1&start_date=2023-02-01&end_date=2023-02-10 

API Status Code

Code	発生事例	エラーの解決方法
200	GETに成功した場合
401	1) Access Tokenがない状況で呼び出しを行った場合 2) Access Tokenが有効ではない場合 Access Tokenが満了された場合 4) クライアントが把握できない場合(不明なクライアント)	有効なクライアントIDが使用されたかどうかを確認します。
403	Access Tokenはあるが、該当のScopeに対する権限がない場合	APIのScopeまたはショップの設定を確認し、APIの呼び出し権限があるかどうかを把握します。
403	httpsプロトコルではない場合	httpsプロトコルでAPIリクエストが行われたかどうかを確認します。
404	1) API URLを間違って呼び出した場合 2) リソースが見つからない場合 3) {#id}がない場合	APIドキュメントを参考に、エンドポイントURLに問題があるかどうかを確認します。
422	照会・処理リクエストを行う際の値が既定の仕様(スペック)と異なる場合 1) 必須パラメーターの漏れ 2) 既定の仕様(スペック)と異なる場合	APIドキュメントを参考に、必須パラメーターの入力漏れや無効な値の入力があるかどうかを確認します。
429	クライアントのAPIリクエストによってバケット(Bucket)のトークンがすべて消費された場合	APIリクエスト数が上限を超えないよう、しばらく時間をおいてから再度リクエストを行います。
500	内部サーバーエラーまたは不明なエラーが発生した場合	Cafe24 Developersまでお問い合わせください。
503	サーバーが過負荷でダウンした場合	Cafe24 Developersまでお問い合わせください。
503	サーバーが過負荷でダウンした場合/APIを使用できない場合	Cafe24 Developersまでお問い合わせください。
504	リクエストの処理に時間がかかり、タイムアウトとなった場合	一時的なエラーが発生した場合です。しばらく時間をおいてから再度試してください。

How to use GET API

Cafe24 Analytics APIは多様なデータ照会方法を提供しています。

API照会と関連し、各種パラメーターを使用してデータの呼び出しを行う様々な方法について説明いたします。

1. 検索条件の追加

検索を行う際に、エンドポイントにパラメーターを追加すると検索条件を追加することができます。

複数の条件に一致する結果を検索したい場合、「&」を使用して検索条件を追加することができます。

  検索条件の追加  
 例) 特定のショップにおいて、特定の期間中に発生したPV数を照会する場合
GET https://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01

例) 特定のショップにおいて、特定の期間中に発生したドメインごとのアクセス数を照会する場合
GET https://ca-api.cafe24data.com/visitpaths/domains?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01

例) 特定のショップにおいて、特定の期間中に発生した商品別の売上高・販売件数を照会する場合
GET https://ca-api.cafe24data.com/products/sales?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01

例) 特定のショップにおいて、特定の期間中に発生した時間帯別の購入者数・購入件数・売上高を照会する場合
GET https://ca-api.cafe24data.com/sales/times?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01 

2. Pagination

検索結果は基本的に100件まで照会できます。

照会された結果が多い場合は、「offset」パラメーターを利用して100件ずつ追加照会を行うことが可能です。

  Pagination  
 例) 100件のPVを照会する場合
GET https://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01

例) 101件目~200件目のPVを照会する場合
GET hhttps://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01&offset=100

例) 201件目~300件目のPVを照会する場合
GET hhttps://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01&offset=200

例) 301件目~400件目のPVを照会する場合
GET hhttps://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01&offset=300 

API Limit

CA APIでは「トークンバケット(Token Bucket)」アルゴリズムが使用されています。

「トークンバケット(Token Bucket)」とは、バケット(Bucket)に「リクエスト数上限」分のトークン(Token)を設定しておいて、リクエストが発生する度に1つのトークンが消費されるうようにし、バケットに使用可能なトークンが残っていない状態になるとリクエストを制限するアルゴリズムです。バケットのトークンは1秒に2個ずつ増加されます。

アプリが1秒に2回ずつのAPIリクエストを発生させる場合は、制限されることなく持続的に使用できます。一時的に1秒以内に「リクエスト数上限」を超える呼び出しが発生する場合は、429エラー(Too Many Request)が返されます。

HeaderのResponse Headerにて「x-ratelimit-remaining」でバケットに残っているトークンを確認し、429エラーを防止することが可能です。

CA APIのトークンバケット計算は、Admin APIで使用されるリーキーバケットアルゴリズムとは異なり、IPとURLを基準に計算されます。

 Response Header
> X-RateLimit-Remaining: 39
> X-RateLimit-Requested-Tokens: 1
> X-RateLimit-Burst-Capacity: 40
> X-RateLimit-Replenish-Rate: 2 

Authentication

アクセストークンは、ショッピングモール（EC Admin API）が発行するトークンとして使用できます。

Get Authentication Code

トークン発行リクエストの際に使用されたコードの再使用は不可であり、発行から1分が経過したコードは満了になります。

{mallid}：該当のショップIDを入力してください。
{client_id}：Cafe24 Developersで作成したアプリのclient_idを入力してください。
{state}：偽造・変造を防止するために入力する値であり、コードの返還時に同じ値が返されます。
{redirect_uri}：Cafe24 Developersで作成したアプリのRedirect URLを入力してください。
{scope}：このアクセストークンを利用してアクセスするリソースサーバーの権限を入力できます。

アクセストークンを発行するには、先にアクセスコードをリクエストする必要があります。アクセスコードは、クライアントがWebアプリケーションである場合に利用されます。コードのリクエストはcURLではなくWebブラウザで行ってください。

  要求例題(検索)  
 GET 'https://{mallid}.cafe24api.com/api/v2/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}&scope={scope}' 
  エラー応答例題  
 HTTP/1.1 302 Found
Location: {redirect_uri}?code={authorize_code}&state={state} 

Get Access Token

発行された認証コードを使用し、実際にAPIを呼び出しできるユーザートークン(Access Token、Refresh Token)を取得することができます。

{mallid}：該当のショップIDを入力してください。
{client_id}：Cafe24 Developersで作成したアプリのclient_idを入力してください。
{client_secret}：Cafe24 Developersで作成したアプリのclient_secretを入力してください。
{code}：発行されたコードを入力してください。
{redirect_uri}：Cafe24 Developersで作成したアプリのRedirect URLを入力してください。

access_token：アクセストークン。クライアントがリソースサーバーにアクセスする際に使用されます。

refresh_token：アクセストークンの満了後、再発行のために使用されるトークンです。

正常応答例題

エラー応答例題

HTTP/1.1 200 OK
{
    "access_token": "0iqR5nM5EJIq..........",
    "expires_at": "2021-03-01T14:00:00.000",
    "refresh_token": "JeTJ7XpnFC0P..........",
    "refresh_token_expires_at": "2021-03-15T12:00:00.000",
    "client_id": "BrIfqEKoPxeE..........",
    "mall_id": "yourmall",
    "user_id": "test",
    "scopes": [
        "mall.analytics",
        "...etc...",
    ],
    "issued_at": "2021-03-01T12:00:00.000"
}

Get Access Token using refresh token

アクセストークンは、発行から2時間が経過すると使用不可になります。アクセストークンが満了された場合、リソースサーバーにアクセスするには再発行が必要となります。その場合、すでにアクセストークンを発行した状態であれば、refresh_tokenを使用してアクセストークンの再発行を行うことが可能です。

refresh tokenの有効期限は2週間であり、refresh tokenが満了される前にリクエストを行うと、更新されたaccess tokenと更新されたrefresh tokenが一緒に返されます。更新されたrefresh tokenが返された後は、既存のrefresh tokenは満了になり、使用不可となります。

発行された認証コードを使用し、実際にAPIを呼び出しできるユーザートークン(Access Token、Refresh Token)を取得することができます。

{mallid}：該当のショップIDを入力してください。
{domain}：該当のショップのドメインを入力してください。
{client_id}：Cafe24 Developersで作成したアプリのclient_idを入力してください。
{client_secret}：Cafe24 Developersで作成したアプリのclient_secretを入力してください。
{refresh_token}：トークンの発行時に返されたrefresh_tokenを入力してください。

access_token：アクセストークン。クライアントがリソースサーバーにアクセスする際に使用されます。

refresh_token：アクセストークンの満了後、再発行のために使用されるトークンです。

例示コード(要求)

例示コード(応答)

HTTP/1.1 200 OK
{
    "access_token": "21EZes0dGSfN..........",
    "expires_at": "2021-03-01T15:50:00.000",
    "refresh_token": "xLlhWztQHBik............",
    "refresh_token_expires_at": "2021-03-15T13:50:00.000",
    "client_id": "BrIfqEKoPxeE..........",
    "mall_id": "yourmall",
    "user_id": "test",
    "scopes": [
        "mall.analytics",
        "...etc...",
    ],
    "issued_at": "2021-03-01T13:50:00.000"
}

Revoke Access Token

特定のアクセストークンを取り消すことができます。

アクセストークンが取り消された場合、要求されたアクセストークンのリフレッシュトークンも同時に取り消されます。

{mallid} : ショップのIDを入力します。
{domain}: ショップのドメインを入力します。
{client_id} : 開発者センターで作成したアプリのclient_idを入力します。
{client_secret}: 開発者センターで作成したアプリのclient_secretを入力します。
{token} : 取り消すアクセストークンを入力してください。

例示コード(要求)

例示コード(応答)

HTTP/1.1 200 OK