카테고리

상품 카테고리 트리를 조회하고 관리합니다. 카테고리는 여러 단계로 중첩할 수 있고, 상품은 category_id 로 카테고리 하나에 연결됩니다(상품).

조회는 user scope, 생성·수정·삭제는 supervisor scope 로 검사합니다. scope 의 역할 부분은 Bootpay-Role 헤더로 바뀝니다 — 인증.

카테고리 객체

필드 타입 설명
_id string 카테고리 ID
name string 이름
parent_category_id string 부모 카테고리 ID. 최상위면 빈 문자열 ""
status_display boolean 전시 여부
status_best boolean 베스트 카테고리 여부
filter_color integer 색상 필터 설정
filter_size integer 사이즈 필터 설정
children array 하위 카테고리(같은 형태)

GET /v1/categories

이 프로젝트의 카테고리 전체를 트리로 조회합니다. 최상위 카테고리 배열이고, 각 카테고리의 children 에 하위 카테고리가 들어 있습니다. 같은 단계 안에서는 관리자에서 정한 순서입니다. 페이지네이션은 없습니다.

전시하지 않는(status_display=false) 카테고리도 포함됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:category_list
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

파라미터가 없습니다.

응답

200 OK

[
  {
    "_id": "66f1c1a0e1b2c3d4e5f60001",
    "name": "커피",
    "parent_category_id": "",
    "status_display": true,
    "status_best": false,
    "filter_color": 0,
    "filter_size": 0,
    "children": [
      {
        "_id": "66f1c1a0e1b2c3d4e5f60002",
        "name": "드립백",
        "parent_category_id": "66f1c1a0e1b2c3d4e5f60001",
        "status_display": true,
        "status_best": true,
        "filter_color": 0,
        "filter_size": 0,
        "children": []
      }
    ]
  }
]json

필드는 위 카테고리 객체​​를 봅니다.

오류

공통 오류(인증·scope·방화벽)만 있습니다 — 오류.

변경 이력

  • 2026-09-23 문서 최초 작성

POST /v1/categories

카테고리를 만듭니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:category_create (Bootpay-Role 헤더가 없을 때)
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body name string O 이름
body parent_category_id string 부모 카테고리 ID. 없으면 최상위
body status_display boolean false 전시 여부. true/"true" 만 참으로 봅니다
body status_best boolean false 베스트 카테고리 여부
body filter_color integer 색상 필터. status_display=true 일 때만 저장됩니다
body filter_size integer 사이즈 필터. status_display=true 일 때만 저장됩니다

응답

200 OK — 만든 카테고리(​​카테고리 객체​). children 은 빈 배열입니다.

{
  "_id": "66f1c1a0e1b2c3d4e5f60003",
  "name": "원두",
  "parent_category_id": "66f1c1a0e1b2c3d4e5f60001",
  "status_display": true,
  "status_best": false,
  "filter_color": 0,
  "filter_size": 0,
  "children": []
}json

오류

HTTP error_code 언제
404 CATEGORY_NOT_FOUND parent_category_id 가 없는 카테고리

변경 이력

  • 2026-09-23 문서 최초 작성

GET /v1/categories/:id

카테고리 하나를 조회합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:category_detail
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 카테고리 ID

응답

200 OK — 카테고리 객체​. 이 API 의 children 은 하위 카테고리가 있어도 항상 빈 배열​​입니다. 하위 트리는 GET /v1/categories 로 읽으세요.

오류

HTTP error_code 언제
404 CATEGORY_NOT_FOUND 없는 ID 또는 다른 프로젝트의 카테고리

변경 이력

  • 2026-09-23 문서 최초 작성

PUT /v1/categories/:id

카테고리를 수정합니다. PATCH 도 같습니다.

알려진 문제​: 현재 이 API 는 카테고리를 바꾸기 전에 500 SERVER_ERROR 로 실패합니다. 수정은 관리자 화면에서 하세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:category_update (Bootpay-Role 헤더가 없을 때)
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 카테고리 ID
body name string O 이름
body parent_category_id string 부모 카테고리 ID. 보내지 않으면 최상위로 옮겨집니다
body status_display boolean false 전시 여부
body status_best boolean false 베스트 여부
body filter_color integer 색상 필터 (status_display=true 일 때만)
body filter_size integer 사이즈 필터 (status_display=true 일 때만)

전체 값을 바꾸는 방식입니다. 보내지 않은 필드는 기존 값을 유지하지 않고 위 기본값(이름은 빈 값)이 됩니다.

응답

200 OK (정상 동작 시) — 수정한 카테고리 객체​.

오류

HTTP error_code 언제
401 CATEGORY_NOT_OWNED_BY_SELLER 다른 판매자·다른 프로젝트의 카테고리
404 CATEGORY_NOT_FOUND 없는 ID 또는 없는 parent_category_id
500 SERVER_ERROR 위 알려진 문제

변경 이력

  • 2026-09-23 문서 최초 작성

DELETE /v1/categories/:id

카테고리와 그 아래 모든 하위 카테고리​​를 지웁니다. 되돌릴 수 없습니다. 연결돼 있던 상품은 지워지지 않습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:category_delete (Bootpay-Role 헤더가 없을 때)
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 카테고리 ID

응답

200 OK — 본문에 의미 있는 값이 없습니다.

오류

HTTP error_code 언제
401 CATEGORY_NOT_OWNED_BY_SELLER 다른 프로젝트의 카테고리
404 CATEGORY_NOT_FOUND 없는 ID

변경 이력

  • 2026-07-27 직계 자식만 지우던 것을 모든 하위 단계까지 지우도록 수정
  • 2026-09-23 문서 최초 작성

함께 보기