Basic API Guide

Home > API 가이드 > API 기본가이드

API 기본가이드

카페24 API는 쇼핑몰 플랫폼을 기반으로 구성되며, RESTful 방식으로 쉽고 편리하게 사용할 수 있도록 제공됩니다.

본 가이드에서는 API를 이용하기 위해 기본적으로 알아야 할 내용을 안내하고 있습니다.

■ 카페24 API 개요

■ Front API와 Admin API

■ Method 형식

■ 카페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를

의미합니다.

하위 Entity는 그 자체로는 조회하거나 등록/수정할 수 없고 항상 URL에 상위 Entity를 포함하여

사용해야 합니다.

하위 Entity는 상위 Entity에 속해있기 때문에 상위 Entity가 생성될 경우 하위 Entity도 같이 생성되고

상위 Entity가 삭제될 경우 하위 Entity도 삭제됩니다.

관계형 Entity

관계형 Entity는 의미적으로 관계가 있는 Entity 간의 관계를 표현한 것으로, 조금 더 Semantic한 API

사용을 위하여 만든 Entity 입니다. 관계형 Entity는 특정 Entity에 속해있지 않지만 의미적으로 "~~~에

속한 Entity (회원의 장바구니, 상품의 좋아요)"로 표현할 수 있습니다. 관계형 Entity는 하위 Entity와 달리 Entity에 속해있지 않고 대등한 관계로 이루어져 있습니다.

관계형 Entity는 종속된 관계는 아니기 때문에 관계 있는 Entity의 생성, 수정, 삭제, 조회 등에 영향을

받지 않습니다.

엔드포인트

API를 호출할 수 있는 Method와 URL을 의미합니다. 엔드포인트의 Method(POST, GET, PUT, DELETE)는 해당 API의 동작을 정의하며, 엔드포인트의 URL은 해당 API의 동작을 인지적으로

나타냅니다.

요청 파라미터

요청 파라미터는 API를 호출할 때 함께 전송해야하는 값을 의미합니다. 검색 조건을 추가하거나 등록/

수정시 해당 Entity의 속성을 정의할 수 있습니다.

HTTP 헤더

HTTP 헤더에는 웹 서버로 보내는 요청을 설명하는 메타 정보가 포함됩니다. API 요청시 HTTP 헤더에는

접근 토큰을 포함하여 요청해야 합니다.(Admin API 호출시에만 해당) 응답시 HTTP 헤더에는 API 요청수

제한 값을 비롯한 다양한 메타 정보가 반환됩니다.

- 사용 예시

- 잘못된 예시

GET https://{{mallid}}.cafe24api.com/api/v2/options

- 올바른 예시

GET https://{{mallid}}.cafe24api.com/api/v2/products/{#id}/options

- 사용 예시

- 올바른 예시

GET https://{{mallid}}.cafe24api.com/api/v2/admin/wishes/{#id}

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products/{#id}/wishes

- 사용 예시 : 상품(Products) Entity를 등록할 경우

POST {mallid.cafe24.com}/api/v2/admin/products

1. Front API

Front API는 공개된 정보(상품 진열 정보) 또는 쇼핑몰 고객이 자신의 정보를 조회하거나 게시물 등을 작성할 때 적합합니다.

Front API는 Admin API에 비하여 일부 정보는 제한되어있습니다.

■ Front API와 Admin API

각 엔드포인트(End Point)에 따라 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

■ 요청(Request)/응답(Response) 형식

■ API 조회 사용 방법

■ 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 형식

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

구분

설명

POST

해당 Entity를 생성(Create)합니다.

GET

해당 Entity의 정보를 조회(Read)합니다.

PUT

해당 Entity를 수정(Update)합니다.

DELETE

해당 Entity를 삭제(Delete)합니다.

■ API 조회 사용방법

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

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

1. 검색조건을 추가하기

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

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

- 예제) 특정 브랜드 내에서 가격이 1000원 이상인 상품을 검색하고 싶을 경우

GET https://{{mallid}}.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000

시작일, 종료일 등 범위를 검색할 경우에도 "&" 구분자를 사용하여 검색할 수 있습니다.

- 예제) 특정 브랜드 내에서 가격이 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

시작일, 종료일 등 범위를 검색할 경우에도 "&" 구분자를 사용하여 검색할 수 있습니다.

- 예제) 특정 브랜드 내에서 가격이 1000원 이상인 상품을 검색하고 싶을 경우

GET https://{{mallid}}.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000

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

- 예제) 201번째 상품부터 300번째 상품까지 조회하기

GET https://{{mallid}}.cafe24api.com/api/v2/admin/products?limit=100&offset=201

'limit' 파라미터로 확장할 수 있는 조회건수는 각 API마다 정의된 '최대값'만큼만 확장할 수 있습니다.

만약 'limit 최대값'으로 모든 데이터를 조회할 수 없는 경우 'offset' 파라미터를 사용할 수 있습니다.

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?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초 이내에 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"으로 감소합니다.

출력하기

API 기본 가이드

API 상세 사양 (Front)

서버가 필요하신가요?

상태코드 및 오류메시지

실시간 API 제공목록 및 상태

API 상세 사양 (Admin)

API Support Tool 안내