상품 기본 정보
🅐 상품 기본 정보
► 상품 상세 조회하기 해당 상품번호 {productNo}에 대한 상세 정보를 조회합니다.
해당 상품 정보에 대한 상품 이미지 URL, 상품 기본정보, 상세 정보, 배송/반품/교환, 후기, 문의, 관련상품 등의 정보를 조회할 수 있습니다.
엔드 포인트 URL에 따라 본 화면을 구성하는 여러가지 데이터를 불러오며, 영역별로 API를 소개합니다.
🅑 옵션 정보
쇼핑몰에서 판매할 상품을 등록할 때, '상품 (예시 : 오로라 수딩 세럼)' 에 대한 '옵션 (예시 : 30ml, 50ml, 100ml)'을 설정할 수 있습니다.
아래 어드민 경로에서 2가지 형태의 옵션 기능을 제공합니다.
◼︎ 옵션 유형
ⓐ 선택형 옵션 (조합형)
쇼핑몰 고객이 선택하는 형태의 옵션입니다. shop by 에서는 여러 옵션을 조합하는 '선택형(조합형) 옵션' 형태를 제공하고 있습니다.
노출 방식에 따라 '분리형'과 '일체형' 2가지 유형으로 구분됩니다.
분리형 옵션 multiLevelOptions : 각 옵션 별로 계층(단계)를 구분하여 셀렉트 박스를 제공합니다.
일체형 옵션 flatOptions : 쇼핑몰 고객이 선택할 수 있는 옵션을 모두 리스트업 하여 셀렉트 박스를 제공합니다.
ⓑ 텍스트 옵션
쇼핑몰 고객이 직접 옵션값을 입력하는 형태입니다. 어드민에서 '매칭타입'에 따라 상품별 / 옵션별로 텍스트 옵션을 노출할 수 있습니다.
상품별 : 쇼핑몰 고객이 상품 당 1개의 텍스트 옵션만 입력할 수 있습니다.
옵션별 : 각 옵션별로 개별 텍스트 옵션을 입력할 수 있습니다.
수량별 : 설정한 수량만큼 텍스트 옵션을 입력할 수 있습니다.
◼︎ 옵션 조회 API
상품의 옵션 단위로 주문이 진행되므로 옵션이 없는 상품은 없습니다. 어드민에서 옵션 없는 상품으로 등록한 경우, 내부적으로는 자동으로 하나의 옵션이 생성됩니다.
따라서 쇼핑몰 고객이 실제로 상품을 구매하기 위해서는 본 화면에서 GET /products/{productNo}와 함께 아래 옵션 조회 API를 반드시 호출해야 합니다.
GET /products/{productNo}/options
► 상품 옵션 조회하기 해당 상품번호(productNo)에 대한 옵션 정보를 조회합니다.
◼︎ TYPE
선택형 옵션 및 텍스트 옵션을 선택할 수 있습니다.
만약 어드민에서 옵션 사용 여부를 '사용 안 함'으로 설정한 경우 응답 값이 Default로 내려옵니다.
◼︎ flatOptions
일체형 옵션 (각 옵션들의 조합으로 생성되는 모든 옵션을 쭉 나열한 데이터)
selectType에서 flat 선택 시 flatLevelOptions 값을 활용
◼︎ multuLevelOptions
분리형 옵션 (계층 구조로 구성된 옵션 데이터)
selectType 에서 multi 선택 시 multiLevelOptions 값을 활용
◼︎ input
inputLabel 텍스트 옵션 내 입력 문구를 의미합니다.
ex) 최근에 생산된 상품으로 보내주세요.
🅒 쿠폰 다운받기
쇼핑몰 고객이 현재 다운로드 받을 수 있는 쿠폰 리스트와 쿠폰을 다운받을 수 있는 팝업을 노출합니다. 상품 기본 정보에서 [쿠폰받기] 버튼 클릭 시 쿠폰 다운로드 팝업을 출력합니다.
GET /coupons/products/issuable/coupons
► 상품번호 리스트별 발급 가능한 쿠폰 조회하기
본 상품과 추가상품에서 발급 가능한 모든 쿠폰을 조회합니다.
쿠폰 다운받기 팝업에서, [쿠폰받기] / [쿠폰 한번에 받기] 버튼 클릭 시 로그인 여부를 체크 후 쿠폰을 다운로드 합니다.
[쿠폰받기] 버튼 클릭 시 개별로 쿠폰을 다운로드합니다.
POST /coupons/{couponNo}/download
► 쿠폰 발급하기
선택한 쿠폰번호에 해당하는 다운로드 쿠폰을 발급 받습니다.
[쿠폰 한번에 받기] 버튼 클릭 시 상품번호 리스트 별로 발급 가능한 모든 쿠폰을 다운로드 합니다.
POST /coupons/products/download
► 상품번호 리스트별 발급 가능한 쿠폰을 다운로드 하기 본 상품과 추가상품에서 다운로드 받을 수 있는 모든 쿠폰을 발급합니다.
상품번호(productNo) 리스트로 해당 상품에서 다운받을 수 있는 모든 쿠폰을 발급합니다. 추가상품이 설정된 경우, 본 상품과 추가상품의 상품번호 리스트를 활용합니다.
아래 어드민 경로의 설정에 따라 정보가 노출됩니다.
ⓐ 출력되는 쿠폰
발급 유형 : 다운로드 발급
발급 상태 : 발급중
해당 상품이 대상 상품인 쿠폰
즉시 할인가를 기준으로 할인되는 금액이 높은 순으로 쿠폰을 정렬
할인 금액이 동일하다면 주문 쿠폰이 상품 쿠폰보다 상단에 출력
할인되는 금액 및 혜택 구분이 모두 동일하다면 쿠폰 등록일 기준 최신순으로 출력
ⓑ 혜택
정률로 설정 시 % 출력, 정액으로 설정 시 금액 출력
쿠폰 유형 (주문적용 쿠폰 → 주문 할인 / 상품적용 쿠폰 → 상품 할인)
최대 할인금액 (할인 금액을 정률로 설정한 경우에만 노출)
최소 기준금액 (최소 금액을 설정하는 경우 노출)
ⓒ 다운로드 버튼
발급 시 (회원 별 발급 수량 제한이 있을 경우) '발급 완료' 표기
발급 불가 쿠폰의 경우 안내 문구 출력 (발급 대상 회원 등급일 경우 / 발급 불가한 시간, 요일인 경우 / 쿠폰의 일별 총 발급 수량 소진 시)
🅓 좋아요 버튼
해당 상품을 좋아요 상품 리스트에 추가/삭제 할 수 있습니다. 좋아요 기능은 쇼핑몰 회원(member)의 경우에만 사용 가능하므로, 버튼 클릭 시 로그인 여부를 확인해야 합니다.
비회원(guest)
비회원의 경우 좋아요 기능을 지원하지 않습니다.
좋아요 버튼 클릭 시 로그인 여부를 확인하여, 미로그인(비회원)시 서비스이용불가 안내창 노출 후 로그인 페이지로 현재창 이동해야 합니다.
회원(member)
로그인한 상태에서 좋아요 버튼 클릭 시, 아래 POST /profile/like-products를 호출합니다.
해당 API로 좋아요가 적용된 상품은 마이페이지_쇼핑정보 내 '좋아요' 리스트에 추가됩니다.
▶ 회원이 상품을 좋아한다고 추가/삭제하기 회원이 좋아요한 상품을 목록에 추가하거나 삭제합니다
🅔 장바구니 버튼
선택한 상품을 옵션 단위로 장바구니에 추가하는 기능입니다. 장바구니(cart) 버튼 클릭 시, 상품 옵션 선택 여부를 확인 후 장바구니 화면으로 이동합니다.
장바구니 버튼 기능은 쇼핑몰 회원 여부와 상관없이 제공합니다. 단, 회원인 경우에만 API를 호출하며 비회원인 경우 API 호출이 아닌 localStorage에 자체적으로 저장합니다. 추가상품 구매 조건이 추가상품 중 1개 이상 필수 혹은 추가상품별 필수 지정일 경우, 필수 추가상품을 선택하지 않거나 추가상품 구매 제한 수량을 벗어나면 장바구니 담기가 불가능합니다.
회원(member)
로그인한 상태에서 장바구니 담기 버튼 클릭 시, 아래 POST /cart를 호출하여 선택한 상품의 옵션이 장바구니에 추가됩니다.
▶ 장바구니 등록하기 로그인 회원의 상품 구매 수량과 옵션을 장바구 니에 등록하며, 추가상품을 함께 장바구니에 등록할 경우 본 상품 번호를 함께 전송합니다. 누락 시, 서버에서 일반상품 주문으로 처리해 필수 구성을 판정할 수 없습니다.
비회원(guest)
비회원인 경우에도 장바구니 담기 버튼을 제공합니다.
단, API 호출이 아닌 localStorage 내 비회원 장바구니 데이터를 자체적으로 관리해야 합니다.
localStorage에 비회원 장바구니 데이터 저장 시, POST /cart의 request body와 동일한 데이터 형식으로 저장해야 합니다. 이후 상품 상세화면 혹은 장바구니 화면에서 주문서 호출 시 request 형식을 통일하기 위한 목적입니다.
① 검증 주체 — 이 분기가 빠지면 비회원이 필수 추가상품없이 담을 수 있습니다.
회원(member)
서버
담기가 POST /cart 로 서버를 타므로 서버가 판정해
오류를 내려줍니다
비회원(guest)
스킨(프론트)
비회원 장바구니는 API 호출 없이 localStorage 에 저장하므로 담기 시점에 서버가 검증할 지점이 없습니다
② 검증 규칙과 안내 문구 — 미선택 → 최소 수량 → 최대 수량 순으로 확인하고, 처음 발견된 위반 하나만 안내합니다.
공통
필수 추가상품 미선택
필수 추가상품을 선택해주세요.
추가상품 중 1개 이상 필수
합산 수량 < 최소
필수 추가상품을 모두 합쳐 최소 {최소수량 × N}개이상 구매해야 하는 상품이 있습니다.
추가상품 중 1개 이상 필수
합산 수량 > 최대
필수 추가상품을 모두 합쳐 최대
{최대수량 × N}개까지 구매 가능한 상품이 있습니다.
추가상품별 필수 지정
상품별 수량 < 최소
{추가상품명}는 최소 {최소수량 × N}개 이상 구매해야 하는 상품입니다.
추가상품별 필수 지정
상품별 수량 > 최대
{추가상품명}는 최대 {최대수량 × N}개까지 구매 가능한 상품입니다.
🅕 구매하기 버튼
버튼 클릭 시 우선 로그인 여부를 확인한 뒤 POST /order-sheets API로 주문서를 생성합니다. 만약 미로그인(비회원)일 경우에는 해당 API로 비회원 주문을 진행합니다.
► 주문서 생성 요청 선택한 상품의 옵션에 대한 주문서를 생성합니다.
주문서를 생성하는 API로 주문서 화면으로 이동하기 전 단계에서 호출해야 합니다. 해당 API에서 응답 값으로 획득한 주문서 번호 orderSheetNo를 주문서 화면으로 전달합니다. 비회원 주문인 경우 accessToken을 null로 보냅니다. 추가상품 구매 조건이 추가상품 중 1개 이상 필수 혹은 추가상품별 필수 지정일 경우, 필수 추가상품을 선택하지 않거나 추가상품 구매 제한 수량을 벗어나면 구매불가 상품이 되어 바로구매가 불가능합니다. 필수 추가상품이 품절이라 본 상품을 단독으로 살 수 없을 때에도 구매불가 상품이 되어 바로구매가 불가능합니다. 필수 추가상품 검증과 요청 형식(본 상품 번호 전송)은 상품상세 > 상품 기본 정보 의 🅔 장바구니 버튼 · 🅕 구매하기 버튼 과 동일합니다.
Last updated