v1 API 상세: 카탈로그
상품을 묶어 쇼핑몰 화면에 내보내는 단위입니다.
카테고리가 상품의 분류라면, 진열은 상품의 편성입니다. 한 상품이 여러 진열에 동시에 들어갈 수 있고, 진열 안에서 순서를 직접 정할 수 있습니다.
화면 용어는 「진열」이지만 엔드포인트는 /v1/catalogs 입니다. 상품 진열 상태의 status_display 와도 다른 개념입니다 — 그건 상품 한 건의 노출 스위치고, 진열은 묶음입니다.
진열 목록
필요 권한: user:catalog_list
파라미터가 없습니다. 정렬 순서(position)대로 돌려줍니다.
{
"list": [
{
"catalog_id": "67c95e64d01640bb9859c629",
"name": "이번 주 신상",
"description": "매주 월요일 교체",
"status_view": true,
"position": 0,
"product_count": 12,
"cover": "https://.../cover.png"
}
]
}json| 필드 | 타입 | 설명 |
|---|---|---|
catalog_id |
String | 선택 |
name |
String | 선택 |
description |
String | 선택 |
status_view |
Boolean | 선택 |
position |
Integer | 선택 |
product_count |
Integer | 선택 |
cover |
String | 선택 |
진열 상세
필요 권한: user:catalog_detail
전시 중인 진열의 정보와 공개 상품 한 페이지를 함께 돌려줍니다. 전시하지 않는 진열이나 다른 프로젝트의 진열은 404 CATALOG_NOT_FOUND 입니다. 상품만 필요하면 아래 상품 목록을 사용합니다.
page(기본 1), limit(기본 20, 최대 100), sort 쿼리로 상품을 넘겨 볼 수 있습니다. sort 는 position, -created_at, created_at, price, -price, -sold 를 받습니다. 전체 공개 상품 수는 total_count, 다음 페이지 여부는 has_more 로 확인합니다 (page·per 도 함께 옵니다). products 항목은 _id(진열-상품 연결 ID)·product_id·catalog_id·position·product(상품 목록 항목과 같은 구조)입니다. product_count 는 공개 여부와 관계없는 연결 상품 수라 total_count 와 다를 수 있습니다.
진열 생성
필요 권한: user:catalog_create
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
name |
String | 필수 | 진열 이름 |
description |
String | 선택 | 설명 |
cover |
String | 선택 | 커버 이미지 URL |
status_view |
Boolean | 선택 | 쇼핑몰 전시 여부. 보내지 않으면 false 입니다 — JSON Boolean true 로 보냅니다 |
curl -X POST "https://api.bootapi.com/v1/catalogs" \
-H "Authorization: Basic {base64(client_key:secret_key)}" \
-H "Content-Type: application/json" \
-d '{ "name": "이번 주 신상", "status_view": true }'bash{ "id": "67c95e64d01640bb9859c629" }json전체 필드가 필요하면 받은 id 로 진열 상세를 한 번 더 불러옵니다.
진열 수정
필요 권한: user:catalog_update
생성과 같은 파라미터를 받습니다. 성공하면 본문에 의미 있는 값이 없습니다.
지금은 name·description·cover·status_view 중 빼고 보낸 값이 비워집니다. status_view 가 비면 전시가 꺼집니다.
수정할 때는 진열 상세로 현재 값을 읽어 네 값을 모두 함께 보냅니다.
진열 순서 변경
필요 권한: user:catalog_reorder
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
ids |
Array | 필수 | 진열 ID 배열. 배열 순서가 그대로 화면 순서가 됩니다 |
curl -X PUT "https://api.bootapi.com/v1/catalogs/reorder" \
-H "Authorization: Basic {base64(client_key:secret_key)}" \
-H "Content-Type: application/json" \
-d '{ "ids": ["catalog_c", "catalog_a", "catalog_b"] }'bashreorder 는 collection 경로입니다. /v1/catalogs/reorder 를 진열 하나의 ID 로 착각하지 않도록 주의합니다.
성공하면 본문은 null 입니다.
진열 삭제
필요 권한: user:catalog_delete
진열과 함께 진열-상품 연결이 지워집니다. 상품 자체는 남습니다. 성공하면 본문은 null 입니다.
진열 안 상품 목록
필요 권한: user:catalog_products
진열 상세와 같이 전시 중인 진열의 공개 상품을 페이지 단위로 돌려줍니다. page(기본 1), limit(기본 20, 최대 100), sort 를 받으며 응답은 { list, count, page, limit } 입니다. count 는 공개 상품 수입니다.
상품 추가
필요 권한: user:catalog_add_products
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
product_ids |
Array | 필수 | 추가할 상품 ID 배열 |
중복은 서버가 거릅니다. 같은 배열을 두 번 보내도 상품이 두 번 들어가지 않습니다.
{ "added": 2, "skipped": 1, "rejected_product_ids": [] }jsonadded 는 새로 넣은 수, skipped 는 이미 들어 있어서 건너뛴 수입니다. 다른 프로젝트나 없는 상품 ID 는 넣지 않고 rejected_product_ids 에 돌려줍니다.
상품 제거
필요 권한: user:catalog_remove_product
진열에서 한 건만 뺍니다. 상품은 삭제되지 않습니다. 성공하면 본문은 null 입니다.
진열 안 상품 순서 변경
필요 권한: user:catalog_reorder_products
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
product_ids |
Array | 필수 | 상품 ID 배열. 배열 순서가 진열 안 노출 순서가 됩니다 |
성공하면 본문은 null 입니다.
에러 코드
인증·권한 관련 에러는 커머스 API 인증 에러를 참고합니다.
| 코드 | 메시지 | 대처 방법 |
|---|---|---|
CATALOG_ |
진열을 찾을 수 없습니다 | :id 가 이 프로젝트의 진열인지 확인합니다. 조회에서는 전시 중이어야 합니다 |
CATALOG_ |
카탈로그 이름은 필수입니다. | 진열 생성에 name 을 넣습니다 |
CATALOG_ |
카탈로그-상품 연결을 찾을 수 없습니다. | 상품 제거의 :product_id 가 이 진열에 들어 있는지 확인합니다 |



