닫기

  • Admin API

  • Front API

  • D.Collection API (Beta)

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

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

    • img
      Admin API

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

      詳細を見る

    • img
      Front API

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

      詳細を見る

    • img
      D.Collection API (Beta)

      D.Collectionプログラムに参加しているショップのショップ情報および商品情報を照会し、対象ショップの販売を促すことを目的とするサービスを制作する際に使用できる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": "エラーコード",
        "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はショップの管理者によるショップ情報の検索、生成、修正、削除に適合しています。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文書を参考に確認します。
    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"
}

    REST API

    Front API

    Introduction

    Cafe24 API

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

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

    Front API Intro

    Front API

    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": "エラーコード",
      "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文書を参考に確認します。
    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 > アプリ管理 > 開発関連情報 > 認証情報のバージョン管理

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

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

    例示コード(要求)

    REST API

    D.Collection API (Beta)

    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": "エラーコード",
      "message": "エラーメッセージ",
      "more_info": {
      }
  }
}

    Method

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

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

    D.Collection API Intro

    D.Collection API

    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. カンマ(，)を使用した複数の値の検索

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

    カンマ(，)で追加した検索条件は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

    Authentication

    Authentication

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

    認証が正常に行われたら、D.Collection APIデータをすぐに使用できます。

    • {client_id}: 開発者センターで作成したアプリのclient_idを入力します。

    • {client_secret}: 開発者センターで作成したアプリのclient_secretを入力します。

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

    例示コード(要求)
    例示コード(応答) 
    {
  "resource": {
      "key": "value",
      "key": "value"
   }
}

    D.Collection API

    Top