아래 서비스별 링크를 눌러 API 사용 가이드를 확인하세요.

앱스토어 입점 개발사에서 카페24의 서비스와 데이터를 쉽게 활용할 수 있는 오픈 API입니다.

Admin API
쇼핑몰 전반의 상품,주문,회원,게시판 등의 정보를 조회하거나 생성,수정,삭제 기능 이용 시 사용할 수 있습니다.

바로가기
Front API
쇼핑몰에 등록된 상품의 정보를 조회하거나 장바구니 담기 기능을 이용 시 사용할 수 있습니다.

바로가기
D.Collection API
D.Collection 프로그램 참여 쇼핑몰의 상점 정보와 상품 정보를 조회하여 대상 쇼핑몰의 판매 촉진을 유도하기 위한 목적의 서비스 제작 시 사용할 수 있습니다.

바로가기
Cafe24 Analytics API (Beta)
쇼핑몰의 사용자 행동 데이터를 제공하기 위한 목적의 서비스 제작 시 사용할 수 있습니다.

바로가기

non-print

Admin API

Introduction

Cafe24 API

카페24 쇼핑몰 API는 카페24 쇼핑몰에 연동하여 서비스를 제공하기 위한 앱스토어 입점 개발사, 서드파티 솔루션 제공자 등에 제공하는 API입니다.

카페24 API는 RESTful한 아키텍쳐로서 OAuth 2.0 기반의 인증 시스템과 표준 HTTP Request Method, 리소스를 예측할 수 있는 엔드포인트 URL, HTTP 코드 기반의 에러 메시지를 제공합니다.

API Diagram

리소스 관계를 다이어그램으로 제공하여, 전체적인 카페24 API 체계를 확인할 수 있습니다.

Request/Response Format

API 요청과 응답은 JSON Format을 지원합니다.
개인정보 보호를 위하여 카페24 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는 해당 리소스의 정보를 대부분 조회할 수 있으며 OAuth 2.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) Front API에서 볼 수 있는 권한이 없을 경우	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

카페24 API는 데이터를 조회하는 여러가지 방법을 제공하고 있습니다.

다음은 API 조회시 여러가지 파라메터를 사용하여 다양하게 데이터를 호출할 수 있는 방법을 설명하고 있습니다.

1. 검색조건 추가

검색조건은 엔드포인트에 파라메터를 추가하여 검색할 수 있습니다.

여러 조건을 같이 검색할 경우 "&" 구분자를 이용하여 검색 조건을 추가할 수 있습니다.

API에서 지원하는 경우, 타임존을 사용하여 날짜와 시간 검색을 할 수 있습니다.

  검색조건 추가  
 예) 특정 브랜드 내에서 상품 판매가가 1000원 이상인 상품 조회
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. 멀티쇼핑몰 정보 조회

특정 멀티쇼핑몰 번호를 명시하면 해당 멀티쇼핑몰의 정보를 조회할 수 있습니다.

멀티쇼핑몰 번호를 명시하지 않을 경우, 기본 쇼핑몰의 정보를 조회합니다.

  멀티쇼핑몰 정보 조회  
 예) 특정 멀티쇼핑몰의 상품 조회
GET https://{mallid}.cafe24api.com/api/v2/products?shop_no=2 

4. 상세 조회와 단건 조회

리소스의 ID를 명시하여 상세 조회를 할 수 있습니다.

상세 조회는 리소스 하나만 조회할 수 있지만, 목록 조회보다 더 많은 항목이 반환됩니다.

  상세 조회와 단건 조회  
 예) 특정 상품번호를 지정하여 상품 상세 조회
GET https://{mallid}.cafe24api.com/api/v2/admin/products/128


예) 특정 상품번호를 지정하여 상품 단건 조회
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

카페24 API는 "Leaky Bucket" 알고리즘으로 작동합니다. Leaky Bucket 알고리즘은 성능을 위해 비정상적으로 많은 API 요청만 제한되고 일상적인 API 요청은 별다른 제약 없이 사용할 수 있는 효과가 있습니다.

