카탈로그는 기획전·컬렉션처럼 상품을 골라 묶은 전시 단위입니다. 카탈로그 자체를 만들고 순서를 정하며, 카탈로그에 상품을 넣고 빼고 순서를 바꿉니다.
- 조회(
GET)는 구매자 화면 기준입니다. 인증된 프로젝트의 전시 중(status_view=true) 카탈로그와 그 안의 공개 상품만 돌려줍니다. 공개 상품 조건은 상품의 목록·상세 조건을 모두 만족하는 상품입니다. - 쓰기(생성·수정·삭제·상품 추가 등)는 전시 여부와 상관없이 카탈로그 ID 로 동작합니다. 대상은 인증된 프로젝트의 카탈로그뿐이며, 같은 판매자라도 다른 프로젝트의 카탈로그 ID 는 없는 ID 와 같은
404입니다.
scope 는 user:catalog_<동작> 형식입니다 — 인증.
카탈로그 객체
| 필드 | 타입 | 설명 |
|---|---|---|
| catalog_id | string | 카탈로그 ID |
| project_id, seller_id | string | 프로젝트·판매자 ID |
| name | string | 이름 |
| description | string | 설명 |
| cover | string | 커버 이미지 URL |
| cover_mobile | string | 모바일 커버 이미지 URL |
| type | string | product(상품 카탈로그), category(카테고리 카탈로그) |
| status_view | boolean | 전시 여부 |
| position | integer | 카탈로그 순서 (작을수록 앞) |
| sort_type | string | 카탈로그 안 상품 기본 정렬. position, created_at_desc, created_at, price, price_desc, sold_desc 등 |
| view_type_pc, view_type_mobile | string | 표시 방식 list, grid, image, gallery |
| product_count | integer | 연결된 상품 수 (공개 여부와 무관) |
| metadata | object | 부가 정보 |
| link_type | integer | 배너 클릭 동작 |
| link_url | string | 배너 링크 |
| started_at, ended_at | string | 노출 기간 (ISO 8601, null 이면 상시) |
| created_at, updated_at | string | ISO 8601 |
카탈로그 상품 항목
| 필드 | 타입 | 설명 |
|---|---|---|
| _id | string | 카탈로그–상품 연결 ID |
| product_id | string | 상품 ID |
| catalog_id | string | 카탈로그 ID |
| position | integer | 카탈로그 안 순서 |
| product | object | 상품 목록 항목 — 상품 GET /v1/products 의 list[] 와 같음 |
상품 정렬 (sort)
카탈로그 상품을 읽는 두 API 는 상품 목록과 같은 sort 값을 받습니다.
| 값 | 순서 |
|---|---|
position |
카탈로그에 지정한 순서 |
-created_at / created_at |
최신 등록순 / 오래된순 |
price / -price |
낮은 가격순 / 높은 가격순 |
-sold |
판매량순. 판매 이력이 없는 상품은 카탈로그 지정 순서로 뒤에 붙습니다 |
값이 없거나 목록에 없는 값이면 카탈로그의 sort_type 이 위 값 중 하나일 때 그것을, 아니면 position 을 씁니다. 같은 순위끼리는 최신 등록 상품이 먼저입니다.
GET /v1/catalogs
전시 중인 카탈로그 목록을 position 순으로 조회합니다. 상품은 포함하지 않습니다. 페이지네이션 없이 전체를 돌려줍니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:catalog_list - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
파라미터가 없습니다.
응답
200 OK
{
"list": [
{
"catalog_id": "66f5a0e1b2c3d4e5f6000101",
"project_id": "66a0...",
"seller_id": "65f0...",
"name": "가을 신상",
"description": "이번 시즌 추천",
"cover": "https://.../cover.jpg",
"type": "product",
"status_view": true,
"position": 0,
"sort_type": "position",
"view_type_pc": "image",
"view_type_mobile": "image",
"product_count": 8,
"metadata": null,
"cover_mobile": null,
"link_type": 0,
"link_url": null,
"started_at": null,
"ended_at": null,
"created_at": "2026-09-01T10:00:00+09:00",
"updated_at": "2026-09-10T10:00:00+09:00"
}
]
}json| 필드 | 타입 | 설명 |
|---|---|---|
| list | array | 카탈로그 객체 배열. 개수 필드는 없습니다 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 442 | MALL_INACTIVE |
쇼핑몰이 비활성 상태 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-14 전시하지 않는 카탈로그를 목록에서 뺌
- 2026-09-23 문서 최초 작성
POST /v1/catalogs
카탈로그를 만듭니다. 새 카탈로그는 맨 뒤 순서에 놓입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:catalog_create - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | name | string | O | 이름 | |
| body | description | string | 설명 | ||
| body | cover | string | 커버 이미지 URL | ||
| body | status_view | boolean | false | 전시 여부. JSON true 일 때만 전시합니다. 보내지 않거나 문자열 "true" 로 보내면 전시하지 않는 카탈로그로 만들어집니다 |
응답
200 OK
{
"id": "66f5a0e1b2c3d4e5f6000101"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| id | string | 만든 카탈로그 ID |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | CATALOG_NAME_REQUIRED |
name 이 없거나 비어 있음 |
변경 이력
- 2026-09-23 문서 최초 작성
GET /v1/catalogs/:id
전시 중인 카탈로그 하나와 그 안의 공개 상품 한 페이지를 조회합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:catalog_detail - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 카탈로그 ID | |
| query | page | integer | 1 | 페이지네이션 규칙 | |
| query | limit | integer | 20 | 1~100 | |
| query | sort | string | 카탈로그 기본 정렬 | 위 상품 정렬 |
응답
200 OK — 카탈로그 객체에 상품 페이지 필드가 더해집니다. 이 API 는 list/count 대신 아래 키를 씁니다.
{
"catalog_id": "66f5a0e1b2c3d4e5f6000101",
"name": "가을 신상",
"status_view": true,
"product_count": 8,
"products": [
{
"_id": "66f5b0...",
"product_id": "66f1c2a9e1b2c3d4e5f60789",
"catalog_id": "66f5a0e1b2c3d4e5f6000101",
"position": 0,
"product": { "product_id": "66f1c2a9e1b2c3d4e5f60789", "name": "드립백 커피 10개입" }
}
],
"total_count": 6,
"page": 1,
"per": 20,
"has_more": false
}json| 필드 | 타입 | 설명 |
|---|---|---|
| products | array | 카탈로그 상품 항목 (공개 상품만) |
| total_count | integer | 이 카탈로그의 공개 상품 수. product_count 보다 작을 수 있습니다 |
| page | integer | 실제로 적용한 page |
| per | integer | 실제로 적용한 limit |
| has_more | boolean | 다음 페이지가 있는지 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | CATALOG_NOT_FOUND |
없는 ID·잘못된 형식·전시하지 않는 카탈로그·다른 프로젝트 카탈로그 |
| 442 | MALL_INACTIVE |
쇼핑몰이 비활성 상태 |
변경 이력
- 2026-09-14 전시하지 않는 카탈로그·다른 프로젝트 카탈로그는 404, 상품은 공개 상품만 페이지 단위로 돌려줌(이전에는 숨김 상품 포함 첫 24개)
- 2026-09-23 문서 최초 작성
PUT /v1/catalogs/:id
카탈로그를 수정합니다. PATCH 도 같습니다. 전시하지 않는 카탈로그도 수정할 수 있습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:catalog_update - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 카탈로그 ID | |
| body | name | string | O | 이름 | |
| body | description | string | 설명 | ||
| body | cover | string | 커버 이미지 URL | ||
| body | status_view | boolean | 전시 여부 |
네 필드를 모두 보내세요. 보내지 않은 필드는 기존 값을 유지하지 않고 빈 값(null)으로 저장됩니다. 현재 값은 관리자 화면 또는 전시 중이라면 GET /v1/catalogs/:id 로 확인합니다.
응답
200 OK — 본문에 의미 있는 값이 없습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | CATALOG_NOT_FOUND |
없는 ID 또는 다른 프로젝트의 카탈로그(같은 판매자 포함) |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 판매자 기준 → 인증된 프로젝트 기준으로 카탈로그를 찾음 — 같은 판매자의 다른 프로젝트 카탈로그도 404
DELETE /v1/catalogs/:id
카탈로그를 삭제합니다. 카탈로그–상품 연결도 함께 지워지고, 상품 자체는 남습니다. 되돌릴 수 없습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:catalog_delete - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 카탈로그 ID |
응답
200 OK — 본문에 의미 있는 값이 없습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | CATALOG_NOT_FOUND |
없는 ID 또는 다른 프로젝트의 카탈로그(같은 판매자 포함) |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 판매자 기준 → 인증된 프로젝트 기준으로 카탈로그를 찾음 — 같은 판매자의 다른 프로젝트 카탈로그도 404
PUT /v1/catalogs/reorder
카탈로그 순서를 바꿉니다. 보낸 배열의 순서대로 position 이 0, 1, 2… 로 매겨집니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:catalog_reorder - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | ids | string[] | O | 원하는 순서대로 나열한 카탈로그 ID |
{ "ids": ["66f5a0...0103", "66f5a0...0101", "66f5a0...0102"] }json배열에 없는 카탈로그의 순서는 바뀌지 않습니다. 없는 ID·다른 프로젝트의 ID 는 오류 없이 건너뛰지만 자리 번호는 차지합니다. 모든 카탈로그 ID 를 한 번에 보내는 것을 권장합니다.
응답
200 OK — 본문에 의미 있는 값이 없습니다.
오류
공통 오류(인증·scope·방화벽)만 있습니다 — 오류.
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 다른 프로젝트 카탈로그 ID 는 건너뜀(같은 판매자 포함)
GET /v1/catalogs/:id/products
전시 중인 카탈로그의 공개 상품을 한 페이지씩 조회합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:catalog_products - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 카탈로그 ID | |
| query | page | integer | 1 | 페이지네이션 규칙 | |
| query | limit | integer | 20 | 1~100 | |
| query | sort | string | 카탈로그 기본 정렬 | 위 상품 정렬 |
응답
200 OK
{
"list": [
{
"_id": "66f5b0...",
"product_id": "66f1c2a9e1b2c3d4e5f60789",
"catalog_id": "66f5a0e1b2c3d4e5f6000101",
"position": 0,
"product": { "product_id": "66f1c2a9e1b2c3d4e5f60789", "name": "드립백 커피 10개입" }
}
],
"count": 6,
"page": 1,
"limit": 20
}json| 필드 | 타입 | 설명 |
|---|---|---|
| list | array | 카탈로그 상품 항목 (공개 상품만) |
| count | integer | 이 카탈로그의 공개 상품 수 |
| page, limit | integer | 실제로 적용한 값 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | CATALOG_NOT_FOUND |
없는 ID·잘못된 형식·전시하지 않는 카탈로그·다른 프로젝트 카탈로그 |
| 442 | MALL_INACTIVE |
쇼핑몰이 비활성 상태 |
변경 이력
- 2026-09-14 공개 상품만 페이지 단위로 돌려주고
page·limit·sort지원 - 2026-09-23 문서 최초 작성
POST /v1/catalogs/:id/add_products
카탈로그에 상품을 여러 개 넣습니다. 이미 들어 있는 상품은 건너뛰고, 새 상품은 보낸 순서대로 맨 뒤에 붙습니다. 전시하지 않는 카탈로그에도 넣을 수 있습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:catalog_add_products - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 카탈로그 ID | |
| body | product_ids | string[] | O | 넣을 상품 ID |
{ "product_ids": ["66f1c2a9e1b2c3d4e5f60789", "66f1c2a9e1b2c3d4e5f60790"] }json이 프로젝트의 상품만 넣습니다. 없는 상품 ID·다른 프로젝트의 상품 ID 는 넣지 않고 응답 rejected_product_ids 로 돌려줍니다(요청은 성공). 공개되지 않은 상품은 연결은 되지만 조회 API 에는 나오지 않습니다.
응답
200 OK
{
"added": 1,
"skipped": 1,
"rejected_product_ids": []
}json| 필드 | 타입 | 설명 |
|---|---|---|
| added | integer | 새로 넣은 상품 수 |
| skipped | integer | 이미 들어 있어 건너뛴 상품 수 |
| rejected_product_ids | string[] | 이 프로젝트의 상품이 아니거나 없는 상품이라 넣지 않은 ID |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | CATALOG_NOT_FOUND |
없는 ID 또는 다른 프로젝트의 카탈로그(같은 판매자 포함) |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 인증된 프로젝트의 카탈로그만 대상, 다른 프로젝트·없는 상품 ID 는 넣지 않고
rejected_product_ids로 응답
DELETE /v1/catalogs/:id/remove_product/:product_id
카탈로그에서 상품 하나를 뺍니다. 상품 자체는 지워지지 않습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:catalog_remove_product - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 카탈로그 ID | |
| path | product_id | string | O | 뺄 상품 ID |
응답
200 OK — 본문에 의미 있는 값이 없습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | CATALOG_NOT_FOUND |
없는 ID 또는 다른 프로젝트의 카탈로그(같은 판매자 포함) |
| 404 | CATALOG_PRODUCT_NOT_FOUND |
이 카탈로그에 들어 있지 않은 상품 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 판매자 기준 → 인증된 프로젝트 기준으로 카탈로그를 찾음 — 같은 판매자의 다른 프로젝트 카탈로그도 404
PUT /v1/catalogs/:id/reorder_products
카탈로그 안 상품 순서를 바꿉니다. 보낸 배열의 순서대로 position 이 0, 1, 2… 로 매겨집니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:catalog_reorder_products - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 카탈로그 ID | |
| body | product_ids | string[] | O | 원하는 순서대로 나열한 상품 ID |
카탈로그에 없는 상품 ID 는 건너뛰지만 자리 번호는 차지합니다. 배열에 없는 상품의 순서는 그대로라 번호가 겹칠 수 있으니, 카탈로그의 상품 ID 를 모두 보내세요.
응답
200 OK — 본문에 의미 있는 값이 없습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | CATALOG_NOT_FOUND |
없는 ID 또는 다른 프로젝트의 카탈로그(같은 판매자 포함) |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 판매자 기준 → 인증된 프로젝트 기준으로 카탈로그를 찾음 — 같은 판매자의 다른 프로젝트 카탈로그도 404
