카테고리

v1 API 상세: 카테고리, 상품

상품을 분류하는 트리를 관리합니다. 상품 생성의 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 일 때만 저장)
알려진 문제 — filter_color·filter_size 를 Boolean 으로 보내면 500 입니다

지금은 두 값을 정수로 저장해서, 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 를 바꾸면 트리에서 자리가 옮겨집니다.

알려진 문제 — 카테고리 수정이 항상 500 으로 실패합니다

지금은 이 요청이 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 권한이 필요합니다

함께 보기