- Home
- API 가이드
- API 기본가이드
API 기본가이드
카페24 API는 쇼핑몰 플랫폼을 기반으로 구성되며, RESTful 방식으로 쉽고 편리하게 사용할 수 있도록 제공됩니다.
본 가이드에서는 API를 이용하기 위해 기본적으로 알아야 할 내용을 안내하고 있습니다.
카페24 API 개요
카페24 플랫폼 API는 카페24 쇼핑몰 플랫폼에 연동하여 서비스를 제공하기 위한 App Store 입점 개발사, 서드파티 솔루션 제공자 등에 제공하는 API입니다.
카페24 API는 RESTful 한 아키텍처로서 Oauth V2 기반의 인증 시스템과 표준 HTTP Request Method, 리소스를 예측할 수 있는 엔드 포인트 URL, HTTP 코드 기반의 에러 메시지를 제공합니다.
| 용어 | 설명 |
|---|---|
| API | 애플리케이션 프로그래밍 인터페이스(Application Programming Interface)의 약자로 카페24 쇼핑몰 플랫폼과 애플리케이션, 서비스, 라이브러리 등과 표준화된 규약으로 상호간의 통신을 할 수 있는 인터페이스를 의미합니다. RESTful 방식으로 제공되며 정해진 규약(인터페이스, 파라미터 등)을 통해 통신이 이루어집니다. Admin API 와 Front API로 구분되어 있으며, Front API는 인증을 받지 않아도 호출이 가능한 API로 구성되어 있습니다. |
| Entity | 카페24 쇼핑몰 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 간의 관계를 표현한 것으로, 조금 더 Semantic한 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 헤더에는 웹 서버로 보내는 요청을 설명하는 메타 정보가 포함됩니다. API 요청 시 HTTP 헤더에는 접근 토큰을 포함하여 요청해야 합니다.(Admin API 호출시에만 해당) 응답시 HTTP 헤더에는 API 요청 수 제한 값을 비롯한 다양한 메타 정보가 반환됩니다. |
요청(Request) / 응답(Response) 형식
카페24 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": {
}
}
} 개인정보 보호를 위하여 카페24 API는 HTTPS 프로토콜만 지원합니다.
Dates 속성은 ISO_8601 Format으로 제공합니다. : YYYY-MM-DDTHH:MM:SS+09:00
Method 형식
카페24각 리소스 별로 Create, Read, Update, Delete를 지원하며 표준 HTTP Method를 사용하여 API를 사용할 수 있습니다.
| 구분 | 설명 |
|---|---|
| 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의 정보를 대부분 조회할 수 있으며 Oauth 2.0 방식의 인증을 통과한 경우만 사용할 수 있습니다.
사용 예제
https://{{mallid}}.cafe24api.com/api/v2/admin/sampleapi
API 조회 사용방법
카페24 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/570?embed=variants,inventories
API 요청 수 제한 정책
카페24 API는 "Leaky Bucket" 알고리즘으로 작동합니다. Leaky Bucket 알고리즘은 성능을 위해 비정상적으로 많은 API 요청만 제한되고 일상적인 API 요청은 별다른 제약 없이 사용할 수 있는 효과가 있습니다.
카페24 API는 API 요청을 Bucket에 쌓아둡니다. Bucket은 쇼핑몰 당 최대 10회가 가득차면 API 호출이 제한됩니다.
Bucket은 1초에 1회씩 감소하며, 감소한만큼 다시 API 호출을
할 수 있습니다.
- 만약 앱이 1초에 1회씩 API를 호출한다면 API 호출을 별다른 제약 없이 계속 사용할 수 있습니다.
- 순간적으로 1초 이내에 30회 이상의 콜이 발생한다면 429 에러(Too Many Request)를 반환합니다.
Header에 X-Api-Call-Limit을 확인하면 429 에러를 피할 수 있습니다.
해당 쇼핑몰에서 얼마나 API를 호출했는지, 그리고 Bucket 여유량은 얼마나 남았는지를 확인할 수 있습니다.
예제) Header에 X-Api-Call-Limit을 확인
X-Api-Call-Limit : 1/30 해당 값은 시간이 지날 수록 감소합니다. 만약 해당 값이 "9/30"이라면 3초를 기다리면 "6/10"으로 감소합니다.