> For the complete documentation index, see [llms.txt](https://tech.x2bee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.x2bee.com/api-guide/store-front/goods/undefined-1.md).

# 상품상세

등록된 상품번호(goodsNo)를 기준으로 Front화면에 상품상세화면을 구성하기 위한 상품 상세 API에 대한 가이드입니다.

**상품 정보 제공**

* 상품의 기본 단위로, 색상/사이즈 등의 하위 단품정보를 포함.
* 상품가격, 재고, 판매상태, 협력사, 브랜드, 상품평, 상품Q\&A, 상품배송정보, 할인정보(프로모션 포함) 등 다양한 정보를 제공.

**캐싱 기능 적용**

* 외부컨텐츠(이미지, 상품상세HTML)에 대한 캐싱을 적용하여 데이터 트래픽을 최소화하고 고객 경험을 최우선으로 설계.

***

## 주요 기능

* **업체정보 관리**: 상품 공급업체(파트너사) 정보 추가 제공.
* **표준카테고리 정보 제공**: 상품의 관리를 위한 표준분류체계 제공하며, 해당 표준카테고리별 대표 전시카테고리로 이동 가능.
* **19세 미만 회원 필터링**: 법령에 맞춰 19세 미만 회원에게 특정 상품(유해 매체 및 유해 약물) 노출.
* **가격정보**
  * 공급가, 정상가, 판매가, 행사가 등 다양한 가격정보 제공.
  * 단품별 다양한 옵션 구성 가능하며, 단품별 추가금액 정보도 투명하게 제공.
* **상품상태 제공**: 상품 및 단품의 판매상태에 따라 품절, 임시품절, 판매종료, 예약 등의 판매상태 옵션 제공.
* **재고 관리**: 재고를 효율적으로 관리하도록 구성하며, 1회 주문 가능 수량, 재고수량 표시, 안전재고 확보 등의 기능 제공.
* **배송 정보 제공**: 배송유형과 배송비/반품비 정책이 적용되어 배송에 대한 다양한 정보 제공.
* **이미지 정보 제공**: 대표 이미지, 부가 이미지, 섬네일 이미지 등 다양한 이미지 정보 제공하며, 캐싱을 통해 고객의 트래픽을 최소화하도록 개발.
* **연관상품 등록**: 본 상품과 유사 또는 연결점이 있는 상품에 대해 연관상품으로 등록하여 노출되도록 개발.
* **부가서비스 제공**: 사은품 및 증정품 정보 제공하여, 상품 구매에 대한 부가 서비스 제공.
* **외부채널 할인 정보 제공**: 외부채널을 통한 상품상세 유입시, 해당 채널 코드별 추가 할인에 대한 정보 제공.

## 프로세스 정의 

<figure><img src="https://2999922013-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXTxKSWMmuxEkop1pvuwe%2Fuploads%2FyEIOUFgb1vAUi1sySiqH%2F183107758.jpg?alt=media&amp;token=d03ab8ec-2c6b-49d4-8b28-8c350b75400c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2999922013-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXTxKSWMmuxEkop1pvuwe%2Fuploads%2FPdb3tDlc4q2fN2evIOzE%2F182419608.jpg?alt=media&amp;token=a58b435d-597e-44f8-ab0c-e3eb0ad01564" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

### 상품 상세정보 조회

* 상품상세정보를 조회해서 노출
* 상품기본정보, 컨텐츠정보, 연관상품, 리뷰간략정보, 상품아이콘정보, 단품기본정보를 조회하여 노출
  {% endstep %}

{% step %}

### 상품별 최대혜택가 조회

* 상품가격 노출시 최대혜택가 반영하여 노출
* 최대혜택가정보 API는 프로모션에서 정보를 제공
  {% endstep %}

{% step %}

### 옵션정보 조회 (옵션팝업)

* 단품의 옵션정보를 SELECT BOX형태로 노출
* 재고관리여부, 구매수량제한, 최소/최대 구매수량 정보로 수량변경시 validation 체크
  {% endstep %}

{% step %}

### 단품별 재고증차감

* 주문, 교환, 반품에 의해 재고 증차가감을 위한 API
* 주문에서 상품 단품의 주문에 의해 증차감을 요청
* 재고관리하는 상품만 증차감 처리
  {% endstep %}

{% step %}

### 증정품 정보조회

* 주문에서 해당 상품의 증정품을 보여주기 위해 요청
* 증정품 정보는 증정품명만 TEXT로 제공
  {% endstep %}

{% step %}

### 전시상품정보 (전시상품요약)조회

* 목록에서 사용 할 상품정보를 요약한 정보이며, 목록에서 상품정보를 노출하기 위해 상품의 정보보를 조회요청
* 목록에 노출 할 상품들의 조회요청으로 다건의 상품조회기능 제공
* 상품이미지: 상품의 필수값인 대표이미지를 제공
  {% endstep %}

{% step %}

### 상품별 단품정보 조회

* 상품의 단품들 정보를 조회
* 상품기본정보, 대표전시카테고리정보, 단품명, 재고정보, 가격정보를 제공
  {% endstep %}

{% step %}

### 상품별 단품정보 조회(주문전용)

* 다건의 상품정보를 조회
* 주문에서 교환시 구매가능 수량, 판매가격, 단품추가금이 동일한 다른 단품을 선택 할 때 사용
* 단품재고가 요청수량보다 많은 경우의 단품만 조회
  {% endstep %}

{% step %}

### 대체가능 상품단품정보 조회(장바구니)

* 다건의 상품정보를 조회
* 요청받은 상품,단품외의 단품중에 판매가격, 단품추가금이 동일한 다른 단품을 조회
* 단품추가금이 동일한 다른 단품정보 조회
* 단품수량이 요청한 수량보다 많은 단품만 조회
  {% endstep %}

{% step %}

### 상품별 단품정보 조회(장바구니전용)

* 장바구니에서 단품별 상세정보를 보여주기 위해 요청
* 다건으로 받은 단품번호 기준으로 단품정보를 조회
  {% endstep %}

{% step %}

### 상품별 결제가능수단 조회

* 다건의 상품의 결제수단을 조회
* 결제수단의 사용여부가 'Y'인 결제수단만 조회
* 주문에서 상품의 결제수단목록을 보여주기 위해 조회
  {% endstep %}

{% step %}

### 단품별 즉시할인가 조회

* 즉시할인가정보 API는 프로모션에서 정보 제공
* 상품목록에서 즉시할인가를 보여주기 위해 요청
  {% endstep %}
  {% endstepper %}

## API 기능 목록

<table><thead><tr><th width="107.888916015625">API</th><th width="357.77783203125">설명</th><th width="93.5555419921875">Server</th><th width="86.888916015625">메소드</th><th>비고</th></tr></thead><tbody><tr><td>대체가능 상품단품<br>정보 조회(장바구니)</td><td>•단건의 상품 조회 시 호출하는 API입니다. <br>•요청 받은 상품에 대하여 요청한 단품외의 <br>단품 중에 상품+단품+수량 으로 대체가능(판매가격+단품추가금 동일한 다른 단품)한 단품<br>목록을 조회합니다.<br>• 상품가격은 동일하므로 단품추가금만 <br>확인하여 조회합니다. <br>• 단품재고가 요청수량보다 많은 경우만 <br>조회합니다. <br>• 쿠키에 저장된 언어코드를 사용하여 <br>조회합니다.</td><td>Goods</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=getOrderItmInfo">🔗API 확인하기></a></td></tr><tr><td>단품별 <br>재고증차감</td><td>• 차감한 단품수량이 재고수량보다 클 경우<br>(마이너스 재고), 에러를 리턴합니다. <br>• 증가한 단품수량이 안전재고수량보다 클 시단품판매상태코드 판매 중으로 변경합니다.</td><td>Goods</td><td>PUT</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=setStockUpdate">🔗API 확인하기></a></td></tr><tr><td>옵션정보 조회 <br>(옵션팝업)</td><td>• 상품에 대한 옵션목록을 조회하기 위한 API 입니다. <br>• 묶음상품을 조회하는 경우 해당 묶음상품의 대표 상품의 옵션목록을 조회합니다. <br>• 상품의 전시여부가 Y이고, 단품의 판매상태가 판매중/품절인 단품이 속한 옵션들을 <br>조회합니다. <br>• 단품목록이 없는 단일상품은 조회에서 <br>제외합니다. <br>• 리프옵션에 해당하는 단품의 기본정보를 <br>포함합니다. <br>• 쿠키에 저장된 사이트번호, 몰번호를 <br>사용하여 조회합니다. <br>• 미리보기의 경우 request의 미리보기 언어<br>코드를 사용하여 조회하고, 그외의 경우는 쿠키에 저장된 언어코드를 사용하여 조회합니다.</td><td>Goods</td><td>GET</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=seltProductOptionInfo">🔗API 확인하기></a></td></tr><tr><td>상품별 <br>단품정보 조회<br>(장바구니전용)</td><td>• 장바구니에서 단품별 상세정보를 조회하기 위해 호출합니다. <br>• 리스트로 받은 단품번호 기준으로 단품의 <br>상세정보를 조회합니다. <br>• 쿠키에 저장된 언어코드, 몰번호를 사용하여 조회합니다.</td><td>Goods</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=seltOrderItmInfo">🔗API 확인하기></a></td></tr><tr><td>상품별 <br>단품정보 조회<br>(주문전용)</td><td>• 다건의 상품 조회 시 호출합니다. <br>• 요청 받은 각 상품에 대하여 요청한 단품외의 단품 중에 상품+단품+수량 으로 대체가능(판매가격+단품추가금동일한 다른 단품)한 <br>상품별로 단품목록을 조회합니다. <br>• 단품재고가 요청수량보다 많은 경우만 <br>조회합니다. <br>• 쿠키에 저장된 언어코드를 사용하여 <br>조회합니다.</td><td>Goods</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=getOrderItmInfos">🔗API 확인하기></a></td></tr><tr><td>상품별<br>단품정보 조회</td><td>• 상품번호에 따라 상품 내 모든 단품의 정보를 조회합니다. <br>• 쿠키에 저장된 언어코드를 사용하여 <br>조회합니다. <br>• 단품명, 재고정보, 가격정보를 조회합니다.</td><td>Goods</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=getProductInfo">🔗API 확인하기></a></td></tr><tr><td>상품별 <br>최대혜택가 조회 <br>(프로모션 제공)</td><td>• 상품의 최대혜택가를 조회하는 API 입니다. <br>• request에 단품번호가 없는 경우는 상품의 <br>단품번호가 가장 빠른 단품을 기준으로 <br>프로모션 최대혜택가를 적용하여 조회합니다. <br>• request에 단품번호가 있는 경우는 상품의 <br>해당 단품번호를 기준으로 프로모션 최대<br>혜택가를 적용하여 조회합니다. <br>• 최대혜택가에 해당하는 프로모션리스트를 <br>조회합니다. <br>• 쿠키에 저장된 사이트번호, 몰번호를 <br>사용하여 조회합니다.<br>• request에 채널번호가 있는 경우 해당 채널<br>번호를 사용하여 조회하고, 그외의 경우는 쿠키에 저장된 채널번호를 사용하여 조회합니다. <br>• 로그인을 한 경우 로그인 사용자 정보가 <br>프로모션 최대혜택가 계산 조건에 적용됩니다.</td><td>Goods</td><td>GET</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=getItemPriceInfo">🔗API 확인하기></a><br>[상품상세 최대혜택가조회]<br>/api/order/v1/marketing/maxDcAmt</td></tr><tr><td>단품별 <br>즉시할인가 조회</td><td>• 단품별 즉시할인가를 조회하는 API 입니다. <br>• 쿠키에 저장된 사이트번호, 몰번호를 <br>사용하여 조회합니다. <br>- 단품에 즉시할인가가 적용된 가격정보를 <br>조회합니다.</td><td>Goods</td><td>GET</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=getImmediateDcInfo">🔗API 확인하기></a><br>[상품별 즉시할인가 조회]<br>/api/order/v1/marketing/goodsDirectDiscountList</td></tr><tr><td>상품별 <br>결제가능<br>수단 조회</td><td>• 다건의 상품별 각각의 결제수단을 <br>조회합니다. <br>• 쿠키에 저장된 언어코드를 사용하여 <br>조회합니다. <br>• 결제수단의 사용여부가 'Y'인 결제수단만 <br>조회합니다.</td><td>Goods</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=seltPayMeanList">🔗API 확인하기></a></td></tr><tr><td>증정품 <br>정보 조회</td><td>• 상품에 해당하는 증정품을 조회합니다. <br>• 1001: request값이 없거나, request값에 상품번호가 없는 경우 발생하는 오류입니다.</td><td>Goods</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=seltPromotionGiftList">🔗API 확인하기></a></td></tr><tr><td>상품 상세정보 조회</td><td>• 상품의 상세페이지에서 상품정보를 상세 <br>조회하기 위한 API 입니다. <br>• 전시여부가 Y이고, 판매상태가 판매중/품절이고, 판매기간에 해당하는 상품을 조회합니다. • 상품의 기본/단품/브랜드/이미지/가격/결제수단/연관상품/묶음상품/배송비정책/프로모션/증정품/리뷰별점통계정보를 조회합니다. <br>• 쿠키에 저장된 언어코드, 사이트번호, <br>몰번호를 사용하여 조회합니다.</td><td>Goods</td><td>GET</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=seltProductDetailInfo">🔗API 확인하기></a></td></tr><tr><td>전시상품<br>정보<br>(전시상품요약)조회</td><td>• 다건의 상품조회가 가능합니다. <br>• 이미지는 상품의 대표이미지를 제공합니다. <br>• 미리보기의 경우 request 미리보기 언어<br>코드를 사용하여 조회하고, 그외는 쿠키에 <br>저장된 언어코드를 사용하여 조회합니다.</td><td>Goods</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=goods&#x26;depth=%EC%83%81%ED%92%88%EC%83%81%EC%84%B8&#x26;path=seltProductSmryInfo">🔗API 확인하기></a></td></tr></tbody></table>

## 용어 정의

<table><thead><tr><th width="136.22216796875">명칭</th><th>설명</th><th data-hidden>비고</th></tr></thead><tbody><tr><td>상품</td><td>• 상거래 채널을 통해 판매의 대상이 되는 모든 재화를 의미합니다. <br>• 상품을 전시하는 기본 단위이며 상품 상세 화면을 구성하는 기본 단위가 됩니다. •상품은 가격을 관리하는 단위입니다.</td><td></td></tr><tr><td>단품</td><td>• 상품 하위의 최소 관리 단위로 상품 재고 및 판매의 최소 단위, 즉 고객이 구입하게 되는 단위입니다. <br>• 고객의 선택 옵션에 따른, 주문 상품 정보를 관리하는 단위입니다. <br>• 재고를 관리하는 단위입니다. (솔루션에서 재고는 ‘웹재고’를 의미합니다.) <br>• 옵션의 조합으로 단품 정보가 생성됩니다. <br>(예) 단품A : 컬러-블랙/사이즈-260 / 단품B : 컬러-블랙/사이즈-250</td><td></td></tr><tr><td>옵션</td><td>• 상품을 베리에이션하는 기본 단위입니다.<br>• ‘컬러’, ‘사이즈’ 등의 항목을 옵션명이라 하며 ‘블랙’, ‘XL’등을 옵션값이라 합니다. • 옵션 유형은 성별, 색상, 크기, 중량, 용량, 지역 등 대부분의 커머스에 사용하는 유형이 존재하며 사이트별 필요시 추가하여 사용할 수 있습니다.</td><td></td></tr><tr><td>일반상품 (구분)</td><td>• 일반적인 배송이 이루어지는 모든 재화 상품을 의미합니다.</td><td></td></tr><tr><td>사은품 (구분)</td><td>• 프로모션이나 이벤트 등을 통해 특정 상품 구매 혹은 특정한 액수 이상 구매 등과 같이 일정한 조건을 충족하는 고객에 한하여, 추가 비용 없이 지급하는 상품을 의미합니다.</td><td></td></tr><tr><td>일반상품</td><td>• 단품에 상품의 옵션을 코드화에서 관리하는 상품을 의미합니다. <br>• 재고 차감은 단품 단위로 이루어 집니다.</td><td></td></tr><tr><td>묶음상품</td><td>• 할인 여부와 상관없이 전시 활용을 위한 묶음 상품을 의미합니다. <br>• 옵션 구성 상품을 일부 선택하여 구매합니다.</td><td></td></tr><tr><td>예약상품</td><td>• 일정 기간 동안 사전 주문하여 배송안내일에 일괄 배송하는 상품을 의미합니다. - 예약상품은 판매단위인 단품 단위로 선택하여 등록합니다. <br>• 예약상품 정보의 전시기간이 상품의 전시기간에 포함되는 경우만 단품 조회 및 선택 가능합니다.</td><td></td></tr></tbody></table>

##