진열 | Bootpay 커머스 매뉴얼

어떤 상품을 어디에 얼마나 보여줄지 한 자리에서 편성해요.

v1 API 상세: 카탈로그

상품을 묶어 쇼핑몰 화면에 내보내는 단위예요. 「이번 주 신상」·「베스트」 같은 편성이 여기서 만들어져요.

카테고리가 상품의 분류라면, 진열은 상품의 편성이에요. 한 상품이 여러 진열에 동시에 들어갈 수 있고, 진열 안에서 순서를 직접 정할 수 있어요.

화면 용어는 「진열」이지만 엔드포인트는 /v1/catalogs 예요. 상품 진열 상태의 status_display 와도 다른 개념이에요 — 그건 상품 한 건의 노출 스위치고, 진열은 묶음이에요.

진열 목록

GEThttps://api.bootapi.com/v1/catalogsBasic Auth

필요 권한: 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	선택

진열 상세

GEThttps://api.bootapi.com/v1/catalogs/:idBasic Auth

필요 권한: 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 와 다를 수 있어요.

진열 생성

POSThttps://api.bootapi.com/v1/catalogsBasic Auth

필요 권한: 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 로 진열 상세를 한 번 더 불러요.

진열 수정

PUThttps://api.bootapi.com/v1/catalogs/:idBasic Auth

필요 권한: user:catalog_update

생성과 같은 파라미터를 받아요. 성공하면 본문에 의미 있는 값이 없어요.

지금은 name·description·cover·status_view 중 빼고 보낸 값이 비워져요. status_view 가 비면 전시가 꺼져요.

수정할 때는 진열 상세로 현재 값을 읽어 네 값을 모두 함께 보내요.

진열 순서 변경

PUThttps://api.bootapi.com/v1/catalogs/reorderBasic Auth

필요 권한: 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"] }'bash

reorder 는 collection 경로예요. /v1/catalogs/reorder 를 진열 하나의 ID 로 착각하지 않도록 주의해요.

성공하면 본문은 null 이에요.

진열 삭제

DELETEhttps://api.bootapi.com/v1/catalogs/:idBasic Auth

필요 권한: user:catalog_delete

진열과 함께 진열-상품 연결이 지워져요. 상품 자체는 남아요. 성공하면 본문은 null 이에요.

진열 안 상품 목록

GEThttps://api.bootapi.com/v1/catalogs/:id/productsBasic Auth

필요 권한: user:catalog_products

진열 상세와 같이 전시 중인 진열의 공개 상품을 페이지 단위로 돌려줘요. page(기본 1), limit(기본 20, 최대 100), sort 를 받으며 응답은 { list, count, page, limit } 예요. count 는 공개 상품 수예요.

상품 추가

POSThttps://api.bootapi.com/v1/catalogs/:id/add_productsBasic Auth

필요 권한: user:catalog_add_products

파라미터	타입	필수	설명
`product_ids`	Array	필수	추가할 상품 ID 배열

중복은 서버가 걸러요. 같은 배열을 두 번 보내도 상품이 두 번 들어가지 않아요.

{ "added": 2, "skipped": 1, "rejected_product_ids": [] }json

added 는 새로 넣은 수, skipped 는 이미 들어 있어서 건너뛴 수예요. 다른 프로젝트나 없는 상품 ID 는 넣지 않고 rejected_product_ids 에 돌려줘요.

상품 제거

DELETEhttps://api.bootapi.com/v1/catalogs/:id/remove_product/:product_idBasic Auth

필요 권한: user:catalog_remove_product

진열에서 한 건만 빼요. 상품은 삭제되지 않아요. 성공하면 본문은 null 이에요.

진열 안 상품 순서 변경

PUThttps://api.bootapi.com/v1/catalogs/:id/reorder_productsBasic Auth

필요 권한: user:catalog_reorder_products

파라미터	타입	필수	설명
`product_ids`	Array	필수	상품 ID 배열. 배열 순서가 진열 안 노출 순서가 돼요

성공하면 본문은 null 이에요.

에러 코드

인증·권한 관련 에러는 커머스 API 인증 에러를 참고해요.

코드	메시지	대처 방법
`CATALOG_NOT_FOUND`	진열을 찾을 수 없어요	`:id` 가 이 프로젝트의 진열인지 확인해요. 조회에서는 전시 중이어야 해요
`CATALOG_NAME_REQUIRED`	카탈로그 이름은 필수예요.	진열 생성에 `name` 을 넣어요
`CATALOG_PRODUCT_NOT_FOUND`	카탈로그-상품 연결을 찾을 수 없어요.	상품 제거의 `:product_id` 가 이 진열에 들어 있는지 확인해요

함께 보기

카테고리 — 상품의 분류 축
상품 목록 — 진열에 넣을 product_id 를 찾아요