카탈로그

카탈로그는 기획전·컬렉션처럼 상품을 골라 묶은 전시 단위입니다. 카탈로그 자체를 만들고 순서를 정하며, 카탈로그에 상품을 넣고 빼고 순서를 바꿉니다.

  • 조회​(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

함께 보기