상품 카테고리
관리자 권한으로 상품 카테고리 트리(최대 4단계)를 만들고 고치고 옮기고 지웁니다.
업데이트됨 10.13 — 이미지 칸은 어디서 저장하든 파일 키만 믿습니다무엇인가요
쇼핑몰 소유자를 대신하는 토큰으로 상품 카테고리 트리를 다룹니다. 쇼핑몰 관리자 > 상품 > 상품 카테고리와 같은 규칙입니다.
- 트리를 한 줄 목록으로 줍니다 —
parent_id·depth·sort_order로 세웁니다. 최대 4단계, 대분류는 15개까지입니다. is_all: true는 '전체' 카테고리(slugall)입니다. 지우거나 하위를 두거나 상품에 걸 수 없습니다.- 생성 · 수정 · 옮기기 · 삭제는 모두 바뀐 뒤의 전체 목록을 돌려줍니다. 아래 예시는 길어서 관계있는 줄만 남겼습니다.
목록
GET
https://api.mallstory.kr/v1/shop/{shop_unique}/categories권한 products:read
bash요청
curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/categories' \
-H 'Authorization: Bearer msat_8Hk2wQ7...'json200 OK
{
"items": [
{
"name": "전체 카테고리",
"displayed": true,
"access_permission": "GUEST",
"access_level": 0,
"list_type": "CARD",
"list_sort": "DISPLAY",
"top": {
"text": {
"enabled": true,
"title": "zz",
"description": "cccc",
"text_color": "#FFFFFF",
"background_color": "#06B6D4",
"size": "XLARGE",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": true,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6aab71c3dd8941ed187ffe56",
"parent_id": null,
"depth": 0,
"sort_order": 0,
"slug": "all",
"is_all": true,
"full_name": "전체 카테고리"
}
]
}응답은 {items} 입니다. 예시는 전체 카테고리 한 줄만 남겼습니다.
응답 필드
| 필드 | 형식 | 설명 |
|---|---|---|
category_unique | string | 카테고리 키. 상품의 category_id 에 넣는 값 |
name | string | 카테고리 이름 |
full_name | string | 상위까지 이은 이름(예: 봄 신상 > 셔츠) |
slug | string | 쇼핑몰 주소 조각(/category/{slug}). 쇼핑몰 조회 API 도 이 값을 씁니다 |
parent_id | string | null | 상위 카테고리 키. 대분류는 null |
depth | number | 단계 — 0 대분류 · 1 중분류 · 2 소분류 · 3 세분류 |
sort_order | number | 형제 카테고리 사이의 차례 |
is_all | boolean | 전체 카테고리인가(몰마다 하나, slug all) |
displayed | boolean | 손님 화면에 보이는가 |
access_permission | string | 누가 볼 수 있나 코드값 |
access_level | number | MEMBER 일 때 볼 수 있는 최소 등급 레벨(0 이면 모든 회원) |
list_type | string | 상품 목록 모양 코드값 |
list_sort | string | 상품 목록의 기본 차례 코드값 |
top.text | object | 상단 문구 — enabled · title · description · text_color · background_color · size · position |
top.banner | object | 상단 배너 — enabled · pc_image · mobile_image · background_color · combine · link_kind · link_value · link_target |
top.banner.pc_image · mobile_image | string | object | null | 배너 이미지 한 장씩. 보낼 때는 키만 — 이미지 업로드(?usage=category.banner)로 받은 file_id 를 문자열 "…" 또는 {"file_id": "…"} 로 넣습니다. 저장소 · 경로 · 주소 · 크기는 서버가 이 쇼핑몰의 파일 기록에서 채우고(보낸 값은 버림), 다른 쇼핑몰 · 지워진 파일이면 400. 응답은 file_id · url · width · height 를 줍니다. 배너를 바꾸거나 카테고리를 지우면 옛 파일은 지워집니다 |
top.video | object | 상단 동영상 — enabled · url · ratio · autoplay |
top.recommend | object | 추천 상품 — enabled · title · product_ids(고른 차례 그대로) |
오류
| 상태 | code | 언제 |
|---|---|---|
| 401 | MissingLoginSession | Authorization 헤더에 Bearer 토큰이 없음 |
| 401 | InvalidAccessToken | 토큰이 틀리거나 만료 · 폐기됨 |
| 403 | InsufficientScope | 토큰에 products:read 가 없음 |
생성
POST
https://api.mallstory.kr/v1/shop/{shop_unique}/categories권한 products:write
요청 본문
| 필드 | 형식 | 설명 |
|---|---|---|
name필수 | string | 카테고리 이름(생성 때 필수) |
parent_id | string | null | 상위 카테고리 키(생성 때만). 없으면 대분류 — 대분류는 15개까지, 단계는 4까지 |
displayed | boolean | 손님 화면에 보이는가(기본 true) |
access_permission | string | 누가 볼 수 있나(기본 GUEST) 코드값 |
access_level | number | MEMBER 일 때 최소 등급 레벨 |
list_type | string | 상품 목록 모양 코드값 |
list_sort | string | 상품 목록의 기본 차례 코드값 |
top | object | 상단 문구 · 배너 · 동영상 · 추천 상품(응답의 top 과 같은 모양) |
bash요청
curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/categories' \
-H 'Authorization: Bearer msat_8Hk2wQ7...' \
-H 'Content-Type: application/json' \
-d '{"name":"봄 신상","displayed":true,"list_type":"CARD","list_sort":"CREATED"}'json201 Created (관계있는 줄만)
{
"items": [
{
"name": "전체 카테고리",
"displayed": true,
"access_permission": "GUEST",
"access_level": 0,
"list_type": "CARD",
"list_sort": "DISPLAY",
"top": {
"text": {
"enabled": true,
"title": "zz",
"description": "cccc",
"text_color": "#FFFFFF",
"background_color": "#06B6D4",
"size": "XLARGE",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": true,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6aab71c3dd8941ed187ffe56",
"parent_id": null,
"depth": 0,
"sort_order": 0,
"slug": "all",
"is_all": true,
"full_name": "전체 카테고리"
},
{
"name": "봄 신상",
"displayed": true,
"access_permission": "GUEST",
"access_level": 0,
"list_type": "CARD",
"list_sort": "CREATED",
"top": {
"text": {
"enabled": false,
"title": "",
"description": "",
"text_color": "#000000",
"background_color": "",
"size": "MEDIUM",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": false,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6accb194c2ca90eedea6211c",
"parent_id": null,
"depth": 0,
"sort_order": 9,
"slug": "73eos897",
"is_all": false,
"full_name": "봄 신상"
}
]
}하위 카테고리 생성
bash요청 — parent_id 로 '봄 신상' 아래에
curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/categories' \
-H 'Authorization: Bearer msat_8Hk2wQ7...' \
-H 'Content-Type: application/json' \
-d '{"name":"셔츠","parent_id":"6accb194c2ca90eedea6211c"}'json201 Created (관계있는 줄만)
{
"items": [
{
"name": "전체 카테고리",
"displayed": true,
"access_permission": "GUEST",
"access_level": 0,
"list_type": "CARD",
"list_sort": "DISPLAY",
"top": {
"text": {
"enabled": true,
"title": "zz",
"description": "cccc",
"text_color": "#FFFFFF",
"background_color": "#06B6D4",
"size": "XLARGE",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": true,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6aab71c3dd8941ed187ffe56",
"parent_id": null,
"depth": 0,
"sort_order": 0,
"slug": "all",
"is_all": true,
"full_name": "전체 카테고리"
},
{
"name": "봄 신상",
"displayed": true,
"access_permission": "GUEST",
"access_level": 0,
"list_type": "CARD",
"list_sort": "CREATED",
"top": {
"text": {
"enabled": false,
"title": "",
"description": "",
"text_color": "#000000",
"background_color": "",
"size": "MEDIUM",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": false,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6accb194c2ca90eedea6211c",
"parent_id": null,
"depth": 0,
"sort_order": 9,
"slug": "73eos897",
"is_all": false,
"full_name": "봄 신상"
},
{
"name": "셔츠",
"displayed": true,
"access_permission": "GUEST",
"access_level": 0,
"list_type": "CARD",
"list_sort": "DISPLAY",
"top": {
"text": {
"enabled": false,
"title": "",
"description": "",
"text_color": "#000000",
"background_color": "",
"size": "MEDIUM",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": false,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6accb194c2ca90eedea6211d",
"parent_id": "6accb194c2ca90eedea6211c",
"depth": 1,
"sort_order": 0,
"slug": "leblslcm",
"is_all": false,
"full_name": " 셔츠"
}
]
}오류
| 상태 | code | 언제 |
|---|---|---|
| 400 | InvalidParameterValue | 이름이 없음 · 대분류 15개 초과 · 4단계 초과 · 전체 카테고리 아래에 만듦 |
| 401 | MissingLoginSession | Authorization 헤더에 Bearer 토큰이 없음 |
| 401 | InvalidAccessToken | 토큰이 틀리거나 만료 · 폐기됨 |
| 403 | InsufficientScope | 토큰에 products:write 가 없음 |
수정
PATCH
https://api.mallstory.kr/v1/shop/{shop_unique}/categories/{category_unique}권한 products:write
보낸 필드만 바뀝니다. include_children: true 를 함께 보내면 노출 · 접근 권한을 하위 카테고리에도 똑같이 겁니다.
요청 본문
| 필드 | 형식 | 설명 |
|---|---|---|
name | string | 카테고리 이름(생성 때 필수) |
displayed | boolean | 손님 화면에 보이는가(기본 true) |
access_permission | string | 누가 볼 수 있나(기본 GUEST) 코드값 |
access_level | number | MEMBER 일 때 최소 등급 레벨 |
list_type | string | 상품 목록 모양 코드값 |
list_sort | string | 상품 목록의 기본 차례 코드값 |
top | object | 상단 문구 · 배너 · 동영상 · 추천 상품(응답의 top 과 같은 모양) |
include_children | boolean | displayed · access_permission · access_level 을 하위에도 적용 |
bash요청
curl -X PATCH 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/categories/6accb194c2ca90eedea6211c' \
-H 'Authorization: Bearer msat_8Hk2wQ7...' \
-H 'Content-Type: application/json' \
-d '{"access_permission":"MEMBER","access_level":0,"include_children":true}'json200 OK (관계있는 줄만) — 하위 '셔츠' 에도 회원 전용이 걸림
{
"items": [
{
"name": "전체 카테고리",
"displayed": true,
"access_permission": "GUEST",
"access_level": 0,
"list_type": "CARD",
"list_sort": "DISPLAY",
"top": {
"text": {
"enabled": true,
"title": "zz",
"description": "cccc",
"text_color": "#FFFFFF",
"background_color": "#06B6D4",
"size": "XLARGE",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": true,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6aab71c3dd8941ed187ffe56",
"parent_id": null,
"depth": 0,
"sort_order": 0,
"slug": "all",
"is_all": true,
"full_name": "전체 카테고리"
},
{
"name": "봄 신상",
"displayed": true,
"access_permission": "MEMBER",
"access_level": 0,
"list_type": "CARD",
"list_sort": "CREATED",
"top": {
"text": {
"enabled": false,
"title": "",
"description": "",
"text_color": "#000000",
"background_color": "",
"size": "MEDIUM",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": false,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6accb194c2ca90eedea6211c",
"parent_id": null,
"depth": 0,
"sort_order": 9,
"slug": "73eos897",
"is_all": false,
"full_name": "봄 신상"
},
{
"name": "셔츠",
"displayed": true,
"access_permission": "MEMBER",
"access_level": 0,
"list_type": "CARD",
"list_sort": "DISPLAY",
"top": {
"text": {
"enabled": false,
"title": "",
"description": "",
"text_color": "#000000",
"background_color": "",
"size": "MEDIUM",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": false,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6accb194c2ca90eedea6211d",
"parent_id": "6accb194c2ca90eedea6211c",
"depth": 1,
"sort_order": 0,
"slug": "leblslcm",
"is_all": false,
"full_name": " 셔츠"
}
]
}오류
| 상태 | code | 언제 |
|---|---|---|
| 404 | CategoryNotExist | 없는 키 |
| 401 | MissingLoginSession | Authorization 헤더에 Bearer 토큰이 없음 |
| 401 | InvalidAccessToken | 토큰이 틀리거나 만료 · 폐기됨 |
| 403 | InsufficientScope | 토큰에 products:write 가 없음 |
옮기기
POST
https://api.mallstory.kr/v1/shop/{shop_unique}/categories/{category_unique}/move권한 products:write
요청 본문
| 필드 | 형식 | 설명 |
|---|---|---|
parent_id필수 | string | null | 새 상위 카테고리 키. null 이면 대분류로 |
index필수 | number | 형제 사이의 자리(0부터) |
bash요청
curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/categories/6accb194c2ca90eedea6211d/move' \
-H 'Authorization: Bearer msat_8Hk2wQ7...' \
-H 'Content-Type: application/json' \
-d '{"parent_id":null,"index":1}'json200 OK (관계있는 줄만) — '셔츠' 가 대분류 두 번째 자리로
{
"items": [
{
"name": "전체 카테고리",
"displayed": true,
"access_permission": "GUEST",
"access_level": 0,
"list_type": "CARD",
"list_sort": "DISPLAY",
"top": {
"text": {
"enabled": true,
"title": "zz",
"description": "cccc",
"text_color": "#FFFFFF",
"background_color": "#06B6D4",
"size": "XLARGE",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": true,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6aab71c3dd8941ed187ffe56",
"parent_id": null,
"depth": 0,
"sort_order": 0,
"slug": "all",
"is_all": true,
"full_name": "전체 카테고리"
},
{
"name": "셔츠",
"displayed": true,
"access_permission": "MEMBER",
"access_level": 0,
"list_type": "CARD",
"list_sort": "DISPLAY",
"top": {
"text": {
"enabled": false,
"title": "",
"description": "",
"text_color": "#000000",
"background_color": "",
"size": "MEDIUM",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": false,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6accb194c2ca90eedea6211d",
"parent_id": null,
"depth": 0,
"sort_order": 1,
"slug": "leblslcm",
"is_all": false,
"full_name": "셔츠"
},
{
"name": "봄 신상",
"displayed": true,
"access_permission": "MEMBER",
"access_level": 0,
"list_type": "CARD",
"list_sort": "CREATED",
"top": {
"text": {
"enabled": false,
"title": "",
"description": "",
"text_color": "#000000",
"background_color": "",
"size": "MEDIUM",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": false,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6accb194c2ca90eedea6211c",
"parent_id": null,
"depth": 0,
"sort_order": 10,
"slug": "73eos897",
"is_all": false,
"full_name": "봄 신상"
}
]
}- 하위 카테고리도 함께 옮겨지고, 4단계를 넘으면 거절됩니다.
- 전체 카테고리는 대분류 사이에서만 옮길 수 있습니다.
오류
| 상태 | code | 언제 |
|---|---|---|
| 400 | InvalidParameterValue | 4단계 초과 · 자기 하위로 옮김 · 전체 카테고리를 하위로 |
| 401 | MissingLoginSession | Authorization 헤더에 Bearer 토큰이 없음 |
| 401 | InvalidAccessToken | 토큰이 틀리거나 만료 · 폐기됨 |
| 403 | InsufficientScope | 토큰에 products:write 가 없음 |
삭제
DELETE
https://api.mallstory.kr/v1/shop/{shop_unique}/categories/{category_unique}권한 products:write
하위 카테고리까지 지우고, 걸려 있던 상품에서 뗍니다.
bash요청
curl -X DELETE 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/categories/6accb194c2ca90eedea6211c' \
-H 'Authorization: Bearer msat_8Hk2wQ7...'json200 OK
{
"items": [
{
"name": "전체 카테고리",
"displayed": true,
"access_permission": "GUEST",
"access_level": 0,
"list_type": "CARD",
"list_sort": "DISPLAY",
"top": {
"text": {
"enabled": true,
"title": "zz",
"description": "cccc",
"text_color": "#FFFFFF",
"background_color": "#06B6D4",
"size": "XLARGE",
"position": "CENTER_MIDDLE"
},
"banner": {
"enabled": true,
"mobile_image": null,
"pc_image": null,
"background_color": "",
"combine": "SPLIT",
"link_kind": "URL",
"link_value": "",
"link_target": "SELF"
},
"video": {
"enabled": false,
"url": "",
"ratio": "AUTO",
"autoplay": false
},
"recommend": {
"enabled": false,
"title": "",
"product_ids": []
}
},
"category_unique": "6aab71c3dd8941ed187ffe56",
"parent_id": null,
"depth": 0,
"sort_order": 0,
"slug": "all",
"is_all": true,
"full_name": "전체 카테고리"
}
],
"removed": 1,
"affected": 0
}응답 필드
| 필드 | 형식 | 설명 |
|---|---|---|
items | array | 지운 뒤의 전체 목록 |
removed | number | 지운 카테고리 수(하위 포함) |
affected | number | 카테고리가 떼어진 상품 수 |
json400 — 전체 카테고리를 지우려 함
{
"code": "InvalidParameterValue",
"message": "전체 카테고리는 삭제할 수 없습니다."
}오류
| 상태 | code | 언제 |
|---|---|---|
| 400 | InvalidParameterValue | 전체 카테고리는 삭제할 수 없음 |
| 404 | CategoryNotExist | 없는 키 |
| 401 | MissingLoginSession | Authorization 헤더에 Bearer 토큰이 없음 |
| 401 | InvalidAccessToken | 토큰이 틀리거나 만료 · 폐기됨 |
| 403 | InsufficientScope | 토큰에 products:write 가 없음 |