카페24 API는 API 요청을 Bucket에 쌓아둡니다. Bucket은 쇼핑몰 당 "호출건 수 제한"만큼 가득차면 API 호출이 제한됩니다. Bucket은 1초에 2회씩 감소하며, 감소한만큼 다시 API 호출을 할 수 있습니다.

만약 앱이 1초에 2회씩 API를 호출한다면 API 호출을 별다른 제약 없이 계속 사용할 수 있습니다.
순간적으로 1초 이내에 "호출건 수 제한" 이상의 콜이 발생한다면 429 에러(Too Many Request)를 반환합니다.
Bucket 이내의 호출이라도 해당 쇼핑몰에서 동일 IP로 초당 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"를 통해 원하시는 버전을 지정할 수 있으며 버전을 지정하지 않을경우 개발정보의 앱 버전으로 동작합니다.

앱 버전은 아래 경로를 통해 확인 및 변경이 가능합니다.

개발자센터(로그인) > Apps > 개발정보 > 인증정보 내 버전관리

버전의 만료 기간은 최신 버전 릴리즈가 출시된 시점부터 최대 1년입니다.

해당 버전이 만료된 이후에는 만료되지 않은 버전 중 가장 오래된 버전으로 동작합니다.

예시 코드 (요청)

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

Access Token을 사용하여 직접 토큰을 폐기할 수 있습니다.

요청한 토큰에 해당하는 리프레시 토큰도 함께 폐기됩니다.

{mallid} : 해당 쇼핑몰ID를 입력합니다.
{client_id} : 개발자 센터에서 생성한 앱의 client_id를 입력합니다.
{client_secret} : 개발자 센터에서 생성한 앱의 client_secret을 입력합니다.
{token} : 토큰 발급시 받은 access_token을 입력합니다.

예시 코드 (요청)

예시 코드 (응답)

HTTP/1.1 200 OK

REST API

Front API

Introduction

Cafe24 API

카페24 쇼핑몰 API는 카페24 쇼핑몰에 연동하여 서비스를 제공하기 위한 앱스토어 입점 개발사, 서드파티 솔루션 제공자 등에 제공하는 API입니다.

Front API Intro

Front API는 공개된 정보(상품 진열 정보) 또는 쇼핑몰 이용 고객이 자신의 정보를 조회하거나 게시물 등을 작성할 때 적합합니다. Front API는 Admin API에 비하여 일부 정보는 제한되어있습니다.

  사용 예시  
 https://{mallid}.cafe24api.com/api/v2/sampleapi 

API Diagram

리소스 관계를 다이어그램으로 제공하여, 전체적인 카페24 API 체계를 확인할 수 있습니다.

Request/Response Format

API 요청과 응답은 JSON Format을 지원합니다.
개인정보 보호를 위하여 카페24 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) Front API에서 볼 수 있는 권한이 없을 경우	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

카페24 API는 데이터를 조회하는 여러가지 방법을 제공하고 있습니다.

다음은 API 조회시 여러가지 파라메터를 사용하여 다양하게 데이터를 호출할 수 있는 방법을 설명하고 있습니다.

1. 검색조건 추가

검색조건은 엔드포인트에 파라메터를 추가하여 검색할 수 있습니다.

여러 조건을 같이 검색할 경우 "&" 구분자를 이용하여 검색 조건을 추가할 수 있습니다.

API에서 지원하는 경우, 타임존을 사용하여 날짜와 시간 검색을 할 수 있습니다.

  검색조건 추가  
 예) 특정 브랜드 내에서 상품 판매가가 1000원 이상인 상품 조회
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. 멀티쇼핑몰 정보 조회

특정 멀티쇼핑몰 번호를 명시하면 해당 멀티쇼핑몰의 정보를 조회할 수 있습니다.

