Mall StoryDevelopers
관리자 API상품 관리소유자 토큰

상품 카테고리

관리자 권한으로 상품 카테고리 트리(최대 4단계)를 만들고 고치고 옮기고 지웁니다.

업데이트됨 10.13 — 이미지 칸은 어디서 저장하든 파일 키만 믿습니다

무엇인가요

쇼핑몰 소유자를 대신하는 토큰으로 상품 카테고리 트리를 다룹니다. 쇼핑몰 관리자 > 상품 > 상품 카테고리와 같은 규칙입니다.

  • 트리를 한 줄 목록으로 줍니다 — parent_id · depth · sort_order 로 세웁니다. 최대 4단계, 대분류는 15개까지입니다.
  • is_all: true 는 '전체' 카테고리(slug all)입니다. 지우거나 하위를 두거나 상품에 걸 수 없습니다.
  • 생성 · 수정 · 옮기기 · 삭제는 모두 바뀐 뒤의 전체 목록을 돌려줍니다. 아래 예시는 길어서 관계있는 줄만 남겼습니다.
요청경로바로가기권한
GET/categories목록products:read
POST/categories생성products:write
PATCH/categories/{category_unique}수정products:write
POST/categories/{category_unique}/move옮기기products:write
DELETE/categories/{category_unique}삭제products:write

목록

GEThttps://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_uniquestring카테고리 키. 상품의 category_id 에 넣는 값
namestring카테고리 이름
full_namestring상위까지 이은 이름(예: 봄 신상 > 셔츠)
slugstring쇼핑몰 주소 조각(/category/{slug}). 쇼핑몰 조회 API 도 이 값을 씁니다
parent_idstring | null상위 카테고리 키. 대분류는 null
depthnumber단계 — 0 대분류 · 1 중분류 · 2 소분류 · 3 세분류
sort_ordernumber형제 카테고리 사이의 차례
is_allboolean전체 카테고리인가(몰마다 하나, slug all)
displayedboolean손님 화면에 보이는가
access_permissionstring누가 볼 수 있나 코드값
access_levelnumberMEMBER 일 때 볼 수 있는 최소 등급 레벨(0 이면 모든 회원)
list_typestring상품 목록 모양 코드값
list_sortstring상품 목록의 기본 차례 코드값
top.textobject상단 문구 — enabled · title · description · text_color · background_color · size · position
top.bannerobject상단 배너 — enabled · pc_image · mobile_image · background_color · combine · link_kind · link_value · link_target
top.banner.pc_image · mobile_imagestring | object | null배너 이미지 한 장씩. 보낼 때는 키만 — 이미지 업로드(?usage=category.banner)로 받은 file_id 를 문자열 "…" 또는 {"file_id": "…"} 로 넣습니다. 저장소 · 경로 · 주소 · 크기는 서버가 이 쇼핑몰의 파일 기록에서 채우고(보낸 값은 버림), 다른 쇼핑몰 · 지워진 파일이면 400. 응답은 file_id · url · width · height 를 줍니다. 배너를 바꾸거나 카테고리를 지우면 옛 파일은 지워집니다
top.videoobject상단 동영상 — enabled · url · ratio · autoplay
top.recommendobject추천 상품 — enabled · title · product_ids(고른 차례 그대로)

오류

상태code언제
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:read 가 없음

생성

POSThttps://api.mallstory.kr/v1/shop/{shop_unique}/categories

권한 products:write

요청 본문

필드형식설명
name필수string카테고리 이름(생성 때 필수)
parent_idstring | null상위 카테고리 키(생성 때만). 없으면 대분류 — 대분류는 15개까지, 단계는 4까지
displayedboolean손님 화면에 보이는가(기본 true)
access_permissionstring누가 볼 수 있나(기본 GUEST) 코드값
access_levelnumberMEMBER 일 때 최소 등급 레벨
list_typestring상품 목록 모양 코드값
list_sortstring상품 목록의 기본 차례 코드값
topobject상단 문구 · 배너 · 동영상 · 추천 상품(응답의 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언제
400InvalidParameterValue이름이 없음 · 대분류 15개 초과 · 4단계 초과 · 전체 카테고리 아래에 만듦
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:write 가 없음

수정

PATCHhttps://api.mallstory.kr/v1/shop/{shop_unique}/categories/{category_unique}

권한 products:write

보낸 필드만 바뀝니다. include_children: true 를 함께 보내면 노출 · 접근 권한을 하위 카테고리에도 똑같이 겁니다.

요청 본문

필드형식설명
namestring카테고리 이름(생성 때 필수)
displayedboolean손님 화면에 보이는가(기본 true)
access_permissionstring누가 볼 수 있나(기본 GUEST) 코드값
access_levelnumberMEMBER 일 때 최소 등급 레벨
list_typestring상품 목록 모양 코드값
list_sortstring상품 목록의 기본 차례 코드값
topobject상단 문구 · 배너 · 동영상 · 추천 상품(응답의 top 과 같은 모양)
include_childrenbooleandisplayed · 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언제
404CategoryNotExist없는 키
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:write 가 없음

옮기기

POSThttps://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언제
400InvalidParameterValue4단계 초과 · 자기 하위로 옮김 · 전체 카테고리를 하위로
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:write 가 없음

삭제

DELETEhttps://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
}

응답 필드

필드형식설명
itemsarray지운 뒤의 전체 목록
removednumber지운 카테고리 수(하위 포함)
affectednumber카테고리가 떼어진 상품 수
json400 — 전체 카테고리를 지우려 함
{
  "code": "InvalidParameterValue",
  "message": "전체 카테고리는 삭제할 수 없습니다."
}

오류

상태code언제
400InvalidParameterValue전체 카테고리는 삭제할 수 없음
404CategoryNotExist없는 키
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:write 가 없음