GET API 사용 가이드
카페24 API는 데이터를 조회하는 다양한 방법을 제공합니다. 이 가이드에서는 GET 요청 시 사용 가능한 7가지 파라미터 활용 방법을 설명합니다.
1️⃣ 검색조건 추가
검색조건은 엔드포인트에 파라미터를 추가하여 검색할 수 있습니다.
여러 조건을 함께 검색할 경우 & 구분자를 사용합니다.
예제
# 특정 브랜드에서 가격 1000원 이상 상품 조회
GET https://yourmall.cafe24api.com/api/v2/products?brand_code=B000000A&price_min=1000
# 날짜 범위로 상품 조회 (YYYY-MM-DD)
GET https://yourmall.cafe24api.com/api/v2/products?created_start_date=2024-01-03&created_end_date=2024-02-03
# 날짜+시간 범위로 조회 (ISO 8601)
GET https://yourmall.cafe24api.com/api/v2/products?updated_start_date=2024-01-03T14:01:26+09:00&updated_end_date=2024-02-03T14:01:26+09:00
코드 예제
// Node.js
const response = await axios.get('/api/v2/admin/products', {
params: {
brand_code: 'B000000A',
price_min: 1000,
price_max: 50000,
status: 'active'
}
});
# Python
params = {
'brand_code': 'B000000A',
'price_min': 1000,
'created_start_date': '2024-01-03'
}
response = requests.get(url, params=params)
2️⃣ 콤마로 여러 건 검색
콤마(,)를 사용하여 여러 값을 동시에 검색할 수 있습니다 (최대 100개).
콤마로 추가한 검색 조건은 OR 조건으로 동작합니다.
예제
# 특정 상품번호들 조회 (11 OR 12 OR 13)
GET https://yourmall.cafe24api.com/api/v2/products?product_no=11,12,13
# 여러 조건 조합
GET https://yourmall.cafe24api.com/api/v2/products?product_no=11,12,13&product_code=P000000X,P000000W
코드 예제
// Node.js
const productNos = [11, 12, 13];
const response = await axios.get('/api/v2/admin/products', {
params: {
product_no: productNos.join(',')
}
});
# Python
product_nos = [11, 12, 13]
params = {'product_no': ','.join(map(str, product_nos))}
response = requests.get(url, params=params)
⚠️ 주의: 최대 100개, OR 조건, 공백 없음
3️⃣ 멀티쇼핑몰 정보 조회
shop_no 파라미터로 특정 멀티쇼핑몰의 정보를 조회할 수 있습니다.
명시하지 않으면 기본(첫 번째) 쇼핑몰의 정보를 반환합니다.
예제
# 2번 쇼핑몰의 상품 조회
GET https://yourmall.cafe24api.com/api/v2/products?shop_no=2
# 기본 쇼핑몰 (shop_no 생략)
GET https://yourmall.cafe24api.com/api/v2/products
코드 예제
// Node.js - 모든 쇼핑몰 순회
async function getAllShopsProducts() {
const allProducts = [];
for (let shopNo = 1; shopNo <= 5; shopNo++) {
try {
const response = await axios.get('/api/v2/admin/products', {
params: { shop_no: shopNo }
});
allProducts.push({ shop_no: shopNo, products: response.data });
} catch (error) {
break; // 존재하지 않는 쇼핑몰
}
}
return allProducts;
}
4️⃣ 상세 조회와 단건 조회
리소스 ID를 명시하여 상세 조회가 가능합니다.
| 방식 | URL | 반환 데이터 |
|---|---|---|
| 상세 조회 | GET /products/128 | 많은 정보 |
| 단건 조회 | GET /products?product_no=128 | 기본 정보 |
예제
# 상세 조회 - 더 많은 정보 포함
GET https://yourmall.cafe24api.com/api/v2/admin/products/128
# 단건 조회 - 기본 정보만
GET https://yourmall.cafe24api.com/api/v2/admin/products?product_no=128
코드 예제
// Node.js
// 상세 조회
const detail = await axios.get(`/api/v2/admin/products/${productNo}`);
// 단건 조회
const info = await axios.get('/api/v2/admin/products', {
params: { product_no: productNo }
});
5️⃣ Pagination (페이지네이션)
limit과 offset 파라미터를 사용하여 페이지 단위로 조회합니다.
| 파라미터 | 설명 | 예시 |
|---|---|---|
limit | 한 번에 조회할 건수 | 100 |
offset | 건너뛸 건수 (0부터 시작) | 200 |
계산 공식
페이지 번호 = P (1부터 시작)
limit = L
offset = (P - 1) * L
예) 3페이지 조회 (limit=100)
offset = (3 - 1) * 100 = 200
예제
# 처음 100개
GET https://yourmall.cafe24api.com/api/v2/admin/products?limit=100
# 201~300번째 (3페이지)
GET https://yourmall.cafe24api.com/api/v2/admin/products?limit=100&offset=200
코드 예제
// Node.js - 모든 데이터 조회
async function getAllProducts() {
const allProducts = [];
let offset = 0;
const limit = 100;
while (true) {
const response = await axios.get('/api/v2/admin/products', {
params: { limit, offset }
});
const products = response.data.resource;
if (products.length === 0) break;
allProducts.push(...products);
offset += limit;
}
return allProducts;
}
# Python - 페이지 단위 조회
def get_products_page(page, limit=100):
offset = (page - 1) * limit
response = requests.get(url, params={'limit': limit, 'offset': offset})
return response.json()['resource']
6️⃣ 특정 항목 조회
fields 파라미터로 필요한 항목만 선택적으로 조회합니다.
예제
# 상품명과 상품번호만 조회
GET https://yourmall.cafe24api.com/api/v2/admin/products?fields=product_name,product_no
# 여러 항목 조회
GET https://yourmall.cafe24api.com/api/v2/admin/products?fields=product_no,product_name,price,inventory_qty
응답 예시
{
"resource": [
{
"product_no": 128,
"product_name": "Sample Product"
}
]
}
코드 예제
// Node.js
const fields = ['product_no', 'product_name', 'price'];
const response = await axios.get('/api/v2/admin/products', {
params: { fields: fields.join(',') }
});
장점
- 네트워크 절감
- 처리 속도 향상
- 메모리 효율
- 민감 데이터 필터링
7️⃣ 하위 리소스 조회
embed 파라미터로 관련 하위 리소스를 함께 조회합니다.
예제
# 상품 조회 시 품목과 재고 포함
GET https://yourmall.cafe24api.com/api/v2/admin/products/570?embed=variants,inventories
# 주문 조회 시 상품 정보 포함
GET https://yourmall.cafe24api.com/api/v2/admin/orders/123?embed=products,shipping
응답 예시
{
"resource": {
"product_no": 570,
"product_name": "Sample Product",
"variants": [
{"variant_no": 1, "option_name": "Color", "option_value": "Red"}
],
"inventories": [
{"warehouse_name": "Main", "quantity": 100}
]
}
}
코드 예제
// Node.js
const response = await axios.get(`/api/v2/admin/products/${productNo}`, {
params: { embed: 'variants,inventories,categories' }
});
const product = response.data.resource;
console.log('Variants:', product.variants);
console.log('Inventories:', product.inventories);
embed vs 별도 조회
| 항목 | embed 사용 | 별도 조회 |
|---|---|---|
| API 호출 | 1회 | N+1회 |
| 성능 | 빠름 | 느림 |
| 응답 크기 | 큼 | 작음 |
🎯 모범 사례
1. 조건 결합 최적화
# ✅ 좋은 예 - 한 번의 요청으로 필요한 데이터만
GET /products?status=active&fields=product_no,product_name,price&limit=100
# ❌ 나쁜 예 - 모든 데이터 조회 후 필터링
GET /products
2. 에러 처리
async function safeGetData(endpoint, params) {
try {
const response = await axios.get(endpoint, { params });
return response.data.resource;
} catch (error) {
if (error.response?.status === 404) {
return null; // 리소스 없음
} else if (error.response?.status === 422) {
console.error('잘못된 파라미터:', error.response.data);
}
throw error;
}
}
3. URL 인코딩
// ✅ 자동 인코딩 (권장)
const params = {
product_name: '상품명',
category: '카테고리'
};
axios.get(url, { params }); // axios가 자동 인코딩
// ❌ 수동 인코딩 (비권장)
const url = `/products?name=${encodeURIComponent('상품명')}`;
4. 성능 최적화
// ✅ 필요한 필드만 조회
const params = {
fields: 'product_no,product_name,price',
limit: 100
};
// ✅ embed로 N+1 문제 해결
const params = {
embed: 'variants,inventories',
fields: 'product_no,product_name,variants,inventories'
};
// ✅ 조건을 최대한 활용
const params = {
status: 'active',
price_min: 10000,
created_start_date: '2024-01-01',
limit: 50
};
📊 파라미터 조합 예제
복합 조회 예제
# 활성 상품 중 가격대별로 특정 필드만 페이지네이션 조회
GET /api/v2/admin/products?status=active&price_min=10000&price_max=50000&fields=product_no,product_name,price&limit=100&offset=0
// Node.js 복합 조회
const response = await axios.get('/api/v2/admin/products', {
params: {
status: 'active',
price_min: 10000,
price_max: 50000,
created_start_date: '2024-01-01',
fields: 'product_no,product_name,price,created_date',
limit: 100,
offset: 0,
shop_no: 1
},
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
}
});
⚠️ 주의사항
- URL 인코딩: 한글, 특수문자는 반드시 인코딩
- 날짜 형식: ISO 8601 형식 권장 (
YYYY-MM-DDTHH:MM:SS+09:00) - 콤마 제한: 최대 100개 항목
- offset 성능: 큰 offset은 성능 저하 가능
- API 문서 확인: 각 API마다 지원하는 파라미터가 다름
📚 관련 문서
💡 요약
| 기능 | 파라미터 | 예시 |
|---|---|---|
| 검색조건 | param=value | status=active |
| 여러 값 검색 | param=v1,v2,v3 | product_no=11,12,13 |
| 멀티쇼핑몰 | shop_no=N | shop_no=2 |
| 상세 조회 | /resource/{id} | /products/128 |
| 페이지네이션 | limit=N&offset=M | limit=100&offset=200 |
| 특정 항목 | fields=f1,f2 | fields=product_no,name |
| 하위 리소스 | embed=r1,r2 | embed=variants,inventories |