상품 카테고리 트리를 조회하고 관리합니다. 카테고리는 여러 단계로 중첩할 수 있고, 상품은 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 문서 최초 작성