멀티쇼핑몰 번호를 명시하지 않을 경우, 기본 쇼핑몰의 정보를 조회합니다.

  멀티쇼핑몰 정보 조회  
 예) 특정 멀티쇼핑몰의 상품 조회
GET https://{mallid}.cafe24api.com/api/v2/products?shop_no=2 

4. 상세 조회와 단건 조회

리소스의 ID를 명시하여 상세 조회를 할 수 있습니다.

상세 조회는 리소스 하나만 조회할 수 있지만, 목록 조회보다 더 많은 항목이 반환됩니다.

  상세 조회와 단건 조회  
 예) 특정 상품번호를 지정하여 상품 상세 조회
GET https://{mallid}.cafe24api.com/api/v2/admin/products/128


예) 특정 상품번호를 지정하여 상품 단건 조회
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로 초당 10회 이상의 호출이 발생할 경우 비정상적인 호출로 판단될 수 있습니다.

X-Api-Call-Limit : 1/40

Versioning

Version yyyy-mm-dd

이전 버전과 호환되지 않은 변경사항에 대해 날짜로 버전을 제공합니다.

custom headers "X-Cafe24-Api-Version"를 통해 원하시는 버전을 지정할 수 있으며 버전을 지정하지 않을경우 개발정보의 앱 버전으로 동작합니다.

앱 버전은 아래 경로를 통해 확인 및 변경이 가능합니다.

개발자센터(로그인) > Apps > 개발정보 > 인증정보 내 버전관리

버전의 만료 기간은 최신 버전 릴리즈가 출시된 시점부터 최대 1년입니다.

해당 버전이 만료된 이후에는 만료되지 않은 버전 중 가장 오래된 버전으로 동작합니다.

예시 코드 (요청)

REST API

D.Collection API

Introduction

D.Collection API

D.Collection API는 카페24 쇼핑몰의 판매 촉진을 유도하기 위한 마케팅/광고 서비스 및 이에 수반되는 제반 서비스를 제작하는 카페24의 승인을 받은 제휴사에 제공되는 API입니다.

본 API를 통해 취득한 정보는 사전 승인되지 않은 채널(또는 미디어) 및 목적을 위해 사용할 수 없습니다.

D.Collection API는 Basic Auth 기반의 인증 시스템과 표준 HTTP Request Method, 리소스를 예측할 수 있는 엔드포인트 URL, HTTP 코드 기반의 에러 메시지를 제공합니다.

Request/Response Format

API 요청과 응답은 JSON Format을 지원합니다.
개인정보 보호를 위하여 D.Collection API는 HTTPS 프로토콜만 지원합니다.
Dates 속성은 ISO_8601 Format으로 제공합니다. : 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는 해당 리소스의 정보를 대부분 조회할 수 있으며 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) Access Token 없이 호출한 경우 2) API에서 요구한 Access Token 가 유효하지 않은 경우 3) 인증을 요청한 client 권한이 유효하지 않은 경우	유효한 Access Token를 사용하여 요청하였는지 확인합니다
404	1) API URL을 잘못 호출한 경우 2) 리소스를 찾을 수 없을 경우	엔드포인트 URL의 오류가 있는지 API문서를 참고하여 확인합니다.
422	조회/처리 요청시 값이 정해진 스펙과 다를 경우 1) 필수 파라메터 누락함 2) 파라미터에 유효한 타입의 값을 넣지 않을 경우	API문서를 참고하여 필수 파라미터가 입력되지 않았거나 유효하지 않은 타입의 값을 입력하지 않았는지 확인합니다.
429	클라이언트의 API 요청이 최대 허용 요청 건수(1분에 최대 40회)를 넘은 경우	API 최대 허용 요청 건수를 초과하지 않도록 잠시 후 다시 요청합니다.
500	내부 서버 에러, 알 수 없는 에러	개발자센터로 문의해주세요.
503	현재 서버가 다운된 경우	개발자센터로 문의해주세요.
504	요청 시간이 초과된 경우(Timeout)	일시적으로 에러가 발생하여 응답이 지연되고 있습니다. 잠시 후에 다시 시도해주세요.

