카테고리 | Bootpay 커머스 매뉴얼

상품을 분류하는 트리를 관리해요. 상품 생성의 category_id 가 여기서 나와요.

카테고리는 부모-자식 트리예요. 최상위 카테고리는 parent_category_id 없이 만들고, 하위 카테고리는 부모 ID 를 넣어 만들어요. 목록 조회는 최상위만 돌려주고 자식은 그 안에 접혀 들어와요.

카테고리는 상품이 무엇인가(분류)이고, 진열은 어디에 보여줄 것인가(편성)예요. 같은 상품이 하나의 카테고리에 속하면서 여러 진열에 동시에 들어갈 수 있어요.

목록 조회

GEThttps://api.bootapi.com/v1/categoriesBasic Auth

필요 권한: user:category_list

파라미터가 없어요. 프로젝트의 카테고리 트리 전체를 돌려줘요.

curl -X GET "https://api.bootapi.com/v1/categories" \
  -H "Authorization: Basic {base64(client_key:secret_key)}"bash

[
  {
    "_id": "67c95e64d01640bb9859c629",
    "name": "의류",
    "parent_category_id": "",
    "status_display": true,
    "status_best": false,
    "filter_color": 0,
    "filter_size": 0,
    "children": []
  }
]json

필드	타입	설명
`_id`	String	선택
`name`	String	선택
`parent_category_id`	String	선택
`status_display`	Boolean	선택
`status_best`	Boolean	선택
`filter_color`	Integer	선택
`filter_size`	Integer	선택
`children`	Array	선택

상세 조회

GEThttps://api.bootapi.com/v1/categories/:idBasic Auth

필요 권한: user:category_detail

없는 ID 를 넣으면 CATEGORY_NOT_FOUND 가 돌아와요. 상세 응답의 children 은 항상 빈 배열이에요 — 하위 카테고리는 목록 조회로 봐요.

생성

POSThttps://api.bootapi.com/v1/categoriesBasic Auth (supervisor 권한 필요)

필요 권한: supervisor:category_create

파라미터	타입	필수	설명
`name`	String	필수	카테고리 이름 (서버가 비어 있는지 검사하지 않으니 꼭 보내요)
`parent_category_id`	String	선택	부모 카테고리 ID. 비우면 최상위로 만들어요
`status_display`	Boolean	선택	쇼핑몰 노출 여부 (보내지 않으면 `false`)
`status_best`	Boolean	선택	베스트 카테고리 표시 여부 (보내지 않으면 `false`)
`filter_color`	Integer	선택	색상 필터 설정 (`status_display: true` 일 때만 저장)
`filter_size`	Integer	선택	사이즈 필터 설정 (`status_display: true` 일 때만 저장)

지금은 두 값을 정수로 저장해서, status_display: true 와 함께 true·false 를 보내면 SERVER_ERROR(HTTP 500)가 나요. 응답에도 Boolean 이 아니라 정수나 null 로 와요.

두 값은 빼고 보내요. 빼면 status_display: true 일 때 0, 아니면 null 로 저장돼요.

curl -X POST "https://api.bootapi.com/v1/categories" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Bootpay-Role: supervisor" \
  -H "Content-Type: application/json" \
  -d '{ "name": "아우터", "parent_category_id": "67c95e64d01640bb9859c629", "status_display": true }'bash

응답은 목록 조회와 같은 모양의 카테고리 하나예요.

수정

PUThttps://api.bootapi.com/v1/categories/:idBasic Auth (supervisor 권한 필요)

필요 권한: supervisor:category_update

생성과 같은 파라미터를 받아요. parent_category_id 를 바꾸면 트리에서 자리가 옮겨져요.

지금은 이 요청이 SERVER_ERROR(HTTP 500)로 끝나고 아무것도 바뀌지 않아요. 카테고리 수정은 관리자 화면에서 해요.

삭제

DELETEhttps://api.bootapi.com/v1/categories/:idBasic Auth (supervisor 권한 필요)

필요 권한: supervisor:category_delete

삭제는 재귀적이에요. 하위 카테고리가 있으면 전부 같이 사라져요. 지우기 전에 목록 조회로 트리를 확인해요.

에러 코드

인증·권한 관련 에러는 커머스 API 인증 에러를 참고해요.

코드	메시지	대처 방법
`CATEGORY_NOT_FOUND`	카테고리를 찾을 수 없어요	`:id` 가 이 프로젝트의 카테고리인지 확인해요
`CATEGORY_NOT_OWNED_BY_SELLER`	판매자의 카테고리가 아니에요. 다시 확인해요. (HTTP 401)	다른 프로젝트의 카테고리를 지우려 했는지 확인해요
`API_SCOPE_INVALID`	현재 API 키에 필요한 권한이 없어요	생성·수정·삭제는 supervisor 권한이 필요해요

함께 보기

상품 생성 — category_id 로 상품을 카테고리에 넣어요
진열 — 카테고리와 별개로 상품을 편성해요