# 상품
## 템플릿 ID로 상품 제약 템플릿 상세 조회
> 템플릿 ID를 이용하여 상품 제약 조건 템플릿의 판매 옵션 상세 정보를 조회합니다.\
> \
> \## 판매 옵션 구조\
> \
> 판매 옵션은 두 가지로 분류됩니다.\
> \
> \- \*\*selectOneSaleOptions (택1 그룹)\*\*: \`groupKey\`로 묶인 옵션 그룹입니다. 같은 그룹 내에서 하나만 선택해야 합니다.\
> \- \*\*salesOptions (일반 옵션)\*\*: 개별 판매 옵션입니다.
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"GetProductConstraintTemplateByIdFepResponse":{"required":["salesOptions","selectOneSaleOptions"],"type":"object","properties":{"selectOneSaleOptions":{"type":"array","description":"택1 판매 옵션 그룹 목록","items":{"$ref":"#/components/schemas/SelectOneSaleOptionFepResponse"}},"salesOptions":{"type":"array","description":"판매 옵션 목록","items":{"$ref":"#/components/schemas/SalesOptionFepResponse"}}},"description":"템플릿 ID 기반 상품 제약 조건 템플릿 상세 응답"},"SelectOneSaleOptionFepResponse":{"required":["groupKey","options"],"type":"object","properties":{"groupKey":{"type":"string","description":"그룹 키"},"options":{"type":"array","description":"그룹 내 판매 옵션 목록","items":{"$ref":"#/components/schemas/SalesOptionFepResponse"}}},"description":"택1 판매 옵션 그룹"},"SalesOptionFepResponse":{"required":["id","isOneOfRequiredGroup","key","optionValueTemplate"],"type":"object","properties":{"id":{"type":"integer","description":"판매 옵션 ID","format":"int64"},"key":{"type":"string","description":"옵션 키"},"optionValueTemplate":{"$ref":"#/components/schemas/OptionValueTemplateFepResponse"},"isOneOfRequiredGroup":{"type":"boolean","description":"택1 필수 그룹 여부"}},"description":"판매 옵션"},"OptionValueTemplateFepResponse":{"required":["formatType","isOption","optionGroupId","optionGroupName","valueCandidates"],"type":"object","properties":{"optionGroupId":{"type":"integer","description":"옵션 그룹 ID","format":"int64"},"optionGroupName":{"type":"string","description":"옵션 그룹 명"},"formatType":{"type":"string","description":"입력 포맷 타입 (TEXT: 자유 입력, NUMBER: 숫자 입력 + 단위, DROPDOWN: 선택형 입력, RANGE: 숫자 구간 + 단위)"},"valueCandidates":{"type":"array","description":"입력 가능한 값 리스트","items":{"type":"string","description":"입력 가능한 값 리스트"}},"isOption":{"type":"boolean","description":"옵션 여부 (true: 선택 항목, false: 필수 항목)"},"placeholder":{"type":"string","description":"입력 예시"},"unitValues":{"type":"array","description":"입력 단위","items":{"type":"string","description":"입력 단위"}},"keyComment":{"type":"string","description":"옵션 키에 대한 추가 설명"},"valueComment":{"type":"string","description":"옵션 값에 대한 추가 설명"}},"description":"옵션 값 템플릿"}}},"paths":{"/api/v3/shopping-fep/product-constraint-templates/{templateId}":{"get":{"tags":["상품 Public Controller"],"summary":"템플릿 ID로 상품 제약 템플릿 상세 조회","description":"템플릿 ID를 이용하여 상품 제약 조건 템플릿의 판매 옵션 상세 정보를 조회합니다.\n\n## 판매 옵션 구조\n\n판매 옵션은 두 가지로 분류됩니다.\n\n- **selectOneSaleOptions (택1 그룹)**: `groupKey`로 묶인 옵션 그룹입니다. 같은 그룹 내에서 하나만 선택해야 합니다.\n- **salesOptions (일반 옵션)**: 개별 판매 옵션입니다.","operationId":"findConstraintTemplateById_1","parameters":[{"name":"templateId","in":"path","description":"템플릿 ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/GetProductConstraintTemplateByIdFepResponse"}}}}}}}}}}}
```
## 상품 등록
> 상품 등록 API입니다.\
> \
> \## 주의사항\
> \
> \- 상품 등록/수정 시에는 \*\*초당 30건 이하\*\*로 요청해주셔야 합니다\
> \- 초과 시에는 이용량 초과로 인해 요청이 실패할 수 있습니다\
> \- 카테고리 제약사항은 주기적으로 수정될 수 있으므로, API를 호출하여 제약사항을 주기적으로 확인 후 기입되도록 구현 부탁드립니다
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RegisterProductFepRequest":{"required":["categoryId","deliveryPolicy","exchangeReturnPolicy","exposure","images","isTaxFree","name","notice","stocks"],"type":"object","properties":{"name":{"type":"string","description":"상품명\n\n- 정규식: ^[0-9a-zA-Z가-힣 ()\\-·\\[\\]/&+,~.*_#]{1,100}$"},"brandName":{"type":"string","description":"브랜드명\n\n- 정규식: [0-9a-zA-Z가-힣 *()-_+/.,]{1,50}\n\n- 사용 불가 단어: 없음, 중국, 기타, OEM, 협력사"},"categoryId":{"type":"integer","description":"상품 카테고리 ID\n\n- 카테고리 중에 isLeaf=true인 최하위 카테고리ID만 가능","format":"int64"},"stocks":{"maxItems":300,"minItems":0,"type":"array","description":"각 옵션의 판매 정보","items":{"$ref":"#/components/schemas/RegisterProductBodyStockFepRequest"}},"images":{"type":"array","description":"상품 이미지 목록. 썸네일 이미지(THUMBNAIL)가 최소 1개 이상 필요\n\n- THUMBNAIL 1개, DESCRIPTION 또는 DESCRIPTION_HTML 1개 등록 필수\n- 이미지 URL은 기존 사용하시는 사이트 이미지 URL을 업로드해주시면 내부적으로 다운로드하여 등록하게 됩니다.\n- 다운로드 실패 시 상품등록에 실패할 수 있습니다.","items":{"$ref":"#/components/schemas/RegisterProductBodyImageFepRequest"}},"exposure":{"$ref":"#/components/schemas/RegisterProductBodyExposureFepRequest"},"isTaxFree":{"type":"boolean","description":"면세 상품 여부\n\n- true: 면세\n- false: 과세"},"deliveryPolicy":{"$ref":"#/components/schemas/RegisterProductBodyDeliveryPolicyFepRequest"},"exchangeReturnPolicy":{"$ref":"#/components/schemas/RegisterProductBodyExchangeReturnPolicyFepRequest"},"notice":{"$ref":"#/components/schemas/RegisterProductBodyNoticeFepRequest"},"isCultureDeduction":{"type":"boolean","description":"문화비 소득공제 적용 여부"},"managementCode":{"type":"string","description":"판매자가 상품을 관리하려고 사용하는 코드 (최대 100자)"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"상품 등록 요청"},"RegisterProductBodyStockFepRequest":{"required":["isHide","isMainPrice","options","originPrice","remainingCount","salePrice"],"type":"object","properties":{"options":{"type":"array","description":"재고 옵션그룹 이름 & 옵션값 이름\n\n- 카테고리 제약사항에 따라 제한됩니다.\n- 제약사항이 있는 경우에는 반드시 제약사항에 따라 입력이 가능하며 그외 옵션은 입력이 불가합니다.\n- 기존 옵션이 부재한 상품의 경우에도 카테고리 제약사항에 맞게 입력이 필요합니다.","items":{"$ref":"#/components/schemas/RegisterProductBodyStockOptionFepRequest"}},"remainingCount":{"type":"integer","description":"현재 판매할 수 있는 재고 수량\n\n- remainingCount가 0인 경우, 품절 상태로 자동 등록됩니다\n- 0 이상 입력 가능","format":"int32"},"isHide":{"type":"boolean","description":"숨김 여부 (true: 숨김, false: 노출)"},"isMainPrice":{"type":"boolean","description":"대표 가격 여부 (true: 대표 가격으로 노출)\n\n- 반드시 1개만 true여야 합니다"},"originPrice":{"type":"integer","description":"정상가. 권장소비자가격이나 자사몰/온라인 채널에서 판매 이력이 있는 가격\n\n- 최소 1원 이상","format":"int32"},"salePrice":{"type":"integer","description":"판매가. 셀러가 등록한 가격\n\n- 최소 1원 이상\n- 정상가(originPrice) 이하여야 합니다","format":"int32"},"managementCode":{"type":"string","description":"옵션 관리 코드 (최대 100자)"},"images":{"type":"array","description":"옵션 별 이미지 목록. 해당 필드에 값이 있으면 기존에 존재하던 representativeThumbnailImage 필드는 무시됩니다.","items":{"$ref":"#/components/schemas/RegisterProductBodyStockImageFepRequest"}}},"description":"상품 재고 정보"},"RegisterProductBodyStockOptionFepRequest":{"required":["groupName","valueName"],"type":"object","properties":{"groupName":{"type":"string","description":"재고 옵션그룹 이름 (예: 색상)\n- groupName은 카테고리 제약사항 categorySalesOptions의 key\n- isOption = false일 경우 필수\n- isOneOfRequiredGroup = true인 그룹 중 최소 1개 이상 반드시 포함해야 등록 가능\n- 허용 개수: 1~3개\n- 허용 글자: [0-9a-zA-Z가-힣*()-_+/.]{1,10}"},"valueName":{"type":"string","description":"재고 옵션값 이름 (예: 블랙)\n- valueName은 valueCandidates에 포함되는 값만 허용 (valueCandidates가 빈 배열일 경우 자유)\n- unitValues가 있을 경우 valueName은 해당 단위로 끝나는 값이어야합니다.\n- keyComment와 valueComment가 있을 경우 해당 내용을 참조하여 입력해야합니다.\n- 허용 개수: 1~30개\n- 허용 글자: [0-9a-zA-Z가-힣*()-_+/.]{1,30}"}},"description":"재고 옵션 정보"},"RegisterProductBodyStockImageFepRequest":{"required":["order","url"],"type":"object","properties":{"url":{"type":"string","description":"상품 옵션 이미지 url"},"order":{"type":"integer","description":"상품 옵션 정렬 순서","format":"int32"}},"description":"상품 옵션 이미지"},"RegisterProductBodyImageFepRequest":{"required":["order","type"],"type":"object","properties":{"type":{"type":"string","description":"이미지 유형","enum":["THUMBNAIL","DESCRIPTION","DESCRIPTION_HTML","AD"]},"productItemId":{"type":"integer","description":"옵션 식별용 ID","format":"int64"},"url":{"type":"string","description":"이미지 URL (최대 255자)"},"html":{"type":"string","description":"상세 설명 이미지 HTML\n\n- html의 경우, 서버에서 sanitization 후 저장"},"order":{"type":"integer","description":"정렬 순서 (0부터 증가)","format":"int32"}},"description":"상품 이미지 정보"},"RegisterProductBodyExposureFepRequest":{"required":["searchKeywords"],"type":"object","properties":{"searchKeywords":{"type":"array","description":"상품 검색에 사용되는 키워드 목록\n없으면 emptyList로 요청. 키워드 당 1~10 글자 허용\n실제 검색에 활용되는 키워드입니다.\n허용 정규식: [0-9a-zA-Z가-힣]{1,10}","items":{"type":"string","description":"상품 검색에 사용되는 키워드 목록\n없으면 emptyList로 요청. 키워드 당 1~10 글자 허용\n실제 검색에 활용되는 키워드입니다.\n허용 정규식: [0-9a-zA-Z가-힣]{1,10}"}},"description":{"type":"string","description":"사용자에 노출되는 상품 설명. 최대 1500자까지 입력 가능\n\n- AI 상품 추천에 사용돼요\n- 자세히 적을수록 더 적합한 고객에게 추천할 수 있어요"},"serialNumber":{"type":"string","description":"제조사가 부여한 모델명\n\n- 정규식: [0-9a-zA-Z가-힣 -_]{1,50}"}},"description":"상품 노출 정보"},"RegisterProductBodyDeliveryPolicyFepRequest":{"required":["deliveryFee","deliveryFeeType","deliveryMethod","deliveryType","isJejuAndIslandsMountainsDelivery","islandsMountainsDeliveryFee","jejuDeliveryFee","minimumPurchasePrice"],"type":"object","properties":{"deliveryType":{"type":"string","description":"배송 타입","enum":["NORMAL","PREFERRED_DATE"]},"deliveryMethod":{"type":"string","description":"배송 방식","enum":["NORMAL","TODAY_DELIVERY"]},"deliveryDeadline":{"type":"string","description":"출고 마감 시각 (HH:mm, 30분 단위)\n\n- 오늘 출고(TODAY_DELIVERY)일 때 필수입니다\n- 예: \"14:00\", \"14:30\""},"preparationDays":{"type":"integer","description":"상품 준비 기간 (일, 최대 14일)\n\n- 일반 배송(NORMAL)일 때 미입력 시 기본값 3으로 설정됩니다","format":"int32"},"deliveryLocationId":{"type":"integer","description":"배송비 묶음 그룹 ID\n\n- null이면 묶음배송 불가\n- 배송비 묶음 그룹 ID 목록 참고","format":"int64"},"deliveryFeeType":{"type":"string","description":"배송비 유형","enum":["FREE","PAID","CONDITIONALLY_FREE","CASH_ON_DELIVERY"]},"deliveryFee":{"type":"integer","description":"기본 배송비. 무료 배송이면 0원","format":"int32"},"minimumPurchasePrice":{"type":"integer","description":"조건부 무료배송 시 무료배송 조건 금액","format":"int32"},"isJejuAndIslandsMountainsDelivery":{"type":"boolean","description":"제주/도서산간 배송 가능여부 true/false"},"jejuDeliveryFee":{"type":"integer","description":"제주도 추가 배송비\n\n- isJejuAndIslandsMountainsDelivery가 true일 경우 적용됩니다","format":"int32"},"islandsMountainsDeliveryFee":{"type":"integer","description":"도서 산간 추가 배송비\n\n- isJejuAndIslandsMountainsDelivery가 true일 경우 적용됩니다","format":"int32"},"deliveryCompanyId":{"type":"integer","description":"택배사 ID","format":"int64"},"preferredDateType":{"type":"string","description":"희망일 배송 기준 타입 (`ORDER_DATE`: 주문일 기준, `CALENDAR`: 캘린더 기준)","enum":["ORDER_DATE","CALENDAR"]},"preferredDateFromDays":{"type":"integer","description":"주문일로부터 시작일 (1~30). ORDER_DATE 타입에서 사용","format":"int32"},"preferredDateToDays":{"type":"integer","description":"주문일로부터 종료일 (30~90). ORDER_DATE 타입에서 사용","format":"int32"},"preferredDateFromDate":{"type":"string","description":"희망 배송 시작일. CALENDAR 타입에서 사용","format":"date"},"preferredDateToDate":{"type":"string","description":"희망 배송 종료일. CALENDAR 타입에서 사용","format":"date"}},"description":"배송 정책"},"RegisterProductBodyExchangeReturnPolicyFepRequest":{"required":["applicationMethodDescription","applicationTermDescription","exchangeRefundLocationId","exchangeRoundTripDeliveryFee","refundOneWayDeliveryFee"],"type":"object","properties":{"exchangeRefundLocationId":{"type":"integer","description":"교환/반품지 ID\n\n- 교환/반품지 조회 API 참조","format":"int64"},"refundOneWayDeliveryFee":{"type":"integer","description":"반품 편도 배송비 (0 이상)","format":"int32"},"exchangeRoundTripDeliveryFee":{"type":"integer","description":"교환 왕복 배송비 (0 이상)","format":"int32"},"applicationMethodDescription":{"type":"string","description":"교환,환불 방법 설명 (1~500자)"},"applicationTermDescription":{"type":"string","description":"교환,환불 신청 가능 기간 설명 (1~500자)"}},"description":"교환/반품 정책"},"RegisterProductBodyNoticeFepRequest":{"required":["categoryCode","items"],"type":"object","properties":{"categoryCode":{"type":"string","description":"상품 정보제공 고시 카테고리 코드\n\n- 정보제공 고시를 위한 카테고리 목록 조회 API 참조"},"items":{"type":"array","description":"상품 정보제공 고시 항목 목록\n\n- 정보제공 고시를 위한 항목 조회 API 참조","items":{"$ref":"#/components/schemas/RegisterProductBodyNoticeItemFepRequest"}}},"description":"상품 정보제공 고시"},"RegisterProductBodyNoticeItemFepRequest":{"required":["content","id"],"type":"object","properties":{"id":{"type":"integer","description":"정보제공 고시 항목 ID","format":"int64"},"content":{"type":"string","description":"고시 항목 내용 (판매자 입력 정보, 1~4000자)"}},"description":"정보제공 고시 항목"},"RegisterProductResponse":{"required":["id"],"type":"object","properties":{"id":{"type":"integer","description":"상품 ID","format":"int64"}},"description":"상품 등록 응답"}}},"paths":{"/api/v3/shopping-fep/products/v2":{"post":{"tags":["상품 Public Controller"],"summary":"상품 등록","description":"상품 등록 API입니다.\n\n## 주의사항\n\n- 상품 등록/수정 시에는 **초당 30건 이하**로 요청해주셔야 합니다\n- 초과 시에는 이용량 초과로 인해 요청이 실패할 수 있습니다\n- 카테고리 제약사항은 주기적으로 수정될 수 있으므로, API를 호출하여 제약사항을 주기적으로 확인 후 기입되도록 구현 부탁드립니다","operationId":"registerProductV2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterProductFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","TOO_MANY_REQUEST","BAD_REQUEST","NOT_FOUND","INTERNAL_SERVER_ERROR","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/RegisterProductResponse"}}}}}}}}}}}
```
## 상품 정보 변경
> 상품등록시 반환된 상품 ID를 이용하여 상품 정보를 변경합니다.\
> \
> \## 검수 정책\
> \
> \- \*\*이미지 변경\*\*: 검수 단계로 진입됩니다\
> \- \*\*가격/재고/배송정보 변경\*\*: 즉시 반영됩니다\
> \- \*\*검수 반려된 상품\*\*: 정보 변경 시 자동으로 검수 단계로 진입합니다
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ChangeProductFepRequest":{"required":["categoryId","deliveryPolicy","exchangeReturnPolicy","exposure","images","isTaxFree","name","notice","stocks"],"type":"object","properties":{"name":{"type":"string","description":"상품명\n\n- 정규식: ^[0-9a-zA-Z가-힣 ()\\-·\\[\\]/&+,~.*_#]{1,100}$"},"brandName":{"type":"string","description":"브랜드명\n\n- 정규식: [0-9a-zA-Z가-힣 *()-_+/.,]{1,50}\n\n- 사용 불가 단어: 없음, 중국, 기타, OEM, 협력사"},"stocks":{"maxItems":300,"minItems":0,"type":"array","description":"각 옵션의 판매 정보","items":{"$ref":"#/components/schemas/ChangeProductBodyStockFepRequest"}},"images":{"type":"array","description":"상품 이미지 목록","items":{"$ref":"#/components/schemas/ChangeProductBodyImageFepRequest"}},"exposure":{"$ref":"#/components/schemas/ChangeProductBodyExposureFepRequest"},"isTaxFree":{"type":"boolean","description":"면세 상품 여부 (true: 면세, false: 과세)"},"isCultureDeduction":{"type":"boolean","description":"문화비 소득공제 적용 여부"},"deliveryPolicy":{"$ref":"#/components/schemas/ChangeProductBodyDeliveryPolicyFepRequest"},"exchangeReturnPolicy":{"$ref":"#/components/schemas/ChangeProductBodyExchangeReturnPolicyFepRequest"},"notice":{"$ref":"#/components/schemas/ChangeProductBodyNoticeFepRequest"},"categoryId":{"type":"integer","description":"상품 카테고리 ID","format":"int64"},"managementCode":{"type":"string","description":"상품 관리 코드 (최대 100자)"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"상품 정보 변경 요청"},"ChangeProductBodyStockFepRequest":{"required":["isHide","isMainPrice","options","originPrice","remainingCount","salePrice"],"type":"object","properties":{"options":{"type":"array","description":"옵션 목록","items":{"$ref":"#/components/schemas/Option"}},"remainingCount":{"type":"integer","description":"현재 판매할 수 있는 재고 수량\n\n- remainingCount가 0인 경우, 품절 상태로 자동 등록됩니다\n- 0 이상 입력 가능","format":"int32"},"isMainPrice":{"type":"boolean","description":"대표 가격 여부 (true: 대표 가격으로 노출)"},"isHide":{"type":"boolean","description":"숨김 여부 (true: 숨김, false: 노출)"},"originPrice":{"type":"integer","description":"정상가. 권장소비자가격이나 자사몰/온라인 채널에서 판매 이력이 있는 가격\n\n- 최소 1원 이상","format":"int32"},"salePrice":{"type":"integer","description":"판매가. 셀러가 등록한 가격\n\n- 최소 1원 이상\n- 정상가(originPrice) 이하여야 합니다","format":"int32"},"managementCode":{"type":"string","description":"옵션 관리 코드 (최대 100자)"},"representativeThumbnailImage":{"type":"string","description":"옵션 별 대표 썸네일 이미지 URL"},"images":{"type":"array","description":"옵션 별 이미지 목록","items":{"$ref":"#/components/schemas/ChangeProductBodyStockImageFepRequest"}}},"description":"상품 재고 정보"},"Option":{"required":["groupName","valueName"],"type":"object","properties":{"groupName":{"type":"string","description":"옵션 그룹 이름"},"valueName":{"type":"string","description":"옵션 값 이름"}},"description":"재고 옵션"},"ChangeProductBodyStockImageFepRequest":{"required":["order","url"],"type":"object","properties":{"url":{"type":"string","description":"상품 옵션 이미지 url"},"order":{"type":"integer","description":"상품 옵션 이미지 순서","format":"int32"}},"description":"상품 옵션 이미지"},"ChangeProductBodyImageFepRequest":{"required":["order","type"],"type":"object","properties":{"type":{"type":"string","description":"이미지 유형","enum":["THUMBNAIL","DESCRIPTION","DESCRIPTION_HTML","AD","PRODUCT_ITEM"]},"url":{"type":"string","description":"이미지 URL (최대 255자)"},"html":{"type":"string","description":"상세 설명 이미지 HTML\n\n- html의 경우, 서버에서 sanitization 후 저장"},"order":{"type":"integer","description":"정렬 순서 (0부터 증가)","format":"int32"}},"description":"상품 이미지 정보"},"ChangeProductBodyExposureFepRequest":{"required":["description","searchKeywords"],"type":"object","properties":{"searchKeywords":{"type":"array","description":"상품 검색에 사용되는 키워드 목록\n없으면 emptyList로 요청. 키워드 당 1~10 글자 허용\n실제 검색에 활용되는 키워드입니다.\n허용 정규식: [0-9a-zA-Z가-힣]{1,10}","items":{"type":"string","description":"상품 검색에 사용되는 키워드 목록\n없으면 emptyList로 요청. 키워드 당 1~10 글자 허용\n실제 검색에 활용되는 키워드입니다.\n허용 정규식: [0-9a-zA-Z가-힣]{1,10}"}},"description":{"type":"string","description":"사용자에게 보여지는 상품 설명. 최대 1500자까지 입력 가능\n\n- AI 상품 추천에 사용돼요\n- 자세히 적을수록 더 적합한 고객에게 추천할 수 있어요"},"serialNumber":{"type":"string","description":"제조사가 부여한 모델명\n\n- 정규식: [0-9a-zA-Z가-힣 -_]{1,50}"}},"description":"상품 노출 정보"},"ChangeProductBodyDeliveryPolicyFepRequest":{"required":["deliveryFee","deliveryFeeType","deliveryMethod","deliveryType","isJejuAndIslandsMountainsDelivery","islandsMountainsDeliveryFee","jejuDeliveryFee","minimumPurchasePrice"],"type":"object","properties":{"deliveryType":{"type":"string","description":"배송 타입","enum":["NORMAL","PREFERRED_DATE"]},"deliveryMethod":{"type":"string","description":"배송 방식","enum":["NORMAL","TODAY_DELIVERY"]},"deliveryDeadline":{"type":"string","description":"출고 마감 시각 (HH:mm, 30분 단위)\n\n- 오늘 출고(TODAY_DELIVERY)일 때 필수입니다\n- 예: \"14:00\", \"14:30\""},"preparationDays":{"type":"integer","description":"상품 준비 기간 (일, 최대 14일)\n\n- 일반 배송(NORMAL)일 때 미입력 시 기본값 3으로 설정됩니다","format":"int32"},"deliveryLocationId":{"type":"integer","description":"배송비 묶음 그룹 ID\n\n- null이면 묶음배송 불가\n- 배송비 묶음 그룹 ID 목록 참고","format":"int64"},"deliveryFeeType":{"type":"string","description":"배송비 유형","enum":["FREE","PAID","CONDITIONALLY_FREE","CASH_ON_DELIVERY"]},"deliveryFee":{"type":"integer","description":"기본 배송비 (0 이상)","format":"int32"},"minimumPurchasePrice":{"type":"integer","description":"조건부 무료배송 시 무료배송 조건 금액 (0 이상)","format":"int32"},"isJejuAndIslandsMountainsDelivery":{"type":"boolean","description":"제주/도서산간 배송 가능여부 true/false"},"jejuDeliveryFee":{"type":"integer","description":"제주도 추가 배송비 (0 이상)\n\n- isJejuAndIslandsMountainsDelivery가 true일 경우 적용됩니다","format":"int32"},"islandsMountainsDeliveryFee":{"type":"integer","description":"도서 산간 추가 배송비 (0 이상)\n\n- isJejuAndIslandsMountainsDelivery가 true일 경우 적용됩니다","format":"int32"},"deliveryCompanyId":{"type":"integer","description":"택배사 ID\n\n- 택배사 목록 조회 API 참조","format":"int64"},"preferredDateType":{"type":"string","description":"희망일 배송 기준 타입 (`ORDER_DATE`: 주문일 기준, `CALENDAR`: 캘린더 기준)","enum":["ORDER_DATE","CALENDAR"]},"preferredDateFromDays":{"type":"integer","description":"주문일로부터 시작일 (1~30). ORDER_DATE 타입에서 사용","format":"int32"},"preferredDateToDays":{"type":"integer","description":"주문일로부터 종료일 (30~90). ORDER_DATE 타입에서 사용","format":"int32"},"preferredDateFromDate":{"type":"string","description":"희망 배송 시작일. CALENDAR 타입에서 사용","format":"date"},"preferredDateToDate":{"type":"string","description":"희망 배송 종료일. CALENDAR 타입에서 사용","format":"date"}},"description":"배송 정책"},"ChangeProductBodyExchangeReturnPolicyFepRequest":{"required":["applicationMethodDescription","applicationTermDescription","exchangeRefundLocationId","exchangeRoundTripDeliveryFee","refundOneWayDeliveryFee"],"type":"object","properties":{"exchangeRefundLocationId":{"type":"integer","description":"교환/반품지 ID\n\n- 교환/반품지 조회 API 참조","format":"int64"},"refundOneWayDeliveryFee":{"type":"integer","description":"반품 배송비(편도) (0 이상)","format":"int32"},"exchangeRoundTripDeliveryFee":{"type":"integer","description":"교환 배송비(왕복) (0 이상)","format":"int32"},"applicationMethodDescription":{"type":"string","description":"교환/반품 신청 방법 (1~500자)"},"applicationTermDescription":{"type":"string","description":"교환/반품 신청 가능 기간 (1~500자)"}},"description":"교환/반품 정책"},"ChangeProductBodyNoticeFepRequest":{"required":["categoryCode","items"],"type":"object","properties":{"categoryCode":{"type":"string","description":"상품 정보제공 고시 카테고리 코드"},"items":{"type":"array","description":"상품 정보제공 고시 항목 목록","items":{"$ref":"#/components/schemas/ChangeProductBodyNoticeItemFepRequest"}}},"description":"상품 정보제공 고시"},"ChangeProductBodyNoticeItemFepRequest":{"required":["content","id"],"type":"object","properties":{"id":{"type":"integer","description":"상품 정보제공 고시 항목 ID","format":"int64"},"content":{"type":"string","description":"상품 정보제공 고시 항목에 대한 내용 (1~4000자)"}},"description":"정보제공 고시 항목"}}},"paths":{"/api/v3/shopping-fep/products/{productId}/v2":{"put":{"tags":["상품 Public Controller"],"summary":"상품 정보 변경","description":"상품등록시 반환된 상품 ID를 이용하여 상품 정보를 변경합니다.\n\n## 검수 정책\n\n- **이미지 변경**: 검수 단계로 진입됩니다\n- **가격/재고/배송정보 변경**: 즉시 반영됩니다\n- **검수 반려된 상품**: 정보 변경 시 자동으로 검수 단계로 진입합니다","operationId":"changeProductV2","parameters":[{"name":"productId","in":"path","description":"상품 ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeProductFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","BAD_REQUEST","NOT_FOUND","INTERNAL_SERVER_ERROR","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```
## 상품 삭제
> 상품을 삭제합니다.\
> \
> \## 주의사항\
> \
> \- 노출중인 상품은 삭제할 수 없습니다\
> \- 상품 삭제 전 \*\*상품 정보 노출 상태 숨기기로 변경 API\*\*를 호출하여 숨김 처리 후 삭제해주셔야 합니다
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RemoveProductBody":{"required":["productId"],"type":"object","properties":{"productId":{"type":"integer","description":"상품 ID","format":"int64"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"상품 삭제 요청"}}},"paths":{"/api/v3/shopping-fep/products/remove":{"post":{"tags":["상품 Public Controller"],"summary":"상품 삭제","description":"상품을 삭제합니다.\n\n## 주의사항\n\n- 노출중인 상품은 삭제할 수 없습니다\n- 상품 삭제 전 **상품 정보 노출 상태 숨기기로 변경 API**를 호출하여 숨김 처리 후 삭제해주셔야 합니다","operationId":"removeProduct","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveProductBody"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","BAD_REQUEST","NOT_FOUND","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```
## 상품 조회
> 상품 ID를 이용하여 상품 정보를 조회합니다.
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ProductFepResponse":{"required":["categories","categoryId","categoryName","constraintTemplateId","deliveryPolicy","exchangeReturnPolicy","exposure","firstCategoryId","firstCategoryName","id","images","inspectionStatus","isCultureDeduction","isTaxFree","merchantId","name","options","rejectionReasons","stocks","version"],"type":"object","properties":{"id":{"type":"integer","description":"상품 식별용 ID","format":"int64"},"merchantId":{"type":"integer","description":"상점 식별용 ID","format":"int64"},"name":{"type":"string","description":"사용자에게 노출되는 상품 이름"},"brandName":{"type":"string","description":"브랜드 이름"},"isTaxFree":{"type":"boolean","description":"면세 상품 여부 (true: 면세, false: 과세)"},"isCultureDeduction":{"type":"boolean","description":"문화비 소득공제 적용 여부"},"inspectionStatus":{"type":"string","description":"검수 상태","enum":["LLM_INSPECTION_READY","COMPLETE","REJECT"]},"rejectionReasons":{"type":"array","description":"검수 거절 사유 목록","items":{"$ref":"#/components/schemas/ProductResponseRejectionReasonFepResponse"}},"exposure":{"$ref":"#/components/schemas/ProductResponseExposureFepResponse"},"serialNumberId":{"type":"integer","description":"모델명 ID","format":"int64"},"version":{"type":"integer","description":"상품 버전 번호 (상품 수정될 때마다 증가)","format":"int32"},"constraintTemplateId":{"type":"integer","description":"상품 제약 템플릿 식별용 ID","format":"int64"},"deliveryPolicy":{"$ref":"#/components/schemas/ProductResponseDeliveryPolicyFepResponse"},"firstCategoryId":{"type":"integer","description":"상품 1차 카테고리 ID","format":"int64"},"firstCategoryName":{"type":"string","description":"상품 1차 카테고리 명"},"categoryId":{"type":"integer","description":"상품 카테고리 ID","format":"int64"},"categoryName":{"type":"string","description":"상품 카테고리 명"},"categories":{"type":"array","description":"1차 카테고리부터 해당 카테고리까지 경로상의 모든 카테고리 정보 배열","items":{"$ref":"#/components/schemas/ProductResponseCategoryFepResponse"}},"options":{"type":"array","description":"상품 옵션 그룹","items":{"$ref":"#/components/schemas/ProductResponseOptionGroupFepResponse"}},"stocks":{"type":"array","description":"상품의 옵션별 재고 정보","items":{"$ref":"#/components/schemas/ProductResponseStockFepResponse"}},"images":{"type":"array","description":"상품 이미지 (썸네일, 상세 설명 이미지 등)","items":{"$ref":"#/components/schemas/ProductResponseImageFepResponse"}},"exchangeReturnPolicy":{"$ref":"#/components/schemas/ProductResponseExchangeReturnPolicyFepResponse"},"notice":{"$ref":"#/components/schemas/ProductResponseNoticeFepResponse"},"lastInspectionRequestedAt":{"type":"string","description":"마지막 검수 요청 시각","format":"date-time"},"managementCode":{"type":"string","description":"판매자가 상품 관리에 사용하는 코드"},"removedAt":{"type":"string","description":"삭제 시각","format":"date-time"}},"description":"상품 상세 조회 응답"},"ProductResponseRejectionReasonFepResponse":{"required":["message","title"],"type":"object","properties":{"title":{"type":"string","description":"반려 사유 제목"},"message":{"type":"string","description":"반려 사유 메시지"}},"description":"검수 거절 사유 목록"},"ProductResponseExposureFepResponse":{"required":["description","searchKeywords"],"type":"object","properties":{"searchKeywords":{"type":"array","description":"검색 키워드 목록","items":{"type":"string","description":"검색 키워드 목록"}},"description":{"type":"string","description":"상품 설명"},"serialNumber":{"type":"string","description":"모델명"}},"description":"검색 키워드, 상품 설명, 모델명 등 사용자 노출과 관련된 정보"},"ProductResponseDeliveryPolicyFepResponse":{"required":["deliveryFee","deliveryFeeType","deliveryMethod","deliveryType","isJejuAndIslandsMountainsDelivery","islandsMountainsDeliveryFee","jejuDeliveryFee"],"type":"object","properties":{"deliveryType":{"type":"string","description":"배송 타입","enum":["NORMAL","PREFERRED_DATE"]},"deliveryMethod":{"type":"string","description":"배송 방식","enum":["NORMAL","TODAY_DELIVERY"]},"deliveryDeadline":{"type":"string","description":"출고 마감 시각 (HH:mm)"},"deliveryCutoffTime":{"type":"string","description":"출고 마감 시각 (HH:mm)"},"preparationDays":{"type":"integer","description":"상품 준비 기간 (일)","format":"int32"},"deliveryLocationId":{"type":"integer","description":"배송비 묶음 그룹 ID","format":"int64"},"deliveryFeeType":{"type":"string","description":"배송비 유형","enum":["FREE","PAID","CONDITIONALLY_FREE","CASH_ON_DELIVERY"]},"deliveryFee":{"type":"integer","description":"배송 비용","format":"int32"},"minimumPurchasePrice":{"type":"integer","description":"무료배송 조건을 위한 최소 구매 금액","format":"int32"},"isJejuAndIslandsMountainsDelivery":{"type":"boolean","description":"제주/도서산간 배송 여부"},"jejuDeliveryFee":{"type":"integer","description":"제주 배송 비용","format":"int32"},"islandsMountainsDeliveryFee":{"type":"integer","description":"도서산간 배송 비용","format":"int32"},"deliveryCompanyId":{"type":"integer","description":"택배사 ID","format":"int64"},"preferredDateType":{"type":"string","description":"희망일 배송 기준 타입 (`ORDER_DATE`: 주문일 기준, `CALENDAR`: 캘린더 기준)","enum":["ORDER_DATE","CALENDAR"]},"preferredDateFromDays":{"type":"integer","description":"주문일로부터 시작일 (1~30). ORDER_DATE 타입에서 사용","format":"int32"},"preferredDateToDays":{"type":"integer","description":"주문일로부터 종료일 (30~90). ORDER_DATE 타입에서 사용","format":"int32"},"preferredDateFromDate":{"type":"string","description":"희망 배송 시작일. CALENDAR 타입에서 사용","format":"date"},"preferredDateToDate":{"type":"string","description":"희망 배송 종료일. CALENDAR 타입에서 사용","format":"date"}},"description":"배송 정책"},"ProductResponseCategoryFepResponse":{"required":["id","level","name"],"type":"object","properties":{"id":{"type":"integer","description":"카테고리 식별용 ID","format":"int64"},"level":{"type":"integer","description":"카테고리 깊이 (1차 카테고리는 1, 2차 카테고리는 2)","format":"int32"},"name":{"type":"string","description":"카테고리 이름"},"parentId":{"type":"integer","description":"바로 위 카테고리 ID","format":"int64"}},"description":"1차 카테고리부터 해당 카테고리까지 경로상의 모든 카테고리 정보 배열"},"ProductResponseOptionGroupFepResponse":{"required":["name","order","values"],"type":"object","properties":{"name":{"type":"string","description":"옵션 그룹 이름"},"order":{"type":"integer","description":"옵션 그룹 표시 순서","format":"int32"},"values":{"type":"array","description":"이 옵션 그룹에 속하는 옵션 값","items":{"$ref":"#/components/schemas/ProductResponseOptionGroupValue"}}},"description":"상품 옵션 그룹"},"ProductResponseOptionGroupValue":{"required":["name","order"],"type":"object","properties":{"name":{"type":"string","description":"옵션 값 이름"},"order":{"type":"integer","description":"옵션 값 표시 순서","format":"int32"}},"description":"이 옵션 그룹에 속하는 옵션 값"},"ProductResponseStockFepResponse":{"required":["id","images","isHide","isMainPrice","isPurchasableAlone","isSoldOut","options","originPrice","remainingCount","salePrice","type"],"type":"object","properties":{"id":{"type":"integer","description":"재고 식별용 ID","format":"int64"},"itemId":{"type":"integer","description":"옵션 식별용 ID","format":"int64"},"type":{"type":"string","description":"재고 유형"},"options":{"type":"array","description":"옵션 목록","items":{"$ref":"#/components/schemas/ProductResponseStockOptionFepResponse"}},"remainingCount":{"type":"integer","description":"현재 판매 가능한 재고 수량","format":"int32"},"isMainPrice":{"type":"boolean","description":"대표 가격 여부 (true: 대표 가격으로 노출)"},"isSoldOut":{"type":"boolean","description":"품절 상태 여부 (true: 품절, false: 판매 중)","deprecated":true},"isHide":{"type":"boolean","description":"재고 숨김 여부 (true: 숨김, false: 노출)"},"originPrice":{"type":"integer","description":"정상가 (권장소비자가격이나 자사몰/온라인 채널에서 판매 이력이 있는 가격)","format":"int32"},"salePrice":{"type":"integer","description":"판매가 (셀러가 등록한 가격)","format":"int32"},"isPurchasableAlone":{"type":"boolean","description":"단독구매 가능 여부. true 면 단독구매 가능 false 면 단독구매 불가능","deprecated":true},"managementCode":{"type":"string","description":"판매자가 옵션 관리에 사용하는 코드"},"representativeThumbnailImage":{"type":"string","description":"옵션별 썸네일 이미지 URL"},"images":{"type":"array","description":"옵션별 썸네일 이미지 목록","items":{"$ref":"#/components/schemas/ProductResponseStockImageFepResponse"}}},"description":"상품의 옵션별 재고 정보"},"ProductResponseStockOptionFepResponse":{"required":["groupName","valueName"],"type":"object","properties":{"groupName":{"type":"string","description":"옵션 그룹 이름"},"valueName":{"type":"string","description":"옵션 값 이름"}},"description":"옵션 목록"},"ProductResponseStockImageFepResponse":{"required":["url"],"type":"object","properties":{"url":{"type":"string","description":"상품 옵션 썸네일 이미지 url"}},"description":"상품 옵션 이미지"},"ProductResponseImageFepResponse":{"required":["order","type","url"],"type":"object","properties":{"type":{"type":"string","description":"이미지 유형","enum":["THUMBNAIL","DESCRIPTION","DESCRIPTION_HTML","AD"]},"url":{"type":"string","description":"URL"},"requestedUrl":{"type":"string","description":"요청 이미지 URL"},"sellerHtml":{"type":"string","description":"판매자 HTML"},"order":{"type":"integer","description":"이미지 표시 순서","format":"int32"}},"description":"상품 이미지 (썸네일, 상세 설명 이미지 등)"},"ProductResponseExchangeReturnPolicyFepResponse":{"required":["applicationMethodDescription","applicationTermDescription","exchangeRefundLocationId","exchangeRoundTripDeliveryFee","refundOneWayDeliveryFee"],"type":"object","properties":{"exchangeRefundLocationId":{"type":"integer","description":"교환/반품지 ID","format":"int64"},"refundOneWayDeliveryFee":{"type":"integer","description":"반품 배송비(편도)","format":"int32"},"exchangeRoundTripDeliveryFee":{"type":"integer","description":"교환 배송비(왕복)","format":"int32"},"applicationMethodDescription":{"type":"string","description":"교환/반품 신청 방법"},"applicationTermDescription":{"type":"string","description":"교환/반품 신청 가능 기간"}},"description":"상품 교환/반품 정책"},"ProductResponseNoticeFepResponse":{"required":["categoryCode","items"],"type":"object","properties":{"categoryCode":{"type":"string","description":"상품 정보제공 고시 카테고리 코드"},"items":{"type":"array","description":"상품 정보제공 고시 항목 목록","items":{"$ref":"#/components/schemas/ProductResponseNoticeItemFepResponse"}}},"description":"상품 정보제공 고시"},"ProductResponseNoticeItemFepResponse":{"required":["content","id","title"],"type":"object","properties":{"id":{"type":"integer","description":"상품 정보제공 고시 항목 ID","format":"int64"},"title":{"type":"string","description":"상품 정보제공 고시 항목"},"content":{"type":"string","description":"상품 정보제공 고시 항목에 대한 내용"}},"description":"상품 정보제공 고시 항목 목록"}}},"paths":{"/api/v3/shopping-fep/products/{productId}/v2":{"get":{"tags":["상품 Public Controller"],"summary":"상품 조회","description":"상품 ID를 이용하여 상품 정보를 조회합니다.","operationId":"getProductV2","parameters":[{"name":"productId","in":"path","description":"상품 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","BAD_REQUEST","NOT_FOUND","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/ProductFepResponse"}}}}}}}}}}}
```
## 상품 목록 조회
> 등록한 상품 목록을 커서 조회합니다.
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ListProductsV2FepResponse":{"required":["hasNext","nextToken","products"],"type":"object","properties":{"products":{"type":"array","description":"상품 목록","items":{"$ref":"#/components/schemas/ListProductsV2FepResponseItem"}},"nextToken":{"type":"string","description":"다음 페이지를 위한 토큰. 다음 페이지 조회 시 이 값을 그대로 전달"},"hasNext":{"type":"boolean","description":"다음 페이지 존재 여부. false이면 마지막 페이지"}}},"ListProductsV2FepResponseItem":{"required":["exposureStatus","id","images","inspectionStatus","name","regTs","salePrice"],"type":"object","properties":{"id":{"type":"integer","description":"상품 ID","format":"int64"},"images":{"type":"array","description":"상품 이미지 목록","items":{"$ref":"#/components/schemas/ListProductsV2FepResponseImageItem"}},"brandName":{"type":"string","description":"브랜드명"},"name":{"type":"string","description":"상품명"},"salePrice":{"type":"integer","description":"판매가","format":"int32"},"inspectionStatus":{"type":"string","description":"검수 상태","enum":["LLM_INSPECTION_READY","COMPLETE","REJECT"]},"exposureStatus":{"type":"string","description":"노출 상태","enum":["UNEXPOSURE","EXPOSURE_WAITING","EXPOSURE","EXPOSURE_FINISHED"]},"regTs":{"type":"string","description":"상품 등록 일시","format":"date-time"}},"description":"상품 목록"},"ListProductsV2FepResponseImageItem":{"required":["id","indexOrder","inspectionStatus","type"],"type":"object","properties":{"id":{"type":"integer","description":"이미지 ID","format":"int64"},"type":{"type":"string","description":"이미지 유형","enum":["THUMBNAIL","DESCRIPTION","DESCRIPTION_HTML","AD","PRODUCT_ITEM"]},"url":{"type":"string","description":"이미지 URL"},"inspectionStatus":{"type":"string","enum":["LLM_INSPECTION_READY","COMPLETE","REJECT"]},"indexOrder":{"type":"integer","description":"상품 이미지 순서","format":"int32"}},"description":"상품 이미지 목록"}}},"paths":{"/api/v3/shopping-fep/products/v2":{"get":{"tags":["상품 Public Controller"],"summary":"상품 목록 조회","description":"등록한 상품 목록을 커서 조회합니다.","operationId":"listProductsV2","parameters":[{"name":"regStartDate","in":"query","description":"상품 등록 일자 시작 범위","required":false,"schema":{"type":"string","format":"date"}},{"name":"regEndDate","in":"query","description":"상품 등록 일자 끝 범위","required":false,"schema":{"type":"string","format":"date"}},{"name":"productIds","in":"query","description":"조회할 상품 ID 목록","required":false,"schema":{"uniqueItems":true,"type":"array","items":{"type":"integer","format":"int64"}}},{"name":"nextToken","in":"query","description":"다음 페이지를 위한 커서 정보 (직전 호출에서 받은 nextToken을 그대로 넘겨 호출)","required":false,"schema":{"type":"string"}},{"name":"size","in":"query","description":"페이지 사이즈 (기본값: 20)","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드"},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/ListProductsV2FepResponse"}}}}}}}}}}}
```
## 상품 옵션 그룹 검색 (커서 기반, product 단위 그룹핑)
> 여러 필터 조건 조합을 지원하는 옵션 그룹 검색 API입니다. 페이지 단위는 product 기준이며 응답 row는 product 그룹입니다.\
> \
> \## 페이지네이션\
> \
> \- 커서 기반 페이지네이션을 사용합니다.\
> \
> \- 첫 요청 시 \`nextCursor\`/\`prevCursor\`를 비워서 호출합니다.\
> \
> \- 응답의 \`hasNext\`가 \`true\`이면, \`nextCursor\` 값을 다음 요청의 \`nextCursor\`에 넣어 호출합니다.\
> \
> \- 응답의 \`hasPrev\`가 \`true\`이면, \`prevCursor\` 값을 이전 요청의 \`prevCursor\`에 넣어 호출합니다.\
> \
> \- \`nextCursor\`와 \`prevCursor\`를 동시에 사용할 수 없습니다.\
> \
> \## 필터링\
> \
> \- \`itemStatuses\`: 아이템 상태로 필터링할 수 있습니다.\
> \
> \- \`productName\`: 상품명 부분 검색을 지원합니다.\
> \
> \- \`productIds\`: 특정 상품 ID로 필터링할 수 있습니다.\
> \
> \- \`itemIds\`: 특정 아이템 ID로 필터링할 수 있습니다.
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ProductItemsGroupByProductCursorFepResponse":{"required":["hasNext","hasPrev","items","productCount"],"type":"object","properties":{"productCount":{"type":"integer","description":"조회된 상품 수","format":"int64"},"items":{"type":"array","description":"product 단위 그룹 목록","items":{"$ref":"#/components/schemas/ProductItemsGroupByProductFepResponseItem"}},"hasNext":{"type":"boolean","description":"다음 페이지 존재 여부"},"hasPrev":{"type":"boolean","description":"이전 페이지 존재 여부"},"nextCursor":{"type":"integer","description":"다음 페이지 커서 (다음 조회 시 nextCursor로 전달)","format":"int64"},"prevCursor":{"type":"integer","description":"이전 페이지 커서 (이전 조회 시 prevCursor로 전달)","format":"int64"}},"description":"상품 옵션 그룹 검색 응답 (커서 기반, product 단위 그룹핑)"},"ProductItemsGroupByProductFepResponseItem":{"required":["hasMoreItems","productId","productInspectionStatus","productIsHide","productItems","productName","summaryStatus"],"type":"object","properties":{"productId":{"type":"integer","description":"상품 ID","format":"int64"},"productName":{"type":"string","description":"상품명"},"brandName":{"type":"string","description":"브랜드명"},"summaryStatus":{"$ref":"#/components/schemas/ProductItemsGroupByProductFepResponseSummaryStatus"},"productInspectionStatus":{"type":"string","description":"검수 상태","enum":["LLM_INSPECTION_READY","COMPLETE","REJECT"]},"productIsHide":{"type":"boolean","description":"상품 숨김 여부"},"productItems":{"type":"array","description":"상품 아이템 목록","items":{"$ref":"#/components/schemas/ListProductItemsFepResponseItem"}},"hasMoreItems":{"type":"boolean","description":"상품 내 추가 아이템 존재 여부"},"nextItemCursor":{"type":"integer","description":"상품 내 다음 아이템 커서","format":"int64"}},"description":"product 단위 그룹 항목"},"ProductItemsGroupByProductFepResponseSummaryStatus":{"required":["label","status"],"type":"object","properties":{"status":{"type":"string","description":"상태 코드","enum":["NORMAL","STOP","PENDING"]},"label":{"type":"string","description":"상태 라벨"}},"description":"상품 요약 상태"},"ListProductItemsFepResponseItem":{"required":["isAdultProduct","isMainOption","itemId","itemName","originPrice","quantity","rejectReasons","salePrice","status"],"type":"object","properties":{"itemId":{"type":"integer","description":"아이템 ID","format":"int64"},"itemName":{"type":"string","description":"아이템명"},"quantity":{"type":"integer","description":"재고 수량","format":"int32"},"rejectReasons":{"type":"array","description":"검수 반려 사유 목록","items":{"$ref":"#/components/schemas/ListProductItemsFepResponseRejectReason"}},"isMainOption":{"type":"boolean","description":"대표 옵션 여부"},"status":{"$ref":"#/components/schemas/ListProductItemsFepResponseStatus"},"originPrice":{"type":"integer","description":"정상가","format":"int32"},"salePrice":{"type":"integer","description":"판매가","format":"int32"},"isAdultProduct":{"type":"boolean","description":"청소년 구매 불가 상품 여부"}},"description":"상품 아이템 항목"},"ListProductItemsFepResponseRejectReason":{"required":["message","title"],"type":"object","properties":{"title":{"type":"string","description":"반려 사유 제목"},"message":{"type":"string","description":"반려 사유 상세 메시지"}},"description":"검수 반려 사유"},"ListProductItemsFepResponseStatus":{"required":["code","label"],"type":"object","properties":{"code":{"type":"string","description":"상태 코드","enum":["SOLD_OUT","PENALTY","SELLING","WAITING_FOR_SALE","REVISION_REQUIRED","REJECTED","INSPECTING"]},"label":{"type":"string","description":"상태 라벨"}},"description":"아이템 상태 요약"}}},"paths":{"/api/v3/shopping-fep/product-items/grouped-by-products":{"get":{"tags":["상품 Public Controller"],"summary":"상품 옵션 그룹 검색 (커서 기반, product 단위 그룹핑)","description":"여러 필터 조건 조합을 지원하는 옵션 그룹 검색 API입니다. 페이지 단위는 product 기준이며 응답 row는 product 그룹입니다.\n\n## 페이지네이션\n\n- 커서 기반 페이지네이션을 사용합니다.\n\n- 첫 요청 시 `nextCursor`/`prevCursor`를 비워서 호출합니다.\n\n- 응답의 `hasNext`가 `true`이면, `nextCursor` 값을 다음 요청의 `nextCursor`에 넣어 호출합니다.\n\n- 응답의 `hasPrev`가 `true`이면, `prevCursor` 값을 이전 요청의 `prevCursor`에 넣어 호출합니다.\n\n- `nextCursor`와 `prevCursor`를 동시에 사용할 수 없습니다.\n\n## 필터링\n\n- `itemStatuses`: 아이템 상태로 필터링할 수 있습니다.\n\n- `productName`: 상품명 부분 검색을 지원합니다.\n\n- `productIds`: 특정 상품 ID로 필터링할 수 있습니다.\n\n- `itemIds`: 특정 아이템 ID로 필터링할 수 있습니다.","operationId":"searchItemsGroupByProduct","parameters":[{"name":"nextCursor","in":"query","description":"다음 페이지 커서","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"prevCursor","in":"query","description":"이전 페이지 커서","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"pageSize","in":"query","description":"페이지 크기 (기본값: 20, 최대: 50)","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"name":"itemStatuses","in":"query","description":"아이템 상태 필터","required":false,"schema":{"uniqueItems":true,"type":"array","items":{"type":"string","enum":["SOLD_OUT","PENALTY","SELLING","REVISION_REQUIRED","WAITING_FOR_SALE","REJECTED","INSPECTING"]}}},{"name":"productName","in":"query","description":"상품명 부분 검색","required":false,"schema":{"type":"string"}},{"name":"productIds","in":"query","description":"상품 ID 필터 (최대 100개)","required":false,"schema":{"uniqueItems":true,"type":"array","items":{"type":"integer","format":"int64"}}},{"name":"itemIds","in":"query","description":"아이템 ID 필터 (최대 500개)","required":false,"schema":{"uniqueItems":true,"type":"array","items":{"type":"integer","format":"int64"}}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/ProductItemsGroupByProductCursorFepResponse"}}}}}}}}}}}
```
## 단일 상품의 아이템 목록 조회 (커서 기반)
> 상품에 속한 아이템(옵션) 목록을 커서 기반으로 조회합니다.\
> \
> \## 페이지네이션\
> \
> \- 커서 기반 페이지네이션을 사용합니다.\
> \
> \- 첫 요청 시 \`cursorItemId\`를 비워서 호출합니다.\
> \
> \- 응답의 \`hasNext\`가 \`true\`이면, \`nextCursor\` 값을 다음 요청의 \`cursorItemId\`에 넣어 호출합니다.\
> \
> \- \`hasNext\`가 \`false\`이면 마지막 페이지입니다.\
> \
> \## 필터링\
> \
> \- \`itemStatuses\`: 아이템 상태로 필터링할 수 있습니다. 여러 상태를 동시에 지정할 수 있습니다.\
> \
> \- \`itemIds\`: 특정 아이템 ID로 필터링할 수 있습니다. 여러 ID를 동시에 지정할 수 있습니다.
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ListProductItemsFepResponse":{"required":["hasNext","items"],"type":"object","properties":{"items":{"type":"array","description":"아이템 목록","items":{"$ref":"#/components/schemas/ListProductItemsFepResponseItem"}},"hasNext":{"type":"boolean","description":"다음 페이지 존재 여부"},"nextCursor":{"type":"integer","description":"다음 페이지 커서 (다음 조회 시 cursorItemId로 전달)","format":"int64"}},"description":"상품 아이템 목록 조회 응답 (커서 기반)"},"ListProductItemsFepResponseItem":{"required":["isAdultProduct","isMainOption","itemId","itemName","originPrice","quantity","rejectReasons","salePrice","status"],"type":"object","properties":{"itemId":{"type":"integer","description":"아이템 ID","format":"int64"},"itemName":{"type":"string","description":"아이템명"},"quantity":{"type":"integer","description":"재고 수량","format":"int32"},"rejectReasons":{"type":"array","description":"검수 반려 사유 목록","items":{"$ref":"#/components/schemas/ListProductItemsFepResponseRejectReason"}},"isMainOption":{"type":"boolean","description":"대표 옵션 여부"},"status":{"$ref":"#/components/schemas/ListProductItemsFepResponseStatus"},"originPrice":{"type":"integer","description":"정상가","format":"int32"},"salePrice":{"type":"integer","description":"판매가","format":"int32"},"isAdultProduct":{"type":"boolean","description":"청소년 구매 불가 상품 여부"}},"description":"상품 아이템 항목"},"ListProductItemsFepResponseRejectReason":{"required":["message","title"],"type":"object","properties":{"title":{"type":"string","description":"반려 사유 제목"},"message":{"type":"string","description":"반려 사유 상세 메시지"}},"description":"검수 반려 사유"},"ListProductItemsFepResponseStatus":{"required":["code","label"],"type":"object","properties":{"code":{"type":"string","description":"상태 코드","enum":["SOLD_OUT","PENALTY","SELLING","WAITING_FOR_SALE","REVISION_REQUIRED","REJECTED","INSPECTING"]},"label":{"type":"string","description":"상태 라벨"}},"description":"아이템 상태 요약"}}},"paths":{"/api/v3/shopping-fep/products/{productId}/product-items":{"get":{"tags":["상품 Public Controller"],"summary":"단일 상품의 아이템 목록 조회 (커서 기반)","description":"상품에 속한 아이템(옵션) 목록을 커서 기반으로 조회합니다.\n\n## 페이지네이션\n\n- 커서 기반 페이지네이션을 사용합니다.\n\n- 첫 요청 시 `cursorItemId`를 비워서 호출합니다.\n\n- 응답의 `hasNext`가 `true`이면, `nextCursor` 값을 다음 요청의 `cursorItemId`에 넣어 호출합니다.\n\n- `hasNext`가 `false`이면 마지막 페이지입니다.\n\n## 필터링\n\n- `itemStatuses`: 아이템 상태로 필터링할 수 있습니다. 여러 상태를 동시에 지정할 수 있습니다.\n\n- `itemIds`: 특정 아이템 ID로 필터링할 수 있습니다. 여러 ID를 동시에 지정할 수 있습니다.","operationId":"getProductItemsByProduct_1","parameters":[{"name":"productId","in":"path","description":"상품 식별용 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"cursorItemId","in":"query","description":"커서 아이템 ID","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"pageSize","in":"query","description":"페이지 크기 (기본값: 20, 최대: 50)","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"name":"itemStatuses","in":"query","description":"아이템 상태 필터","required":false,"schema":{"uniqueItems":true,"type":"array","items":{"type":"string","enum":["SOLD_OUT","PENALTY","SELLING","REVISION_REQUIRED","WAITING_FOR_SALE","REJECTED","INSPECTING"]}}},{"name":"itemIds","in":"query","description":"아이템 ID 필터 (최대 100개)","required":false,"schema":{"uniqueItems":true,"type":"array","items":{"type":"integer","format":"int64"}}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/ListProductItemsFepResponse"}}}}}}}}}}}
```
## 상품 정보 노출 상태 보이기로 변경
> 상품의 노출 상태를 '보이기'로 변경합니다.
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ShowProductBody":{"required":["productId"],"type":"object","properties":{"productId":{"type":"integer","description":"상품 ID","format":"int64"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"상품 보이기 요청"}}},"paths":{"/api/v3/shopping-fep/products/show":{"post":{"tags":["상품 Public Controller"],"summary":"상품 정보 노출 상태 보이기로 변경","description":"상품의 노출 상태를 '보이기'로 변경합니다.","operationId":"showProduct_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowProductBody"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```
## 상품 정보 노출 상태 숨기기로 변경
> 상품의 노출 상태를 '숨기기'로 변경합니다.
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"HideProductBody":{"required":["productId"],"type":"object","properties":{"productId":{"type":"integer","description":"상품 ID","format":"int64"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"상품 숨기기 요청"}}},"paths":{"/api/v3/shopping-fep/products/hide":{"post":{"tags":["상품 Public Controller"],"summary":"상품 정보 노출 상태 숨기기로 변경","description":"상품의 노출 상태를 '숨기기'로 변경합니다.","operationId":"hideProduct_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HideProductBody"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```
## 상품 옵션 판매가 수정
> 특정 상품 옵션의 판매가를 수정합니다.\
> \
> \## 가격 구조\
> \
> \- \*\*정상가\*\*: 권장소비자가격(도서는 정가) 또는 자사몰/온라인 판매 채널에서 판매 이력이 있는 가격\
> \- \*\*판매가\*\*: 실제로 소비자에게 상품을 판매하는 가격으로 쿠폰 등의 할인이 포함되지 않은 가격\
> \
> \## 상품정보 변경 시, API 호출 순서\
> \
> 1\. 상품 정보 조회 API로 상품 아이템 ID를 획득\
> 2\. 해당 상품 아이템 ID를 활용하여 판매가 수정 API 호출
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ChangeOptionSalePriceFepRequest":{"required":["productId","salePrice"],"type":"object","properties":{"productId":{"type":"integer","description":"상품 식별용 ID","format":"int64"},"salePrice":{"type":"integer","description":"판매가 (셀러가 등록한 가격)\n\n- 최소 1원 이상\n- 정상가(originPrice) 이하여야 합니다","format":"int32"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"상품 옵션 판매가 수정 요청"}}},"paths":{"/api/v3/shopping-fep/product-items/{productItemId}/sale-price":{"put":{"tags":["상품 Public Controller"],"summary":"상품 옵션 판매가 수정","description":"특정 상품 옵션의 판매가를 수정합니다.\n\n## 가격 구조\n\n- **정상가**: 권장소비자가격(도서는 정가) 또는 자사몰/온라인 판매 채널에서 판매 이력이 있는 가격\n- **판매가**: 실제로 소비자에게 상품을 판매하는 가격으로 쿠폰 등의 할인이 포함되지 않은 가격\n\n## 상품정보 변경 시, API 호출 순서\n\n1. 상품 정보 조회 API로 상품 아이템 ID를 획득\n2. 해당 상품 아이템 ID를 활용하여 판매가 수정 API 호출","operationId":"changeSalePrice","parameters":[{"name":"productItemId","in":"path","description":"상품 아이템 ID (상품 옵션 ID)","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeOptionSalePriceFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","BAD_REQUEST","NOT_FOUND","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```
## 상품 옵션 정상가 수정
> 특정 상품 옵션의 정상가를 수정합니다.\
> \
> \## 가격 구조\
> \
> \- \*\*정상가\*\*: 권장소비자가격(도서는 정가) 또는 자사몰/온라인 판매 채널에서 판매 이력이 있는 가격\
> \- \*\*판매가\*\*: 실제로 소비자에게 상품을 판매하는 가격으로 쿠폰 등의 할인이 포함되지 않은 가격\
> \
> \## 상품정보 변경 시, API 호출 순서\
> \
> 1\. 상품 정보 조회 API로 상품 아이템 ID를 획득\
> 2\. 해당 상품 아이템 ID를 활용하여 정상가 수정 API 호출
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ChangeOptionOriginPriceFepRequest":{"required":["originPrice","productId"],"type":"object","properties":{"productId":{"type":"integer","description":"상품 식별용 ID","format":"int64"},"originPrice":{"type":"integer","description":"변경할 정상가 가격","format":"int32"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"상품 옵션 정상가 수정 요청"}}},"paths":{"/api/v3/shopping-fep/product-items/{productItemId}/origin-price":{"put":{"tags":["상품 Public Controller"],"summary":"상품 옵션 정상가 수정","description":"특정 상품 옵션의 정상가를 수정합니다.\n\n## 가격 구조\n\n- **정상가**: 권장소비자가격(도서는 정가) 또는 자사몰/온라인 판매 채널에서 판매 이력이 있는 가격\n- **판매가**: 실제로 소비자에게 상품을 판매하는 가격으로 쿠폰 등의 할인이 포함되지 않은 가격\n\n## 상품정보 변경 시, API 호출 순서\n\n1. 상품 정보 조회 API로 상품 아이템 ID를 획득\n2. 해당 상품 아이템 ID를 활용하여 정상가 수정 API 호출","operationId":"changeOriginPrice_1","parameters":[{"name":"productItemId","in":"path","description":"상품 아이템 ID (상품 옵션 ID)","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeOptionOriginPriceFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","BAD_REQUEST","NOT_FOUND","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```
## 상품 구매 개수 제한 생성
> 특정 상품 또는 옵션에 대한 구매 개수 제한을 생성합니다.\
> \
> \## 제한 설정\
> \
> \- \`startTs\`, \`endTs\`: 구매 제한이 적용되는 기간 설정합니다. (ISO-8601 형식)\
> \- \`maxQuantityPerUser\`: 기간 내 사용자 1인당 구매 가능한 최대 수량입니다.\
> \- \`productItemIds\`: 여러 옵션에 대해 동일한 제한 적용 시 배열로 전달합니다.\
> \
> \## 주의사항\
> \
> \- 동일한 옵션들은 같은 \`purchaseLimitGroupId\`로 묶여서 관리됩니다.\
> \- \`startTs\`는 \`endTs\`보다 이전이어야 함
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CreatePurchaseLimitFepRequest":{"required":["endTs","maxQuantityPerUser","productId","productItemIds","startTs"],"type":"object","properties":{"productId":{"type":"integer","description":"상품 식별용 ID\n\n- 검수 승인 완료된 상품만 가능","format":"int64"},"productItemIds":{"type":"array","description":"옵션 식별용 ID 목록 (1개 이상 필수)","items":{"type":"integer","description":"옵션 식별용 ID 목록 (1개 이상 필수)","format":"int64"}},"startTs":{"type":"string","description":"시작일자\n\n- 익일 이후만 가능 (당일 및 과거 날짜 불가)","format":"date-time"},"endTs":{"type":"string","description":"종료일자\n\n- 시작일자 이후여야 합니다\n- 동일 옵션에 대해 기간이 겹치는 구매 제한이 이미 존재하면 생성 불가","format":"date-time"},"maxQuantityPerUser":{"type":"integer","description":"제한할 구매 갯수 (1 이상의 양수)","format":"int32"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"구매 수량 제한 생성 요청"},"CreatePurchaseLimitFepResponse":{"required":["items"],"type":"object","properties":{"items":{"type":"array","description":"생성된 구매 수량 제한 목록","items":{"$ref":"#/components/schemas/CreatePurchaseLimitItemFepResponse"}}},"description":"구매 수량 제한 생성 응답"},"CreatePurchaseLimitItemFepResponse":{"required":["endTs","maxQuantityPerUser","productId","purchaseLimitGroupId","startTs"],"type":"object","properties":{"purchaseLimitGroupId":{"type":"integer","description":"구매 수량 제한 그룹 ID","format":"int64"},"productId":{"type":"integer","description":"상품 식별용 ID","format":"int64"},"productItemId":{"type":"integer","description":"옵션 식별용 ID","format":"int64"},"maxQuantityPerUser":{"type":"integer","description":"사용자당 최대 구매 수량","format":"int32"},"description":{"type":"string","description":"구매 수량 제한 설명"},"startTs":{"type":"string","description":"시작일시","format":"date-time"},"endTs":{"type":"string","description":"종료일시","format":"date-time"}},"description":"구매 수량 제한 생성 항목"}}},"paths":{"/api/v3/shopping-fep/purchase-limits":{"post":{"tags":["상품 구매 개수 제한 Public Controller"],"summary":"상품 구매 개수 제한 생성","description":"특정 상품 또는 옵션에 대한 구매 개수 제한을 생성합니다.\n\n## 제한 설정\n\n- `startTs`, `endTs`: 구매 제한이 적용되는 기간 설정합니다. (ISO-8601 형식)\n- `maxQuantityPerUser`: 기간 내 사용자 1인당 구매 가능한 최대 수량입니다.\n- `productItemIds`: 여러 옵션에 대해 동일한 제한 적용 시 배열로 전달합니다.\n\n## 주의사항\n\n- 동일한 옵션들은 같은 `purchaseLimitGroupId`로 묶여서 관리됩니다.\n- `startTs`는 `endTs`보다 이전이어야 함","operationId":"create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseLimitFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","BAD_REQUEST","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/CreatePurchaseLimitFepResponse"}}}}}}}}}}}
```
## 상품 구매 개수 제한 조회
> 특정 상품에 설정된 구매 개수 제한을 조회합니다.\
> \
> \## 응답 정보\
> \
> \- \`purchaseLimitGroupId\`: 동일한 구매 개수 제한 그룹에 속한 옵션들은 같은 ID를 가집니다.
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"GetPurchaseLimitListFepResponse":{"required":["items"],"type":"object","properties":{"items":{"type":"array","description":"구매 수량 제한 목록","items":{"$ref":"#/components/schemas/GetPurchaseLimitFepResponse"}}},"description":"구매 수량 제한 목록 조회 응답"},"GetPurchaseLimitFepResponse":{"required":["endTs","maxQuantityPerUser","productId","purchaseLimitGroupId","startTs"],"type":"object","properties":{"purchaseLimitGroupId":{"type":"integer","description":"구매 수량 제한 그룹 ID","format":"int64"},"productId":{"type":"integer","description":"상품 식별용 ID","format":"int64"},"productItemId":{"type":"integer","description":"옵션 식별용 ID","format":"int64"},"maxQuantityPerUser":{"type":"integer","description":"사용자당 최대 구매 수량","format":"int32"},"description":{"type":"string","description":"구매 수량 제한 설명"},"startTs":{"type":"string","description":"시작일시","format":"date-time"},"endTs":{"type":"string","description":"종료일시","format":"date-time"}},"description":"구매 수량 제한 상세"}}},"paths":{"/api/v3/shopping-fep/purchase-limits/product-ids/{productId}":{"get":{"tags":["상품 구매 개수 제한 Public Controller"],"summary":"상품 구매 개수 제한 조회","description":"특정 상품에 설정된 구매 개수 제한을 조회합니다.\n\n## 응답 정보\n\n- `purchaseLimitGroupId`: 동일한 구매 개수 제한 그룹에 속한 옵션들은 같은 ID를 가집니다.","operationId":"get","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/GetPurchaseLimitListFepResponse"}}}}}}}}}}}
```
## 상품 구매 개수 제한 제거
> 설정된 구매 개수 제한을 삭제합니다.\
> \
> \## 삭제 방법\
> \
> \- \`purchaseLimitGroupId\`: 조회 API에서 확인한 구매 개수 제한 그룹 ID입니다.\
> \- \`productItemId\`: 삭제할 옵션 ID입니다.\
> \- 여러 옵션의 제한을 한 번에 삭제 가능합니다. (배열로 전달)\
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DeletePurchaseLimitFepRequest":{"required":["purchaseLimitGroups"],"type":"object","properties":{"purchaseLimitGroups":{"type":"array","description":"삭제할 구매 수량 제한 목록","items":{"$ref":"#/components/schemas/DeletePurchaseLimitGroupFepItem"}},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"구매 수량 제한 삭제 요청"},"DeletePurchaseLimitGroupFepItem":{"required":["productItemId","purchaseLimitGroupId"],"type":"object","properties":{"productItemId":{"type":"integer","description":"옵션 ID","format":"int64"},"purchaseLimitGroupId":{"type":"integer","description":"상품 구매 갯수 제한 ID","format":"int64"}},"description":"구매 수량 제한 삭제 항목"}}},"paths":{"/api/v3/shopping-fep/purchase-limits":{"delete":{"tags":["상품 구매 개수 제한 Public Controller"],"summary":"상품 구매 개수 제한 제거","description":"설정된 구매 개수 제한을 삭제합니다.\n\n## 삭제 방법\n\n- `purchaseLimitGroupId`: 조회 API에서 확인한 구매 개수 제한 그룹 ID입니다.\n- `productItemId`: 삭제할 옵션 ID입니다.\n- 여러 옵션의 제한을 한 번에 삭제 가능합니다. (배열로 전달)\n\n","operationId":"delete","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePurchaseLimitFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","BAD_REQUEST","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```
## 상품 옵션 정상 재고 수량 변경
> 특정 상품 옵션의 정상 재고 수량을 변경합니다.\
> \
> \## 주의사항\
> \
> \- 재고 수량은 음수가 될 수 없습니다.\
> \- 재고 수량을 0으로 설정하면 품절 처리됩니다. \
> \- 품절 상태의 상품의 재고 수량을 1 이상으로 설정하면 품절 취소됩니다.
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ChangeOptionRemainingCountFepRequest":{"required":["productId","remainingCount"],"type":"object","properties":{"productId":{"type":"integer","description":"상품 식별용 ID","format":"int64"},"remainingCount":{"minimum":0,"type":"integer","description":"현재 판매 가능한 재고 수량 (0 이상)","format":"int32"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}}}}},"paths":{"/api/v3/shopping-fep/product-items/{productItemId}/stocks/normal-stock/remaining-count":{"put":{"tags":["상품 Public Controller"],"summary":"상품 옵션 정상 재고 수량 변경","description":"특정 상품 옵션의 정상 재고 수량을 변경합니다.\n\n## 주의사항\n\n- 재고 수량은 음수가 될 수 없습니다.\n- 재고 수량을 0으로 설정하면 품절 처리됩니다. \n- 품절 상태의 상품의 재고 수량을 1 이상으로 설정하면 품절 취소됩니다. ","operationId":"changeOptionRemainingCount_1","parameters":[{"name":"productItemId","in":"path","description":"상품 아이템 ID (상품 옵션 ID)","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeOptionRemainingCountFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드"},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```
## 택배사 목록 조회
> 사용 가능한 택배사 목록을 조회합니다.\
> \
> \## 사용처\
> \
> \- 상품 등록/수정 시 배송정책의 \`deliveryCompanyId\` 파라미터에 사용할 택배사 ID를 확인할 수 있습니다
```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ListDeliveryCompaniesFepResponse":{"required":["deliveryCompanies"],"type":"object","properties":{"deliveryCompanies":{"type":"array","description":"택배사 목록","items":{"$ref":"#/components/schemas/DeliveryCompanyFepResponse"}}},"description":"택배사 목록 조회 응답"},"DeliveryCompanyFepResponse":{"required":["code","id","isEnabled","name"],"type":"object","properties":{"id":{"type":"integer","description":"택배사 ID","format":"int64"},"name":{"type":"string","description":"택배사 명"},"code":{"type":"string","description":"배송 코드"},"isEnabled":{"type":"boolean","description":"사용 여부"}},"description":"택배사 정보"}}},"paths":{"/api/v3/shopping-fep/delivery-companies":{"get":{"tags":["상품 Public Controller"],"summary":"택배사 목록 조회","description":"사용 가능한 택배사 목록을 조회합니다.\n\n## 사용처\n\n- 상품 등록/수정 시 배송정책의 `deliveryCompanyId` 파라미터에 사용할 택배사 ID를 확인할 수 있습니다","operationId":"listDeliveryCompanies_1","responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["COMMON_ERROR","INTERNAL_SERVER_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/ListDeliveryCompaniesFepResponse"}}}}}}}}}}}
```
> ### API 연동 중 문의사항이나 개선 제안이 있으신가요?
{% hint style="info" %}
토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 [연동/개발 문의](https://discord.gg/xPz6H9NZ3P)에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://shopping-docs.toss.im/dev/api-2/product.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.