> For the complete documentation index, see [llms.txt](https://shopping-docs.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shopping-docs.toss.im/dev/api-2/product.md).

# 상품

## 상품 등록 v3

> 상품을 등록합니다.\
> \
> \## 구매 옵션\
> \
> \- 옵션별 구매 옵션은 \`salesOptions\`에 옵션 이름(\`key\`)·값(\`value\`)으로 입력합니다\
> \
> \- 옵션 이름은 카테고리 제약사항의 구매 옵션 이름과 정확히 일치해야 합니다\
> \
> \## 주의사항\
> \
> \- 상품 등록/수정 시에는 \*\*초당 30건 이하\*\*로 요청해주셔야 합니다\
> \
> \- 등록 결과로 상품 ID만 반환합니다. 옵션(아이템) ID는 상품 조회 v3 API로 확인해주세요\
> \
> \- 카테고리 제약사항은 주기적으로 수정될 수 있으므로, API를 호출하여 제약사항을 주기적으로 확인 후 기입되도록 구현 부탁드립니다\
> \
> \## 상품 등록(v2)에서 달라진 점\
> \
> \- 필드 이름: \`name\` → \`productName\`, \`categoryId\` → \`leafCategoryId\`, \`managementCode\` → \`productManagementCode\`, \`exposure.searchKeywords\` → \`searchTags\`, \`notice\` → \`productMandatoryNotice\`(\`categoryCode\` → \`mandatoryNoticeCode\`, \`items\` → \`mandatoryNoticeItems\`)\
> \
> \- 옵션: \`stocks\` → \`items\`, \`options\[{groupName, valueName}]\` → \`salesOptions\[{key, value}]\`, \`remainingCount\` → \`quantity\`, \`salePrice\` → \`regularSalePrice\`, \`isMainPrice\` → \`isMainOption\`, \`managementCode\` → \`itemManagementCode\`, \`images\` → \`itemThumbnails\`. 옵션은 1개 이상이어야 합니다\
> \
> \- 이미지: \`images\[{type, url, html, order}]\` 대신 \`productThumbnails\`, \`productDescriptionImages\`, \`productDescriptionHtml\`로 나눠 입력하고, 배열 순서가 노출 순서입니다. 같은 이미지 URL을 여러 번 보내면 합치지 않고 그대로 등록됩니다\
> \
> \- 배송불가지역: \`isJejuAndIslandsMountainsDelivery\`는 받지 않으며 \`deliveryBlockedRegionPolicyId\`가 필수입니다 (1: 전 지역 배송 가능, 3: 제주 배송 불가, 5: 도서산간 배송 불가, 7: 제주/도서산간 배송 불가)\
> \
> \- 받지 않는 필드: \`exposure.description\`, \`exposure.serialNumber\`, \`exchangeReturnPolicy.applicationMethodDescription\`, \`stocks\[].isHide\`, \`partnerName\`

```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":{"RegisterProductV3FepRequest":{"required":["deliveryPolicy","exchangeReturnPolicy","isTaxFree","items","leafCategoryId","productMandatoryNotice","productName","productThumbnails","searchTags"],"type":"object","properties":{"productName":{"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, 협력사"},"productManagementCode":{"type":"string","description":"판매자가 상품을 관리하려고 사용하는 코드 (최대 100자)"},"isTaxFree":{"type":"boolean","description":"면세 상품 여부\n\n- true: 면세\n- false: 과세"},"isCultureDeduction":{"type":"boolean","description":"문화비 소득공제 적용 여부. 생략 시 false"},"searchTags":{"type":"array","description":"상품 검색에 사용되는 태그 목록\n\n- 없으면 빈 배열로 요청\n- 허용 정규식: [0-9a-zA-Z가-힣]{1,10}","items":{"type":"string","description":"상품 검색에 사용되는 태그 목록\n\n- 없으면 빈 배열로 요청\n- 허용 정규식: [0-9a-zA-Z가-힣]{1,10}"}},"leafCategoryId":{"type":"integer","description":"상품 카테고리 ID\n\n- 카테고리 중에 isLeaf=true인 최하위 카테고리 ID만 가능","format":"int64"},"items":{"maxItems":300,"minItems":1,"type":"array","description":"상품 옵션(아이템) 목록 (1~300개)","items":{"$ref":"#/components/schemas/RegisterProductItemV3FepRequest"}},"productThumbnails":{"type":"array","description":"상품 썸네일 이미지 목록 (1~10개). 배열 순서가 노출 순서입니다.\n\n- 최소크기 600x600, 비율 1:1, 용량 2MB 이하, JPG/PNG\n- 이미지 URL은 기존 사용하시는 사이트 이미지 URL을 입력해주시면 내부적으로 다운로드하여 등록합니다. 다운로드 실패 시 상품 등록에 실패할 수 있습니다.","items":{"$ref":"#/components/schemas/ProductThumbnailV3FepRequest"}},"productDescriptionImages":{"type":"array","description":"상품 상세 이미지 목록 (1~50개). 배열 순서가 노출 순서입니다.\n\n- productDescriptionHtml과 둘 중 하나만 입력해야 합니다\n- 최소가로크기 600, 용량 5MB 이하, JPG/PNG/GIF","items":{"$ref":"#/components/schemas/ProductDescriptionImageV3FepRequest"}},"productDescriptionHtml":{"$ref":"#/components/schemas/ProductDescriptionHtmlV3FepRequest"},"deliveryPolicy":{"$ref":"#/components/schemas/ProductDeliveryPolicyV3FepRequest"},"exchangeReturnPolicy":{"$ref":"#/components/schemas/ProductExchangeReturnPolicyV3FepRequest"},"productMandatoryNotice":{"$ref":"#/components/schemas/ProductMandatoryNoticeV3FepRequest"},"bookInfo":{"$ref":"#/components/schemas/ProductBookInfoV3FepRequest"}},"description":"상품 등록 v3 요청"},"RegisterProductItemV3FepRequest":{"required":["isMainOption","originPrice","quantity","regularSalePrice","salesOptions"],"type":"object","properties":{"quantity":{"type":"integer","description":"현재 판매할 수 있는 재고 수량\n\n- 0 이상 입력 가능\n- 0인 경우 품절 상태로 등록됩니다","format":"int32"},"originPrice":{"type":"integer","description":"정상가. 권장소비자가격이나 자사몰/온라인 채널에서 판매 이력이 있는 가격\n\n- 최소 1원 이상","format":"int32"},"regularSalePrice":{"type":"integer","description":"판매가. 실제로 소비자에게 판매하는 가격\n\n- 최소 1원 이상\n- 정상가(originPrice) 이하여야 합니다","format":"int32"},"salesOptions":{"type":"array","description":"구매 옵션 목록 (옵션 이름·값)\n\n- 카테고리 제약사항에 따라 제한됩니다\n- 제약사항이 있는 경우 반드시 제약사항에 따라 입력해야 하며 그 외 옵션은 입력할 수 없습니다","items":{"$ref":"#/components/schemas/ProductItemSalesOptionV3FepRequest"}},"itemManagementCode":{"type":"string","description":"옵션 관리 코드 (최대 100자)"},"itemThumbnails":{"type":"array","description":"옵션 이미지 목록. 배열 순서가 노출 순서입니다.","items":{"$ref":"#/components/schemas/ProductItemThumbnailV3FepRequest"}},"isMainOption":{"type":"boolean","description":"대표 옵션 여부 (true: 대표 가격으로 노출)\n\n- 반드시 1개만 true여야 합니다"},"isAdultProduct":{"type":"boolean","description":"청소년 구매불가 상품 여부 (true: 청소년 구매불가, false: 구매 가능). 생략 시 false"}},"description":"상품 옵션(아이템) 정보"},"ProductItemSalesOptionV3FepRequest":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string","description":"구매 옵션 이름\n\n- 카테고리 제약사항 categorySalesOptions의 key와 정확히 일치해야 합니다\n- isOption = false일 경우 필수\n- isOneOfRequiredGroup = true인 그룹 중 최소 1개 이상 반드시 포함해야 등록 가능"},"value":{"type":"string","description":"구매 옵션 값\n\n- valueCandidates에 포함되는 값만 허용 (valueCandidates가 빈 배열일 경우 자유)\n- unitValues가 있을 경우 해당 단위를 붙여 입력해야 합니다 (예: 500ml)\n- keyComment와 valueComment가 있을 경우 해당 내용을 참조하여 입력해야 합니다"}},"description":"구매 옵션 (옵션 이름·값)"},"ProductItemThumbnailV3FepRequest":{"required":["itemThumbnailUrl"],"type":"object","properties":{"itemThumbnailUrl":{"type":"string","description":"옵션 이미지 URL (최대 255자)"}},"description":"옵션 이미지"},"ProductThumbnailV3FepRequest":{"required":["productThumbnailUrl"],"type":"object","properties":{"productThumbnailUrl":{"type":"string","description":"상품 썸네일 이미지 URL (최대 255자)"}},"description":"상품 썸네일 이미지"},"ProductDescriptionImageV3FepRequest":{"required":["productDescriptionUrl"],"type":"object","properties":{"productDescriptionUrl":{"type":"string","description":"상품 상세 이미지 URL (최대 255자)"}},"description":"상품 상세 이미지"},"ProductDescriptionHtmlV3FepRequest":{"required":["html"],"type":"object","properties":{"html":{"type":"string","description":"상품 상세 HTML. 서버에서 sanitization 후 저장합니다."}},"description":"상품 상세 HTML"},"ProductDeliveryPolicyV3FepRequest":{"required":["deliveryBlockedRegionPolicyId","deliveryFee","deliveryFeeType","deliveryMethod","islandsMountainsDeliveryFee","jejuDeliveryFee","minimumPurchasePrice"],"type":"object","properties":{"deliveryType":{"type":"string","description":"배송 타입. 생략 시 NORMAL","enum":["NORMAL","PREFERRED_DATE"]},"deliveryMethod":{"type":"string","description":"배송 방식","enum":["NORMAL","TODAY_DELIVERY"]},"deliveryDeadline":{"type":"string","description":"출고 마감 시각 (HH:mm, 30분 단위)\n\n- 오늘 출발(TODAY_DELIVERY)일 때 필수입니다\n- 일반 배송(NORMAL)이면 무시됩니다"},"preparationDays":{"type":"integer","description":"상품 준비 기간 (일, 최대 14일)\n\n- 일반 배송(NORMAL)일 때 미입력 시 기본값 3으로 설정됩니다\n- 오늘 출발(TODAY_DELIVERY)이면 무시됩니다","format":"int32"},"deliveryLocationId":{"type":"integer","description":"배송비 묶음 그룹 ID\n\n- null이면 묶음배송 불가","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"},"jejuDeliveryFee":{"type":"integer","description":"제주도 추가 배송비","format":"int32"},"islandsMountainsDeliveryFee":{"type":"integer","description":"도서 산간 추가 배송비","format":"int32"},"deliveryCompanyId":{"type":"integer","description":"택배사 ID. 택배사 목록 조회 API 참고","format":"int64"},"preferredDateType":{"type":"string","description":"희망일 배송 기준 타입. 희망일 배송(PREFERRED_DATE)에서 사용","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"},"deliveryBlockedRegionPolicyId":{"type":"integer","description":"배송불가지역 정책 ID\n\n- 1: 제주/도서산간 포함 전 지역 배송 가능\n- 3: 제주 배송 불가\n- 5: 도서산간 배송 불가\n- 7: 제주/도서산간 배송 불가\n- 상품 수정 시에는 상품 조회 v3 응답의 값을 그대로 보내면 기존 정책이 유지됩니다","format":"int64"}},"description":"배송 정책"},"ProductExchangeReturnPolicyV3FepRequest":{"required":["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"},"applicationTermDescription":{"type":"string","description":"교환,환불 신청 가능 기간 설명 (1~500자)"},"isReturnRequired":{"type":"boolean","description":"교환/반품 시 상품 회수 여부 (true: 회수 필요, false: 회수 불필요). 생략 시 true"},"returnContractSlotNum":{"type":"integer","description":"반품 회수 계약 슬롯 번호 (0~20, 0은 기본 택배사)\n\n- 반품 회수 계약 슬롯 조회 API 참조\n- 생략하거나 null이면 슬롯을 지정하지 않습니다. **상품 수정 시 생략하면 기존에 지정한 슬롯이 해제됩니다.** 유지하려면 상품 조회 v3 응답의 returnContractSlotNum을 그대로 보내주세요","format":"int32"}},"description":"교환/반품 정책"},"ProductMandatoryNoticeV3FepRequest":{"required":["mandatoryNoticeCode","mandatoryNoticeItems"],"type":"object","properties":{"mandatoryNoticeCode":{"type":"string","description":"상품 정보제공 고시 카테고리 코드\n\n- 정보제공 고시를 위한 카테고리 목록 조회 API 참조"},"mandatoryNoticeItems":{"type":"array","description":"상품 정보제공 고시 항목 목록\n\n- 정보제공 고시를 위한 항목 조회 API 참조","items":{"$ref":"#/components/schemas/ProductMandatoryNoticeItemV3FepRequest"}}},"description":"상품 정보제공 고시"},"ProductMandatoryNoticeItemV3FepRequest":{"required":["content","id"],"type":"object","properties":{"id":{"type":"integer","description":"정보제공 고시 항목 ID","format":"int64"},"content":{"type":"string","description":"고시 항목 내용 (판매자 입력 정보, 1~4000자)"}},"description":"정보제공 고시 항목"},"ProductBookInfoV3FepRequest":{"type":"object","properties":{"bookCodeType":{"type":"string","description":"도서 코드 타입","enum":["ISBN","ISSN"]},"bookCodeValue":{"type":"string","description":"ISBN/ISSN 코드값 13자리. 하이픈 포함 입력도 가능합니다."},"isIndependentPublication":{"type":"boolean","description":"독립출판물 등 ISBN/ISSN 예외 여부. 생략 시 false"},"author":{"type":"string","description":"저자. 최대 64자"},"publisher":{"type":"string","description":"출판사. 최대 64자"}},"description":"도서 정보"},"RegisterProductResponse":{"required":["id"],"type":"object","properties":{"id":{"type":"integer","description":"상품 ID","format":"int64"}},"description":"상품 등록 응답"}}},"paths":{"/api/v3/shopping-fep/products/v3":{"post":{"tags":["상품 Public Controller"],"summary":"상품 등록 v3","description":"상품을 등록합니다.\n\n## 구매 옵션\n\n- 옵션별 구매 옵션은 `salesOptions`에 옵션 이름(`key`)·값(`value`)으로 입력합니다\n\n- 옵션 이름은 카테고리 제약사항의 구매 옵션 이름과 정확히 일치해야 합니다\n\n## 주의사항\n\n- 상품 등록/수정 시에는 **초당 30건 이하**로 요청해주셔야 합니다\n\n- 등록 결과로 상품 ID만 반환합니다. 옵션(아이템) ID는 상품 조회 v3 API로 확인해주세요\n\n- 카테고리 제약사항은 주기적으로 수정될 수 있으므로, API를 호출하여 제약사항을 주기적으로 확인 후 기입되도록 구현 부탁드립니다\n\n## 상품 등록(v2)에서 달라진 점\n\n- 필드 이름: `name` → `productName`, `categoryId` → `leafCategoryId`, `managementCode` → `productManagementCode`, `exposure.searchKeywords` → `searchTags`, `notice` → `productMandatoryNotice`(`categoryCode` → `mandatoryNoticeCode`, `items` → `mandatoryNoticeItems`)\n\n- 옵션: `stocks` → `items`, `options[{groupName, valueName}]` → `salesOptions[{key, value}]`, `remainingCount` → `quantity`, `salePrice` → `regularSalePrice`, `isMainPrice` → `isMainOption`, `managementCode` → `itemManagementCode`, `images` → `itemThumbnails`. 옵션은 1개 이상이어야 합니다\n\n- 이미지: `images[{type, url, html, order}]` 대신 `productThumbnails`, `productDescriptionImages`, `productDescriptionHtml`로 나눠 입력하고, 배열 순서가 노출 순서입니다. 같은 이미지 URL을 여러 번 보내면 합치지 않고 그대로 등록됩니다\n\n- 배송불가지역: `isJejuAndIslandsMountainsDelivery`는 받지 않으며 `deliveryBlockedRegionPolicyId`가 필수입니다 (1: 전 지역 배송 가능, 3: 제주 배송 불가, 5: 도서산간 배송 불가, 7: 제주/도서산간 배송 불가)\n\n- 받지 않는 필드: `exposure.description`, `exposure.serialNumber`, `exchangeReturnPolicy.applicationMethodDescription`, `stocks[].isHide`, `partnerName`","operationId":"registerProductV3","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterProductV3FepRequest"}}},"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","REQUEST_FAILED","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/RegisterProductResponse"}}}}}}}}}}}
```

## 상품 조회 v3

> 상품 ID를 이용하여 상품 정보를 조회합니다.\
> \
> \## 상품 수정 v3와 함께 쓰기\
> \
> \- 응답은 상품 수정 v3 요청과 같은 필드 이름·구조입니다. 바꿀 값만 고쳐 그대로 수정 요청에 보낼 수 있습니다\
> \
> \- 옵션의 \`productItemId\`, 구매 옵션(\`salesOptions\`), \`deliveryBlockedRegionPolicyId\`, \`returnContractSlotNum\`은 수정 요청에 그대로 보내주세요\
> \
> \- 특히 \`exchangeReturnPolicy.returnContractSlotNum\`을 빼고 보내면 반품 회수 계약 슬롯 지정이 해제됩니다\
> \
> \- 정보제공 고시(\`productMandatoryNotice\`)가 없는 상품은 수정 요청 시 고시 정보를 채워 보내주세요\
> \
> \- 등록/수정 직후에는 변경 내용이 잠시 반영되지 않을 수 있습니다. 직후 조회 결과로 바로 수정하면 방금 추가한 옵션이 빠져 삭제 처리될 수 있으니, 잠시 후 다시 조회한 결과를 사용해주세요\
> \
> \## 이미지 출처 필터\
> \
> \- \`imageSource\`로 응답에 포함할 이미지를 출처별로 필터링할 수 있습니다\
> \
> \- 생략 시 \`ALL\`로 동작하며 전체 이미지를 반환합니다\
> \
> \- 수정 요청에 쓰려면 \`ALL\`로 조회해주세요\
> \
> \## 상품 조회(v2)에서 달라진 점\
> \
> \- 필드 이름은 상품 등록·수정 v3와 같습니다 (\`stocks\` → \`items\`, \`itemId\` → \`productItemId\`, \`constraintTemplateId\` → \`productConstraintTemplateId\` 등)\
> \
> \- 배송불가지역은 \`isJejuAndIslandsMountainsDelivery\` 대신 \`deliveryPolicy.deliveryBlockedRegionPolicyId\`로 내려줍니다\
> \
> \- 반품 회수 계약 슬롯은 \`returnContractSlot\` 객체 대신 \`exchangeReturnPolicy.returnContractSlotNum\`으로 내려줍니다. 계약 정보는 반품 회수 계약 슬롯 조회 API로 확인해주세요\
> \
> \- 상품 단위 옵션 목록(\`options\`, 옵션 이름별 값 목록)은 내려주지 않습니다. 옵션 이름·값은 옵션별 \`items\[].salesOptions\`로 확인해주세요\
> \
> \- 새로 내려주는 값: 반려 사유 대상 유형(\`rejectionReasons\[].type\`), 옵션별 청소년 구매불가 여부(\`items\[].isAdultProduct\`)\
> \
> \- 내려주지 않는 값: \`firstCategoryId\`, \`firstCategoryName\`, \`categoryName\`(\`categories\`로 확인), \`exposure\`, \`images\[].requestedUrl\`, 옵션의 재고 ID·\`isSoldOut\`(품절은 \`quantity\`가 0인지로 확인), \`removedAt\`

```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":{"ProductV3FepResponse":{"required":["categories","deliveryPolicy","exchangeReturnPolicy","id","inspectionStatus","isCultureDeduction","isTaxFree","items","leafCategoryId","merchantId","productConstraintTemplateId","productDescriptionImages","productName","productThumbnails","rejectionReasons","searchTags","version"],"type":"object","properties":{"id":{"type":"integer","description":"상품 ID","format":"int64"},"merchantId":{"type":"integer","description":"상점 ID","format":"int64"},"version":{"type":"integer","description":"상품 버전","format":"int32"},"productName":{"type":"string","description":"상품명"},"brandName":{"type":"string","description":"브랜드명"},"productManagementCode":{"type":"string","description":"판매자가 상품 관리에 사용하는 코드"},"isTaxFree":{"type":"boolean","description":"면세 상품 여부"},"isCultureDeduction":{"type":"boolean","description":"문화비 소득공제 적용 여부"},"searchTags":{"type":"array","description":"상품 검색 태그 목록","items":{"type":"string","description":"상품 검색 태그 목록"}},"leafCategoryId":{"type":"integer","description":"상품 카테고리 ID (최하위 카테고리)","format":"int64"},"categories":{"type":"array","description":"1차부터 최하위까지의 카테고리 경로","items":{"$ref":"#/components/schemas/ProductCategoryV3FepResponse"}},"productConstraintTemplateId":{"type":"integer","description":"상품 등록 템플릿 ID","format":"int64"},"inspectionStatus":{"type":"string","description":"검수 상태","enum":["LLM_INSPECTION_READY","COMPLETE","REJECT"]},"rejectionReasons":{"type":"array","description":"반려 사유 목록","items":{"$ref":"#/components/schemas/ProductRejectionReasonV3FepResponse"}},"lastInspectionRequestedAt":{"type":"string","description":"마지막 검수 요청 시각","format":"date-time"},"items":{"type":"array","description":"상품 옵션(아이템) 목록. 삭제 처리된 옵션은 포함되지 않습니다.","items":{"$ref":"#/components/schemas/ProductItemV3FepResponse"}},"productThumbnails":{"type":"array","description":"상품 썸네일 이미지 목록 (노출 순서)","items":{"$ref":"#/components/schemas/ProductThumbnailV3FepResponse"}},"productDescriptionImages":{"type":"array","description":"상품 상세 이미지 목록 (노출 순서)","items":{"$ref":"#/components/schemas/ProductDescriptionImageV3FepResponse"}},"productDescriptionHtml":{"$ref":"#/components/schemas/ProductDescriptionHtmlV3FepResponse"},"deliveryPolicy":{"$ref":"#/components/schemas/ProductDeliveryPolicyV3FepResponse"},"exchangeReturnPolicy":{"$ref":"#/components/schemas/ProductExchangeReturnPolicyV3FepResponse"},"productMandatoryNotice":{"$ref":"#/components/schemas/ProductMandatoryNoticeV3FepResponse"},"bookInfo":{"$ref":"#/components/schemas/ProductBookInfoV3FepResponse"}},"description":"상품 조회 v3 응답"},"ProductCategoryV3FepResponse":{"required":["id","level","name"],"type":"object","properties":{"id":{"type":"integer","description":"카테고리 ID","format":"int64"},"level":{"type":"integer","description":"카테고리 단계 (1차부터)","format":"int32"},"name":{"type":"string","description":"카테고리 이름"},"parentId":{"type":"integer","description":"상위 카테고리 ID","format":"int64"}},"description":"카테고리 경로"},"ProductRejectionReasonV3FepResponse":{"required":["message","title","type"],"type":"object","properties":{"title":{"type":"string","description":"반려 사유 제목"},"message":{"type":"string","description":"반려 상세 내용"},"type":{"type":"string","description":"반려 대상 유형","enum":["PRODUCT","ITEM","IMAGE"]}},"description":"반려 사유"},"ProductItemV3FepResponse":{"required":["isAdultProduct","isHide","isMainOption","itemThumbnails","originPrice","productItemId","quantity","regularSalePrice","salesOptions"],"type":"object","properties":{"productItemId":{"type":"integer","description":"상품 옵션(아이템) ID. 상품 수정 v3 요청의 productItemId로 사용합니다.","format":"int64"},"quantity":{"type":"integer","description":"재고 수량","format":"int32"},"originPrice":{"type":"integer","description":"정상가","format":"int32"},"regularSalePrice":{"type":"integer","description":"판매가","format":"int32"},"salesOptions":{"type":"array","description":"구매 옵션 목록 (옵션 이름·값)","items":{"$ref":"#/components/schemas/ProductItemSalesOptionV3FepResponse"}},"itemManagementCode":{"type":"string","description":"옵션 관리 코드"},"itemThumbnails":{"type":"array","description":"옵션 이미지 목록 (노출 순서)","items":{"$ref":"#/components/schemas/ProductItemThumbnailV3FepResponse"}},"isMainOption":{"type":"boolean","description":"대표 옵션 여부"},"isAdultProduct":{"type":"boolean","description":"청소년 구매불가 상품 여부"},"isHide":{"type":"boolean","description":"옵션 숨김 여부. 상품 옵션 노출 상태 변경 API로 바꾸고, 상품 정보 변경 v3 요청에서는 생략해도 그대로 유지됩니다."}},"description":"상품 옵션(아이템) 정보"},"ProductItemSalesOptionV3FepResponse":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string","description":"구매 옵션 이름"},"value":{"type":"string","description":"구매 옵션 값"}},"description":"구매 옵션 (옵션 이름·값)"},"ProductItemThumbnailV3FepResponse":{"required":["itemThumbnailUrl"],"type":"object","properties":{"itemThumbnailUrl":{"type":"string","description":"옵션 이미지 URL"}},"description":"옵션 이미지"},"ProductThumbnailV3FepResponse":{"required":["productThumbnailUrl"],"type":"object","properties":{"productThumbnailUrl":{"type":"string","description":"상품 썸네일 이미지 URL"}},"description":"상품 썸네일 이미지"},"ProductDescriptionImageV3FepResponse":{"required":["productDescriptionUrl"],"type":"object","properties":{"productDescriptionUrl":{"type":"string","description":"상품 상세 이미지 URL"}},"description":"상품 상세 이미지"},"ProductDescriptionHtmlV3FepResponse":{"required":["html"],"type":"object","properties":{"html":{"type":"string","description":"상품 상세 HTML"}},"description":"상품 상세 HTML"},"ProductDeliveryPolicyV3FepResponse":{"required":["deliveryBlockedRegionPolicyId","deliveryFee","deliveryFeeType","deliveryMethod","deliveryType","islandsMountainsDeliveryFee","jejuDeliveryFee","minimumPurchasePrice","preparationDays"],"type":"object","properties":{"deliveryType":{"type":"string","description":"배송 타입","enum":["NORMAL","PREFERRED_DATE","ARRIVAL_GUARANTEED","NO_DELIVERY"]},"deliveryMethod":{"type":"string","description":"배송 방식","enum":["NORMAL","TODAY_DELIVERY"]},"deliveryDeadline":{"type":"string","description":"출고 마감 시각 (HH:mm)\n\n- 오늘 출발(TODAY_DELIVERY)이 아니면 null입니다\n- 상품 수정 v3 요청에 그대로 보내도 됩니다"},"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":"조건부 무료배송 시 무료배송 조건 금액. 조건이 없으면 0","format":"int32"},"jejuDeliveryFee":{"type":"integer","description":"제주도 추가 배송비","format":"int32"},"islandsMountainsDeliveryFee":{"type":"integer","description":"도서 산간 추가 배송비","format":"int32"},"deliveryCompanyId":{"type":"integer","description":"택배사 ID","format":"int64"},"preferredDateType":{"type":"string","description":"희망일 배송 기준 타입","enum":["ORDER_DATE","CALENDAR"]},"preferredDateFromDays":{"type":"integer","description":"주문일로부터 시작일","format":"int32"},"preferredDateToDays":{"type":"integer","description":"주문일로부터 종료일","format":"int32"},"preferredDateFromDate":{"type":"string","description":"희망 배송 시작일","format":"date"},"preferredDateToDate":{"type":"string","description":"희망 배송 종료일","format":"date"},"deliveryBlockedRegionPolicyId":{"type":"integer","description":"배송불가지역 정책 ID. 상품 수정 v3 요청에 그대로 보내면 기존 정책이 유지됩니다.","format":"int64"}},"description":"배송 정책"},"ProductExchangeReturnPolicyV3FepResponse":{"required":["applicationTermDescription","exchangeRefundLocationId","exchangeRoundTripDeliveryFee","isReturnRequired","refundOneWayDeliveryFee"],"type":"object","properties":{"exchangeRefundLocationId":{"type":"integer","description":"교환/반품지 ID","format":"int64"},"refundOneWayDeliveryFee":{"type":"integer","description":"반품 편도 배송비","format":"int32"},"exchangeRoundTripDeliveryFee":{"type":"integer","description":"교환 왕복 배송비","format":"int32"},"applicationTermDescription":{"type":"string","description":"교환,환불 신청 가능 기간 설명"},"isReturnRequired":{"type":"boolean","description":"교환/반품 시 상품 회수 여부"},"returnContractSlotNum":{"type":"integer","description":"지정된 반품 회수 계약 슬롯 번호 (0~20, 0은 기본 택배사). 지정하지 않았으면 null\n\n- 상품 수정 v3 요청 시 이 값을 그대로 보내야 슬롯 지정이 유지됩니다. 생략하면 슬롯이 해제됩니다\n- 슬롯의 계약 정보는 반품 회수 계약 슬롯 조회 API로 확인할 수 있습니다","format":"int32"}},"description":"교환/반품 정책"},"ProductMandatoryNoticeV3FepResponse":{"required":["mandatoryNoticeCode","mandatoryNoticeItems"],"type":"object","properties":{"mandatoryNoticeCode":{"type":"string","description":"상품 정보제공 고시 카테고리 코드"},"mandatoryNoticeItems":{"type":"array","description":"상품 정보제공 고시 항목 목록","items":{"$ref":"#/components/schemas/ProductMandatoryNoticeItemV3FepResponse"}}},"description":"상품 정보제공 고시"},"ProductMandatoryNoticeItemV3FepResponse":{"required":["content","id","title"],"type":"object","properties":{"id":{"type":"integer","description":"정보제공 고시 항목 ID","format":"int64"},"title":{"type":"string","description":"고시 항목 제목"},"content":{"type":"string","description":"고시 항목 내용"}},"description":"정보제공 고시 항목"},"ProductBookInfoV3FepResponse":{"required":["isIndependentPublication"],"type":"object","properties":{"bookCodeType":{"type":"string","description":"도서 코드 타입","enum":["ISBN","ISSN"]},"bookCodeValue":{"type":"string","description":"ISBN/ISSN 코드값"},"isIndependentPublication":{"type":"boolean","description":"독립출판물 여부"},"author":{"type":"string","description":"저자"},"publisher":{"type":"string","description":"출판사"}},"description":"도서 정보"}}},"paths":{"/api/v3/shopping-fep/products/{productId}/v3":{"get":{"tags":["상품 Public Controller"],"summary":"상품 조회 v3","description":"상품 ID를 이용하여 상품 정보를 조회합니다.\n\n## 상품 수정 v3와 함께 쓰기\n\n- 응답은 상품 수정 v3 요청과 같은 필드 이름·구조입니다. 바꿀 값만 고쳐 그대로 수정 요청에 보낼 수 있습니다\n\n- 옵션의 `productItemId`, 구매 옵션(`salesOptions`), `deliveryBlockedRegionPolicyId`, `returnContractSlotNum`은 수정 요청에 그대로 보내주세요\n\n- 특히 `exchangeReturnPolicy.returnContractSlotNum`을 빼고 보내면 반품 회수 계약 슬롯 지정이 해제됩니다\n\n- 정보제공 고시(`productMandatoryNotice`)가 없는 상품은 수정 요청 시 고시 정보를 채워 보내주세요\n\n- 등록/수정 직후에는 변경 내용이 잠시 반영되지 않을 수 있습니다. 직후 조회 결과로 바로 수정하면 방금 추가한 옵션이 빠져 삭제 처리될 수 있으니, 잠시 후 다시 조회한 결과를 사용해주세요\n\n## 이미지 출처 필터\n\n- `imageSource`로 응답에 포함할 이미지를 출처별로 필터링할 수 있습니다\n\n- 생략 시 `ALL`로 동작하며 전체 이미지를 반환합니다\n\n- 수정 요청에 쓰려면 `ALL`로 조회해주세요\n\n## 상품 조회(v2)에서 달라진 점\n\n- 필드 이름은 상품 등록·수정 v3와 같습니다 (`stocks` → `items`, `itemId` → `productItemId`, `constraintTemplateId` → `productConstraintTemplateId` 등)\n\n- 배송불가지역은 `isJejuAndIslandsMountainsDelivery` 대신 `deliveryPolicy.deliveryBlockedRegionPolicyId`로 내려줍니다\n\n- 반품 회수 계약 슬롯은 `returnContractSlot` 객체 대신 `exchangeReturnPolicy.returnContractSlotNum`으로 내려줍니다. 계약 정보는 반품 회수 계약 슬롯 조회 API로 확인해주세요\n\n- 상품 단위 옵션 목록(`options`, 옵션 이름별 값 목록)은 내려주지 않습니다. 옵션 이름·값은 옵션별 `items[].salesOptions`로 확인해주세요\n\n- 새로 내려주는 값: 반려 사유 대상 유형(`rejectionReasons[].type`), 옵션별 청소년 구매불가 여부(`items[].isAdultProduct`)\n\n- 내려주지 않는 값: `firstCategoryId`, `firstCategoryName`, `categoryName`(`categories`로 확인), `exposure`, `images[].requestedUrl`, 옵션의 재고 ID·`isSoldOut`(품절은 `quantity`가 0인지로 확인), `removedAt`","operationId":"getProductV3","parameters":[{"name":"productId","in":"path","description":"상품 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"imageSource","in":"query","description":"이미지 출처 필터 (생략 시 ALL)","required":false,"schema":{"type":"string","enum":["ALL","SELLER","AI_ONLY"]}}],"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","UNAUTHORIZED","REQUEST_FAILED","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/ProductV3FepResponse"}}}}}}}}}}}
```

## 상품 정보 변경 v3

> 상품 정보를 전체 교체 방식으로 변경합니다.\
> \
> \## 옵션(아이템) 처리\
> \
> \- 기존 옵션은 상품 조회 v3의 \`productItemId\`를 입력해 수정합니다. \`productItemId\`가 없으면 새 옵션으로 등록됩니다\
> \
> \- 요청에 없는 기존 옵션은 삭제 처리됩니다\
> \
> \- 기존 옵션의 구매 옵션(\`salesOptions\`)은 바꿀 수 없습니다. 바꾸려면 기존 옵션을 목록에서 빼고 새 옵션으로 입력해주세요\
> \
> \## 주의사항\
> \
> \- 반품 회수 계약 슬롯(\`exchangeReturnPolicy.returnContractSlotNum\`)을 생략하면 기존에 지정한 슬롯이 해제됩니다. 유지하려면 상품 조회 v3 응답의 값을 그대로 보내주세요\
> \
> \- 카테고리는 검수 반려 상태에서만, 구매 옵션 구성이 같은 카테고리로만 변경할 수 있습니다\
> \
> \- 검수 중인 상품은 수정할 수 없습니다\
> \
> \- 검수 승인된 상품의 일부 정보(브랜드명 등)와 검수 중인 옵션이 있는 상품의 상품 정보는 변경 요청이 반영되지 않을 수 있습니다\
> \
> \- 옵션 이미지(\`itemThumbnails\`)를 생략하면 해당 옵션의 이미지가 삭제됩니다\
> \
> \## 검수 정책\
> \
> \- \*\*이미지 변경\*\*: 검수 단계로 진입됩니다\
> \
> \- \*\*가격/재고/배송정보 변경\*\*: 즉시 반영됩니다\
> \
> \- \*\*검수 반려된 상품\*\*: 정보 변경 시 자동으로 검수 단계로 진입합니다\
> \
> \## 상품 정보 변경(v2)에서 달라진 점\
> \
> \- 필드 이름과 배송불가지역 입력 방식은 상품 등록 v3와 같습니다\
> \
> \- 기존 옵션을 옵션 값이 아니라 \`productItemId\`로 찾습니다. v2처럼 옵션 값을 바꿔 보내면 새 옵션이 생기지 않고 요청이 거절됩니다\
> \
> \- 옵션을 숨기려고 \`isHide\`를 보내는 대신, 요청 목록에서 빼면 삭제 처리됩니다\
> \
> \- 상품 정보 변경 v2로 수정한 상품은 옵션 ID가 바뀌었을 수 있으니, 상품 조회 v3로 다시 조회한 결과를 사용해주세요

```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":{"ChangeProductV3FepRequest":{"required":["deliveryPolicy","exchangeReturnPolicy","isTaxFree","items","leafCategoryId","productMandatoryNotice","productName","productThumbnails","searchTags"],"type":"object","properties":{"productName":{"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, 협력사"},"productManagementCode":{"type":"string","description":"판매자가 상품을 관리하려고 사용하는 코드 (최대 100자)"},"isTaxFree":{"type":"boolean","description":"면세 상품 여부\n\n- true: 면세\n- false: 과세"},"isCultureDeduction":{"type":"boolean","description":"문화비 소득공제 적용 여부. 생략 시 false"},"searchTags":{"type":"array","description":"상품 검색에 사용되는 태그 목록\n\n- 없으면 빈 배열로 요청\n- 허용 정규식: [0-9a-zA-Z가-힣]{1,10}","items":{"type":"string","description":"상품 검색에 사용되는 태그 목록\n\n- 없으면 빈 배열로 요청\n- 허용 정규식: [0-9a-zA-Z가-힣]{1,10}"}},"leafCategoryId":{"type":"integer","description":"상품 카테고리 ID\n\n- 검수 반려 상태에서만 변경할 수 있습니다\n- 구매 옵션 구성이 기존 카테고리와 같은 카테고리로만 변경할 수 있습니다","format":"int64"},"items":{"maxItems":300,"minItems":1,"type":"array","description":"판매할 상품 옵션(아이템) 전체 목록 (1~300개)\n\n- 요청에 없는 기존 옵션은 삭제 처리됩니다","items":{"$ref":"#/components/schemas/ChangeProductItemV3FepRequest"}},"productThumbnails":{"type":"array","description":"상품 썸네일 이미지 목록 (1~10개). 배열 순서가 노출 순서입니다.\n\n- 최소크기 600x600, 비율 1:1, 용량 2MB 이하, JPG/PNG","items":{"$ref":"#/components/schemas/ProductThumbnailV3FepRequest"}},"productDescriptionImages":{"type":"array","description":"상품 상세 이미지 목록 (1~50개). 배열 순서가 노출 순서입니다.\n\n- productDescriptionHtml과 둘 중 하나만 입력해야 합니다\n- 최소가로크기 600, 용량 5MB 이하, JPG/PNG/GIF","items":{"$ref":"#/components/schemas/ProductDescriptionImageV3FepRequest"}},"productDescriptionHtml":{"$ref":"#/components/schemas/ProductDescriptionHtmlV3FepRequest"},"deliveryPolicy":{"$ref":"#/components/schemas/ProductDeliveryPolicyV3FepRequest"},"exchangeReturnPolicy":{"$ref":"#/components/schemas/ProductExchangeReturnPolicyV3FepRequest"},"productMandatoryNotice":{"$ref":"#/components/schemas/ProductMandatoryNoticeV3FepRequest"},"bookInfo":{"$ref":"#/components/schemas/ProductBookInfoV3FepRequest"}},"description":"상품 수정 v3 요청"},"ChangeProductItemV3FepRequest":{"required":["isMainOption","originPrice","quantity","regularSalePrice","salesOptions"],"type":"object","properties":{"productItemId":{"type":"integer","description":"상품 옵션(아이템) ID\n\n- 기존 옵션을 수정하려면 상품 조회 v3 응답의 productItemId를 입력합니다\n- 새 옵션이면 생략하거나 null로 입력합니다\n- 기존 옵션의 구매 옵션(salesOptions)은 바꿀 수 없습니다. 바꾸려면 기존 옵션을 목록에서 빼고(삭제) 새 옵션으로 입력해주세요","format":"int64"},"quantity":{"type":"integer","description":"현재 판매할 수 있는 재고 수량\n\n- 0 이상 입력 가능\n- 0인 경우 품절 상태가 됩니다","format":"int32"},"originPrice":{"type":"integer","description":"정상가. 권장소비자가격이나 자사몰/온라인 채널에서 판매 이력이 있는 가격\n\n- 최소 1원 이상","format":"int32"},"regularSalePrice":{"type":"integer","description":"판매가. 실제로 소비자에게 판매하는 가격\n\n- 최소 1원 이상\n- 정상가(originPrice) 이하여야 합니다","format":"int32"},"salesOptions":{"type":"array","description":"구매 옵션 목록 (옵션 이름·값)\n\n- 카테고리 제약사항에 따라 제한됩니다\n- 기존 옵션(productItemId 입력)은 상품 조회 v3 응답의 값과 같아야 합니다","items":{"$ref":"#/components/schemas/ProductItemSalesOptionV3FepRequest"}},"itemManagementCode":{"type":"string","description":"옵션 관리 코드 (최대 100자)"},"itemThumbnails":{"type":"array","description":"옵션 이미지 목록. 배열 순서가 노출 순서입니다.\n\n- 전체 교체이므로 생략하거나 빈 배열이면 기존 옵션 이미지가 삭제됩니다","items":{"$ref":"#/components/schemas/ProductItemThumbnailV3FepRequest"}},"isMainOption":{"type":"boolean","description":"대표 옵션 여부 (true: 대표 가격으로 노출)\n\n- 반드시 1개만 true여야 합니다"},"isAdultProduct":{"type":"boolean","description":"청소년 구매불가 상품 여부 (true: 청소년 구매불가, false: 구매 가능). 생략 시 false"}},"description":"수정할 상품 옵션(아이템) 정보"},"ProductItemSalesOptionV3FepRequest":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string","description":"구매 옵션 이름\n\n- 카테고리 제약사항 categorySalesOptions의 key와 정확히 일치해야 합니다\n- isOption = false일 경우 필수\n- isOneOfRequiredGroup = true인 그룹 중 최소 1개 이상 반드시 포함해야 등록 가능"},"value":{"type":"string","description":"구매 옵션 값\n\n- valueCandidates에 포함되는 값만 허용 (valueCandidates가 빈 배열일 경우 자유)\n- unitValues가 있을 경우 해당 단위를 붙여 입력해야 합니다 (예: 500ml)\n- keyComment와 valueComment가 있을 경우 해당 내용을 참조하여 입력해야 합니다"}},"description":"구매 옵션 (옵션 이름·값)"},"ProductItemThumbnailV3FepRequest":{"required":["itemThumbnailUrl"],"type":"object","properties":{"itemThumbnailUrl":{"type":"string","description":"옵션 이미지 URL (최대 255자)"}},"description":"옵션 이미지"},"ProductThumbnailV3FepRequest":{"required":["productThumbnailUrl"],"type":"object","properties":{"productThumbnailUrl":{"type":"string","description":"상품 썸네일 이미지 URL (최대 255자)"}},"description":"상품 썸네일 이미지"},"ProductDescriptionImageV3FepRequest":{"required":["productDescriptionUrl"],"type":"object","properties":{"productDescriptionUrl":{"type":"string","description":"상품 상세 이미지 URL (최대 255자)"}},"description":"상품 상세 이미지"},"ProductDescriptionHtmlV3FepRequest":{"required":["html"],"type":"object","properties":{"html":{"type":"string","description":"상품 상세 HTML. 서버에서 sanitization 후 저장합니다."}},"description":"상품 상세 HTML"},"ProductDeliveryPolicyV3FepRequest":{"required":["deliveryBlockedRegionPolicyId","deliveryFee","deliveryFeeType","deliveryMethod","islandsMountainsDeliveryFee","jejuDeliveryFee","minimumPurchasePrice"],"type":"object","properties":{"deliveryType":{"type":"string","description":"배송 타입. 생략 시 NORMAL","enum":["NORMAL","PREFERRED_DATE"]},"deliveryMethod":{"type":"string","description":"배송 방식","enum":["NORMAL","TODAY_DELIVERY"]},"deliveryDeadline":{"type":"string","description":"출고 마감 시각 (HH:mm, 30분 단위)\n\n- 오늘 출발(TODAY_DELIVERY)일 때 필수입니다\n- 일반 배송(NORMAL)이면 무시됩니다"},"preparationDays":{"type":"integer","description":"상품 준비 기간 (일, 최대 14일)\n\n- 일반 배송(NORMAL)일 때 미입력 시 기본값 3으로 설정됩니다\n- 오늘 출발(TODAY_DELIVERY)이면 무시됩니다","format":"int32"},"deliveryLocationId":{"type":"integer","description":"배송비 묶음 그룹 ID\n\n- null이면 묶음배송 불가","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"},"jejuDeliveryFee":{"type":"integer","description":"제주도 추가 배송비","format":"int32"},"islandsMountainsDeliveryFee":{"type":"integer","description":"도서 산간 추가 배송비","format":"int32"},"deliveryCompanyId":{"type":"integer","description":"택배사 ID. 택배사 목록 조회 API 참고","format":"int64"},"preferredDateType":{"type":"string","description":"희망일 배송 기준 타입. 희망일 배송(PREFERRED_DATE)에서 사용","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"},"deliveryBlockedRegionPolicyId":{"type":"integer","description":"배송불가지역 정책 ID\n\n- 1: 제주/도서산간 포함 전 지역 배송 가능\n- 3: 제주 배송 불가\n- 5: 도서산간 배송 불가\n- 7: 제주/도서산간 배송 불가\n- 상품 수정 시에는 상품 조회 v3 응답의 값을 그대로 보내면 기존 정책이 유지됩니다","format":"int64"}},"description":"배송 정책"},"ProductExchangeReturnPolicyV3FepRequest":{"required":["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"},"applicationTermDescription":{"type":"string","description":"교환,환불 신청 가능 기간 설명 (1~500자)"},"isReturnRequired":{"type":"boolean","description":"교환/반품 시 상품 회수 여부 (true: 회수 필요, false: 회수 불필요). 생략 시 true"},"returnContractSlotNum":{"type":"integer","description":"반품 회수 계약 슬롯 번호 (0~20, 0은 기본 택배사)\n\n- 반품 회수 계약 슬롯 조회 API 참조\n- 생략하거나 null이면 슬롯을 지정하지 않습니다. **상품 수정 시 생략하면 기존에 지정한 슬롯이 해제됩니다.** 유지하려면 상품 조회 v3 응답의 returnContractSlotNum을 그대로 보내주세요","format":"int32"}},"description":"교환/반품 정책"},"ProductMandatoryNoticeV3FepRequest":{"required":["mandatoryNoticeCode","mandatoryNoticeItems"],"type":"object","properties":{"mandatoryNoticeCode":{"type":"string","description":"상품 정보제공 고시 카테고리 코드\n\n- 정보제공 고시를 위한 카테고리 목록 조회 API 참조"},"mandatoryNoticeItems":{"type":"array","description":"상품 정보제공 고시 항목 목록\n\n- 정보제공 고시를 위한 항목 조회 API 참조","items":{"$ref":"#/components/schemas/ProductMandatoryNoticeItemV3FepRequest"}}},"description":"상품 정보제공 고시"},"ProductMandatoryNoticeItemV3FepRequest":{"required":["content","id"],"type":"object","properties":{"id":{"type":"integer","description":"정보제공 고시 항목 ID","format":"int64"},"content":{"type":"string","description":"고시 항목 내용 (판매자 입력 정보, 1~4000자)"}},"description":"정보제공 고시 항목"},"ProductBookInfoV3FepRequest":{"type":"object","properties":{"bookCodeType":{"type":"string","description":"도서 코드 타입","enum":["ISBN","ISSN"]},"bookCodeValue":{"type":"string","description":"ISBN/ISSN 코드값 13자리. 하이픈 포함 입력도 가능합니다."},"isIndependentPublication":{"type":"boolean","description":"독립출판물 등 ISBN/ISSN 예외 여부. 생략 시 false"},"author":{"type":"string","description":"저자. 최대 64자"},"publisher":{"type":"string","description":"출판사. 최대 64자"}},"description":"도서 정보"}}},"paths":{"/api/v3/shopping-fep/products/{productId}/v3":{"put":{"tags":["상품 Public Controller"],"summary":"상품 정보 변경 v3","description":"상품 정보를 전체 교체 방식으로 변경합니다.\n\n## 옵션(아이템) 처리\n\n- 기존 옵션은 상품 조회 v3의 `productItemId`를 입력해 수정합니다. `productItemId`가 없으면 새 옵션으로 등록됩니다\n\n- 요청에 없는 기존 옵션은 삭제 처리됩니다\n\n- 기존 옵션의 구매 옵션(`salesOptions`)은 바꿀 수 없습니다. 바꾸려면 기존 옵션을 목록에서 빼고 새 옵션으로 입력해주세요\n\n## 주의사항\n\n- 반품 회수 계약 슬롯(`exchangeReturnPolicy.returnContractSlotNum`)을 생략하면 기존에 지정한 슬롯이 해제됩니다. 유지하려면 상품 조회 v3 응답의 값을 그대로 보내주세요\n\n- 카테고리는 검수 반려 상태에서만, 구매 옵션 구성이 같은 카테고리로만 변경할 수 있습니다\n\n- 검수 중인 상품은 수정할 수 없습니다\n\n- 검수 승인된 상품의 일부 정보(브랜드명 등)와 검수 중인 옵션이 있는 상품의 상품 정보는 변경 요청이 반영되지 않을 수 있습니다\n\n- 옵션 이미지(`itemThumbnails`)를 생략하면 해당 옵션의 이미지가 삭제됩니다\n\n## 검수 정책\n\n- **이미지 변경**: 검수 단계로 진입됩니다\n\n- **가격/재고/배송정보 변경**: 즉시 반영됩니다\n\n- **검수 반려된 상품**: 정보 변경 시 자동으로 검수 단계로 진입합니다\n\n## 상품 정보 변경(v2)에서 달라진 점\n\n- 필드 이름과 배송불가지역 입력 방식은 상품 등록 v3와 같습니다\n\n- 기존 옵션을 옵션 값이 아니라 `productItemId`로 찾습니다. v2처럼 옵션 값을 바꿔 보내면 새 옵션이 생기지 않고 요청이 거절됩니다\n\n- 옵션을 숨기려고 `isHide`를 보내는 대신, 요청 목록에서 빼면 삭제 처리됩니다\n\n- 상품 정보 변경 v2로 수정한 상품은 옵션 ID가 바뀌었을 수 있으니, 상품 조회 v3로 다시 조회한 결과를 사용해주세요","operationId":"changeProductV3","parameters":[{"name":"productId","in":"path","description":"상품 ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeProductV3FepRequest"}}},"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","UNAUTHORIZED","INTERNAL_SERVER_ERROR","REQUEST_FAILED","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 템플릿 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":"연동 프로그램명 또는 자사 서비스명"},"bookInfo":{"$ref":"#/components/schemas/ProductBookInfoFepRequest"}},"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"},"isAdultProduct":{"type":"boolean","description":"청소년 구매불가 상품 여부 (true: 청소년 구매불가, false: 구매 가능)\n\n이 값을 생략하면 false(구매 가능)로 등록됩니다."},"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"]},"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"},"deliveryBlockedRegionPolicyId":{"type":"integer","description":"배송불가지역 정책 ID. 입력하면 제주/도서산간 배송 가능 여부보다 우선합니다.","format":"int64"}},"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자)"},"isReturnRequired":{"type":"boolean","description":"교환/반품 시 상품 회수 여부 (true: 회수 필요, false: 회수 불필요). 생략 시 true"},"returnContractSlotNum":{"type":"integer","description":"반품 회수 계약 슬롯 번호 (0~20, 0은 기본 택배사). 생략 시 미선택\n\n- 반품 회수 계약 슬롯 조회 API 참조","format":"int32"}},"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":"정보제공 고시 항목"},"ProductBookInfoFepRequest":{"required":["isIndependentPublication"],"type":"object","properties":{"bookCodeType":{"type":"string","description":"도서 코드 타입","enum":["ISBN","ISSN"]},"bookCodeValue":{"type":"string","description":"ISBN/ISSN 코드값 13자리. 하이픈 포함 입력도 가능합니다."},"isIndependentPublication":{"type":"boolean","description":"독립출판물 등 ISBN/ISSN 예외 여부"},"author":{"type":"string","description":"저자. 최대 64자"},"publisher":{"type":"string","description":"출판사. 최대 64자"}},"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":"연동 프로그램명 또는 자사 서비스명"},"bookInfo":{"$ref":"#/components/schemas/ProductBookInfoFepRequest"}},"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"},"isAdultProduct":{"type":"boolean","description":"청소년 구매불가 상품 여부 (true: 청소년 구매불가, false: 구매 가능)\n\n수정 시 이 값을 생략하면 false(구매 가능)로 설정됩니다. 청소년 구매불가 상태를 유지하려면 수정 요청마다 값을 함께 전송해야 합니다."},"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","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"},"deliveryBlockedRegionPolicyId":{"type":"integer","description":"배송불가지역 정책 ID. 입력하면 제주/도서산간 배송 가능 여부보다 우선합니다.","format":"int64"}},"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자)"},"isReturnRequired":{"type":"boolean","description":"교환/반품 시 상품 회수 여부 (true: 회수 필요, false: 회수 불필요). 생략 시 true\n\n- 생략하면 기존 값과 관계없이 true로 덮어씁니다"},"returnContractSlotNum":{"type":"integer","description":"반품 회수 계약 슬롯 번호 (0~20, 0은 기본 택배사). 생략 시 미선택\n\n- 반품 회수 계약 슬롯 조회 API 참조\n- 생략하면 기존에 지정한 슬롯이 해제됩니다","format":"int32"}},"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":"정보제공 고시 항목"},"ProductBookInfoFepRequest":{"required":["isIndependentPublication"],"type":"object","properties":{"bookCodeType":{"type":"string","description":"도서 코드 타입","enum":["ISBN","ISSN"]},"bookCodeValue":{"type":"string","description":"ISBN/ISSN 코드값 13자리. 하이픈 포함 입력도 가능합니다."},"isIndependentPublication":{"type":"boolean","description":"독립출판물 등 ISBN/ISSN 예외 여부"},"author":{"type":"string","description":"저자. 최대 64자"},"publisher":{"type":"string","description":"출판사. 최대 64자"}},"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를 이용하여 상품 정보를 조회합니다.\
> \
> \## 이미지 출처 필터\
> \
> \- \`imageSource\`로 응답에 포함할 이미지를 출처별로 필터링할 수 있습니다\
> \
> \- 생략 시 \`ALL\`로 동작하며 전체 이미지를 반환합니다

```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"},"bookInfo":{"$ref":"#/components/schemas/ProductBookInfoFepResponse"}},"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"]},"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","isReturnRequired","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":"교환/반품 신청 가능 기간"},"isReturnRequired":{"type":"boolean","description":"교환/반품 시 상품 회수 여부 (true: 회수 필요, false: 회수 불필요)"},"returnContractSlot":{"$ref":"#/components/schemas/ProductResponseReturnContractSlotFepResponse"}},"description":"상품 교환/반품 정책"},"ProductResponseReturnContractSlotFepResponse":{"required":["slotNum"],"type":"object","properties":{"slotNum":{"type":"integer","description":"반품 회수 계약 슬롯 번호 (0~20, 0은 기본 택배사)","format":"int32"},"contractName":{"type":"string","description":"슬롯에 배치된 계약명. 계약이 없거나 조회에 실패하면 null"},"verifiedStatus":{"type":"string","description":"슬롯에 배치된 계약의 승인 상태. 계약이 없거나 조회에 실패하면 null","enum":["PENDING","VERIFIED","REJECTED"]},"deliveryCompanyName":{"type":"string","description":"슬롯에 배치된 계약의 택배사명. 계약이 없거나 조회에 실패하면 null"}},"description":"선택한 반품 회수 계약 슬롯. 미선택이면 null"},"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":"상품 정보제공 고시 항목 목록"},"ProductBookInfoFepResponse":{"required":["isIndependentPublication"],"type":"object","properties":{"bookCodeType":{"type":"string","description":"도서 코드 타입","enum":["ISBN","ISSN"]},"bookCodeValue":{"type":"string","description":"ISBN/ISSN 코드값"},"isIndependentPublication":{"type":"boolean","description":"독립출판물 등 ISBN/ISSN 예외 여부"},"author":{"type":"string","description":"저자"},"publisher":{"type":"string","description":"출판사"}},"description":"도서 정보. 도서 카테고리 상품에만 존재하며 미입력 시 null입니다."}}},"paths":{"/api/v3/shopping-fep/products/{productId}/v2":{"get":{"tags":["상품 Public Controller"],"summary":"상품 조회","description":"상품 ID를 이용하여 상품 정보를 조회합니다.\n\n## 이미지 출처 필터\n\n- `imageSource`로 응답에 포함할 이미지를 출처별로 필터링할 수 있습니다\n\n- 생략 시 `ALL`로 동작하며 전체 이미지를 반환합니다","operationId":"getProductV2","parameters":[{"name":"productId","in":"path","description":"상품 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"imageSource","in":"query","description":"이미지 출처 필터 (생략 시 ALL)","required":false,"schema":{"type":"string","enum":["ALL","SELLER","AI_ONLY"]}},{"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","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로 필터링할 수 있습니다.\
> \
> \- \`productManagementCodes\`: 상품관리코드로 필터링할 수 있습니다.

```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","productItems","productName","summaryStatus"],"type":"object","properties":{"productId":{"type":"integer","description":"상품 ID","format":"int64"},"productName":{"type":"string","description":"상품명"},"productManagementCode":{"type":"string","description":"상품관리코드 (셀러가 등록한 상품 관리용 코드)"},"brandName":{"type":"string","description":"브랜드명"},"summaryStatus":{"$ref":"#/components/schemas/ProductItemsGroupByProductFepResponseSummaryStatus"},"productInspectionStatus":{"type":"string","description":"검수 상태","enum":["LLM_INSPECTION_READY","COMPLETE","REJECT"]},"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":"아이템명"},"itemManagementCode":{"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로 필터링할 수 있습니다.\n\n- `productManagementCodes`: 상품관리코드로 필터링할 수 있습니다.","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"}}},{"name":"productManagementCodes","in":"query","description":"상품관리코드 필터 (최대 100개)","required":false,"schema":{"uniqueItems":true,"type":"array","items":{"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/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":"아이템명"},"itemManagementCode":{"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":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 상품 옵션 노출 상태 변경

> 상품 또는 상품 옵션 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":{"UpdateProductItemHideStatusFepRequest":{"required":["hide","productIds","productItemIds"],"type":"object","properties":{"productIds":{"uniqueItems":true,"type":"array","description":"상품에 속한 모든 옵션을 변경할 상품 ID 목록","items":{"type":"integer","description":"상품에 속한 모든 옵션을 변경할 상품 ID 목록","format":"int64"}},"productItemIds":{"uniqueItems":true,"type":"array","description":"개별 변경할 상품 옵션 ID 목록","items":{"type":"integer","description":"개별 변경할 상품 옵션 ID 목록","format":"int64"}},"hide":{"type":"boolean","description":"숨김 여부 (true: 숨김, false: 노출)"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"상품 옵션 노출 상태 변경 요청"},"UpdateProductItemHideStatusFepResponse":{"required":["failedItemIds","failedProductIds"],"type":"object","properties":{"failedProductIds":{"type":"array","description":"변경에 실패한 상품 ID 목록","items":{"type":"integer","description":"변경에 실패한 상품 ID 목록","format":"int64"}},"failedItemIds":{"type":"array","description":"변경에 실패한 상품 옵션 ID 목록","items":{"type":"integer","description":"변경에 실패한 상품 옵션 ID 목록","format":"int64"}}},"description":"상품 옵션 노출 상태 변경 응답"}}},"paths":{"/api/v3/shopping-fep/product-items/update-hide-status":{"put":{"tags":["상품 Public Controller"],"summary":"상품 옵션 노출 상태 변경","description":"상품 또는 상품 옵션 ID를 기준으로 옵션의 노출 상태를 숨기기 또는 보이기로 변경합니다.","operationId":"updateProductItemHideStatus_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductItemHideStatusFepRequest"}}},"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":{"$ref":"#/components/schemas/UpdateProductItemHideStatusFepResponse"}}}}}}}}}}}
```

## 상품 옵션 판매가 수정

> 특정 상품 옵션의 판매가를 수정합니다.\
> \
> \## 가격 구조\
> \
> \- \*\*정상가\*\*: 권장소비자가격(도서는 정가) 또는 자사몰/온라인 판매 채널에서 판매 이력이 있는 가격\
> \- \*\*판매가\*\*: 실제로 소비자에게 상품을 판매하는 가격으로 쿠폰 등의 할인이 포함되지 않은 가격\
> \
> \## 상품정보 변경 시, 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입니다.\
> \- 여러 옵션의 제한을 한 번에 삭제 가능합니다. (배열로 전달)\ <br>

```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 이상으로 설정하면 품절 취소됩니다.&#x20;

```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"}}}}}}}}}}}
```

## 반품 회수 계약 슬롯 조회

> 셀러의 반품 회수 계약 슬롯 목록을 조회합니다.\
> \
> \## 사용처\
> \
> \- 상품 등록/수정 시 \`exchangeReturnPolicy.returnContractSlotNum\`에 지정할 슬롯 번호를 이 목록에서 고릅니다.\
> \
> \## 응답\
> \
> \- 기본 택배사(0번)와 보조 택배사(1\~20번) 슬롯 21개를 번호순으로 반환합니다.\
> \- 계약 정보(\`contractName\`, \`verifiedStatus\`, \`deliveryCompanyName\`)는 슬롯에 계약이 없거나 조회에 실패하면 null입니다. null을 미승인으로 해석하지 마세요.\
> \- 상품에는 계약 정보(\`deliveryCompanyName\`)가 있는 슬롯을 지정하세요. 계약 정보가 없는 슬롯은 회수할 계약이 없고, 만들지 않은 슬롯 번호를 지정하면 상품 등록/수정이 실패합니다.\
> \
> \## 슬롯 등록 방법\
> \
> \- 토스쇼핑 파트너스의 택배사 관리 화면에서 계약을 등록하고 슬롯에 배치합니다.

```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":{"ListReturnContractSlotsFepResponse":{"required":["items"],"type":"object","properties":{"items":{"type":"array","description":"슬롯 목록 (0~20번, 번호순)","items":{"$ref":"#/components/schemas/ReturnContractSlotFepResponse"}}},"description":"반품 회수 계약 슬롯 목록 조회 응답"},"ReturnContractSlotFepResponse":{"required":["label","slotNum"],"type":"object","properties":{"slotNum":{"type":"integer","description":"슬롯 번호 (0~20, 0은 기본 택배사). 상품 등록/수정의 returnContractSlotNum에 사용","format":"int32"},"label":{"type":"string","description":"슬롯 표시명"},"contractName":{"type":"string","description":"슬롯에 배치된 계약명. 계약이 없거나 조회에 실패하면 null"},"verifiedStatus":{"type":"string","description":"슬롯에 배치된 계약의 승인 상태. 계약이 없거나 조회에 실패하면 null","enum":["PENDING","VERIFIED","REJECTED"]},"deliveryCompanyName":{"type":"string","description":"슬롯에 배치된 계약의 택배사명. 계약이 없거나 조회에 실패하면 null"}},"description":"반품 회수 계약 슬롯"}}},"paths":{"/api/v3/shopping-fep/merchants/return-contract-slots":{"get":{"tags":["상품 Public Controller"],"summary":"반품 회수 계약 슬롯 조회","description":"셀러의 반품 회수 계약 슬롯 목록을 조회합니다.\n\n## 사용처\n\n- 상품 등록/수정 시 `exchangeReturnPolicy.returnContractSlotNum`에 지정할 슬롯 번호를 이 목록에서 고릅니다.\n\n## 응답\n\n- 기본 택배사(0번)와 보조 택배사(1~20번) 슬롯 21개를 번호순으로 반환합니다.\n- 계약 정보(`contractName`, `verifiedStatus`, `deliveryCompanyName`)는 슬롯에 계약이 없거나 조회에 실패하면 null입니다. null을 미승인으로 해석하지 마세요.\n- 상품에는 계약 정보(`deliveryCompanyName`)가 있는 슬롯을 지정하세요. 계약 정보가 없는 슬롯은 회수할 계약이 없고, 만들지 않은 슬롯 번호를 지정하면 상품 등록/수정이 실패합니다.\n\n## 슬롯 등록 방법\n\n- 토스쇼핑 파트너스의 택배사 관리 화면에서 계약을 등록하고 슬롯에 배치합니다.","operationId":"getReturnContractSlots_1","parameters":[{"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":["REQUEST_FAILED","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/ListReturnContractSlotsFepResponse"}}}}}}}}}}}
```

> ### API 연동 중 문의사항이나 개선 제안이 있으신가요?

{% hint style="info" %}
토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 [연동/개발 문의](https://discord.gg/xPz6H9NZ3P)에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://shopping-docs.toss.im/dev/api-2/product.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