How to use GET API

D.Collection 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

D.Collection API는 라라벨 쓰로틀 미들웨어를 사용하여 IP당 1분에 최대 40회까지 요청 가능하도록 호출건 수를 제한하고 있습니다.

한번 호출 시 1회씩 감소하며, 1분 동안 40회 이상의 콜이 발생하면 429에러(Too Many Request)를 반환합니다.

Header에 X-Api-Call-Limit을 확인하면 429에러를 피할 수 있습니다. API 호출 횟수와 1분당 최대 호출 가능 횟수를 각각 확인할 수 있습니다.

X-Api-Call-Limit : 1/40

D.Collection API

Cafe24 Analytics API (Beta)

Introduction

Cafe24 Analytics API (Beta)

Cafe24 Analytics API는 카페24 쇼핑몰의 사용자 행동 데이터를 제공하여 데이터 제공 서비스를 제작하는 카페24의 승인을 받은 제휴사에 제공되는 API입니다.

본 API를 통해 취득한 정보는 사전 승인되지 않은 채널(또는 미디어) 및 목적을 위해 사용할 수 없습니다.

2023년 이전 데이터는 EC Admin > 통계 > 접속통계의 데이터를 기반으로 제공되고, 2023년 이후 데이터는 EC Admin > 통계 > 카페24 애널리틱스의 데이터를 기반으로 제공됩니다.

Cafe24 Analytics API는 OAuth 2.0 기반의 인증 시스템과 표준 HTTP Request Method, 리소스를 예측할 수 있는 엔드포인트 URL, HTTP 코드 기반의 에러 메시지를 제공합니다.

Request/Response Format

API 요청과 응답은 JSON Format을 지원합니다.
개인정보 보호를 위하여 Cafe24 Analytics 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

각 리소스 별로 Read를 지원하며 표준 HTTP Method를 사용하여 API를 사용할 수 있습니다.

GET : 해당 리소스의 정보를 조회(Read)합니다.

Cafe24 Analytics API Intro

Cafe24 Analytics API는 쇼핑몰의 사용자 행동 데이터를 조회하는데 적합합니다. Cafe24 Analytics API는 해당 리소스의 정보를 대부분 조회할 수 있으며 OAuth 2.0 방식의 별도 인증을 통과한 경우에만 사용할 수 있습니다.

  사용 예시  
 페이지뷰 : 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이 유효하지 않은 경우 3) Access Token이 만료된 경우 4) 알 수 없는 클라이언트일 경우	유효한 클라이언트 ID를 사용하였는지 확인합니다.
401	API 사용시 client_id를 미입력한 경우	유효한 클라이언트 ID를 사용하였는지 확인합니다.
403	Access Token은 있으나 해당 Scope에 권한이 없음	API를 호출할 수 있는 권한이 있는지 API의 Scope 또는 쇼핑몰의 설정을 확인합니다.
403	https 프로토콜이 아닌 경우	API 요청시 https 로 요청하였는지 확인합니다.
404	1) API URL을 잘못 호출한 경우 2) 리소스를 찾을 수 없을 경우 3) {#id}가 없는 경우	엔드포인트 URL의 오류가 있는지 API문서를 참고하여 확인합니다.
422	조회/처리 요청시 값이 정해진 스펙과 다를 경우 1) 필수 파라메터 누락함 2) 정해진 스펙과 다를 경우	API문서를 참고하여 필수 파라미터가 입력되지 않았거나 유효하지 않은 타입의 값을 입력하지 않았는지 확인합니다.
429	클라이언트의 API 요청이 Bucket에 Token 을 모두 소모한 경우	API 최대 허용 요청 건수를 초과하지 않도록 잠시 후 다시 요청합니다.
500	내부 서버 에러, 알 수 없는 에러	개발자센터로 문의해주세요.
503	현재 서버가 다운된 경우	개발자센터로 문의해주세요.
503	서버가 다운된 경우. API를 사용할 수 없음.	개발자센터로 문의해주세요.
504	요청 시간이 초과된 경우(Timeout)	일시적으로 에러가 발생하여 응답이 지연되고 있습니다. 잠시 후에 다시 시도해주세요.

How to use GET API

Cafe24 Analytics API는 데이터를 조회하는 여러가지 방법을 제공하고 있습니다.

다음은 API 조회시 여러가지 파라메터를 사용하여 다양하게 데이터를 호출할 수 있는 방법을 설명하고 있습니다.

1. 검색조건 추가

검색조건은 엔드포인트에 파라메터를 추가하여 검색할 수 있습니다.

여러 조건을 같이 검색할 경우 "&" 구분자를 이용하여 검색 조건을 추가할 수 있습니다.

  검색조건 추가  
 예) 특정 상점의 특정 기간 동안의 페이지 뷰 조회
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건 조회
GET https://ca-api.cafe24data.com/visitors/pageview?mall_id=nelly&start_date=2023-01-01&end_date=2023-02-01

예) 101번째부터 200번째까지의 페이지뷰 조회
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번째까지의 페이지뷰 조회
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번째까지의 페이지뷰 조회
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

Cafe24 Analytics API 에서 사용되는 알고리즘은 "Token Bucket" 입니다.

Token Bucket 알고리즘은 Bucket 안에 "호출건 수 제한" 만큼 Token 담아두고, 요청이 들어올 때 1 씩 Token 수를 감소하여 Bucket 에 더 이상 사용할 Token 이 없을 때 요청을 제한합니다. Bucket 안에 Token은 1초에 2씩 다시 증가합니다.

만약 앱이 1초에 2회씩 API 를 요청한다면 API 요청은 별다른 제약 없이 계속 사용할 수 있습니다. 순간적으로 1초 이내에 "호출건 수 제한" 이상의 콜이 발생한다면 429 에러(Too Many Request)를 반환합니다. Header에 Response Header 에 "x-ratelimit-remaining" 으로 Bucket 에 Token이 얼마나 남았는지 확인하여 429 에러를 피할 수 있습니다.

Cafe24 Analytics 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

접근 토큰(access_token)은 쇼핑몰(EC Admin API)에서 발급되는 토큰으로 사용하실 수 있습니다.

Get Authentication Code

토큰발급 요청시 사용된 code는 재사용할 수 없으며 코드 발급 후 1분이 경과하면 만료됩니다.

{mallid} : 해당 쇼핑몰ID를 입력합니다.
{client_id} : 개발자 센터에서 생성한 앱의 client_id를 입력합니다.
{state} : 위변조 방지를 위해 입력하는 값으로 코드 반환시 같은 값이 반환됩니다.
{redirect_uri} : 개발자 센터에서 생성한 앱의 Redirect URL을 입력합니다.
{scope} : 해당 접근 토큰으로 접근할 리소스 서버의 권한을 입력할 수 있습니다.

  예시 코드 (요청)  
 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.analytics",
        "...etc...",
    ],
    "issued_at": "2021-03-01T12:00:00.000"
}

Get Access Token using 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.analytics",
        "...etc...",
    ],
    "issued_at": "2021-03-01T13:50:00.000"
}

Revoke Access Token

Access Token을 사용하여 직접 토큰을 폐기할 수 있습니다.

요청한 토큰에 해당하는 리프레시 토큰도 함께 폐기됩니다.

{mallid} : 해당 쇼핑몰ID를 입력합니다.
{client_id} : 개발자 센터에서 생성한 앱의 client_id를 입력합니다.
{client_secret} : 개발자 센터에서 생성한 앱의 client_secret을 입력합니다.
{token} : 토큰 발급시 받은 access_token을 입력합니다.

예시 코드 (요청)

예시 코드 (응답)

HTTP/1.1 200 OK