# 카테고리

## 카테고리 항목 조회

> 상품 카테고리 항목을 조회합니다.\
> \
> 카테고리 ID를 미기입한 상태로 요청할 경우, 1차 카테고리 항목들을 반환합니다.\
> \
> \## 카테고리 구조\
> 기존 4단계 카테고리가 확장되어 2\~6 level의 카테고리가 말단 카테고리로 가능하며, 말단 카테고리를 선택하여 상품을 등록할 수 있습니다.\
> \
> \## 카테고리 정책\
> 말단 카테고리에만 정책이 존재합니다. (나머지는 null)\
> \- \*\*문화비 소득공제\*\*: 해당 값이 true라면 상품 등록 시 문화비에 대한 공제 여부를 등록할 수 있습니다.\
> \- \*\*할인율 제한\*\*: 해당 값이 null이 아니라면 상품 등록 시 할인율 제한이 있을 수 있습니다. 현재는 도서정가제로 인한 10%만 제한되고 있습니다.

```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":{"ListCategoriesChildrenFepResponse":{"required":["items"],"type":"object","properties":{"items":{"type":"array","description":"상품 카테고리 항목 아이템들","items":{"$ref":"#/components/schemas/ListProductCategoriesChildrenResponseFepItem"}}},"description":"상품 카테고리 하위 목록 응답"},"ListProductCategoriesChildrenResponseFepItem":{"required":["id","isLeaf","level","name"],"type":"object","properties":{"id":{"type":"integer","description":"카테고리 식별용 ID","format":"int64"},"name":{"type":"string","description":"카테고리 이름"},"level":{"type":"integer","description":"카테고리 깊이 (1차 카테고리는 1, 2차 카테고리는 2)","format":"int32"},"parentId":{"type":"integer","description":"바로 위 카테고리 ID (1차 카테고리는 상위 카테고리가 없어서 null)","format":"int64"},"isLeaf":{"type":"boolean","description":"최하위 카테고리 여부"},"policy":{"$ref":"#/components/schemas/CommonCategoryPolicyResponseFepDto"}},"description":"상품 카테고리 항목 아이템들"},"CommonCategoryPolicyResponseFepDto":{"required":["isCultureDeductionTarget"],"type":"object","properties":{"isCultureDeductionTarget":{"type":"boolean","description":"문화비 소득공제 적용 대상\n\n- 해당 값이 true라면 상품 등록 시 문화비에 대한 공제 여부를 등록할 수 있습니다"},"discountLimitPercentage":{"type":"number","description":"할인율 제한 퍼센티지\n\n- 해당 값이 null이 아니라면 상품 등록 시 할인율 제한이 있을 수 있습니다\n- 현재는 도서정가제로 인한 10%만 제한되고 있습니다","format":"double"}},"description":"카테고리 별 정책\n\n- 말단 카테고리에만 정책이 존재합니다 (나머지는 null)"}}},"paths":{"/api/v3/shopping-fep/products/categories/children":{"get":{"tags":["상품 카테고리"],"summary":"카테고리 항목 조회","description":"상품 카테고리 항목을 조회합니다.\n\n카테고리 ID를 미기입한 상태로 요청할 경우, 1차 카테고리 항목들을 반환합니다.\n\n## 카테고리 구조\n기존 4단계 카테고리가 확장되어 2~6 level의 카테고리가 말단 카테고리로 가능하며, 말단 카테고리를 선택하여 상품을 등록할 수 있습니다.\n\n## 카테고리 정책\n말단 카테고리에만 정책이 존재합니다. (나머지는 null)\n- **문화비 소득공제**: 해당 값이 true라면 상품 등록 시 문화비에 대한 공제 여부를 등록할 수 있습니다.\n- **할인율 제한**: 해당 값이 null이 아니라면 상품 등록 시 할인율 제한이 있을 수 있습니다. 현재는 도서정가제로 인한 10%만 제한되고 있습니다.","operationId":"listCategoriesChildren_1","parameters":[{"name":"id","in":"query","description":"카테고리 ID (미기입 시 1차 카테고리 반환)","required":false,"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","REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/ListCategoriesChildrenFepResponse"}}}}}}}}}}}
```

## 상품 제약 조건 템플릿 조회

> 카테고리별 상품 등록/수정 시 적용되는 제약 조건 템플릿을 조회합니다.\
> \
> \## 주요 제약사항\
> \- 카테고리는 주기적으로 수정될 수 있습니다.\
> \- 반드시 API를 호출해서 제약사항을 주기적으로 확인 후 기입되도록 구현 부탁드립니다.\
> \- \`categoryId\`에 따라 해당 카테고리의 옵션 제약이 적용됩니다.\
> \- categoryId는 버전 2의 isLeaf = true인 카테고리 ID만 허용됩니다.\
> \
> \## 판매 옵션 (categorySalesOptions)\
> 상품 등록 시 \`stocks.options\`에 입력할 수 있는 옵션 정보입니다.\
> \- \`groupName\`은 \`categorySalesOptions\`의 \`key\`, \`valueName\`은 \`valueCandidates\`에 포함되는 값만 허용 (valueCandidates가 빈 배열일 경우 자유)\
> \- \`unitValues\`가 있을 경우 valueName은 해당 단위로 끝나는 값이어야 합니다.\
> \- \`keyComment\`와 \`valueComment\`가 있을 경우 해당 내용을 참조하여 입력해야 합니다.\
> \- \`isOption = false\`일 경우 필수 (2025.06.16: salesOption은 isOption 여부와 관계없이 전부 필수값입니다.)\
> \- \`isOneOfRequiredGroup = true\`인 그룹 중 \*\*최소 1개 이상\*\* 반드시 포함해야 등록 가능\
> \- \`categorySalesOptions.id = 373\` (key="수량")의 경우 재고 수량이 아닌, 옵션의 구성 수량을 의미합니다. 토스 쇼핑 파트너스에서 노출되는 구성 수량과 일치합니다.

```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":{"GetProductConstraintTemplatesFepResponse":{"required":["categoryId","categoryName","categorySalesOptions","productNoticeInfoTemplateTypes"],"type":"object","properties":{"categoryName":{"type":"string","description":"카테고리 이름"},"categoryId":{"type":"integer","description":"카테고리 ID","format":"int64"},"categorySalesOptions":{"type":"array","description":"상품 등록/수정시 입력할 수 있는 판매 옵션 (*상품 등록 Request의 stocks.options 참조)","items":{"$ref":"#/components/schemas/CategorySalesOptionApiResponse"}},"productNoticeInfoTemplateTypes":{"type":"array","description":"상품 등록/수정시 입력할 수 있는 상품 정보 제공 고시 타입 리스트","items":{"type":"string","description":"상품 등록/수정시 입력할 수 있는 상품 정보 제공 고시 타입 리스트"}}},"description":"상품 제약 조건 템플릿 응답"},"CategorySalesOptionApiResponse":{"required":["id","isOneOfRequiredGroup","isOption","key"],"type":"object","properties":{"id":{"type":"integer","description":"판매 옵션 ID","format":"int64"},"key":{"type":"string","description":"옵션 그룹 명"},"valueCandidates":{"type":"array","description":"입력 가능한 값 리스트. null인 경우 리스트에 관계없이 입력 가능","items":{"type":"string","description":"입력 가능한 값 리스트. null인 경우 리스트에 관계없이 입력 가능"}},"isOption":{"type":"boolean","description":"판매옵션의 필수 입력 여부, 2025.06.16부터 모두 필수입니다."},"placeholder":{"type":"string","description":"입력 예시"},"unitValues":{"type":"array","description":"입력단위. 무게 / 부피 등","items":{"type":"string","description":"입력단위. 무게 / 부피 등"}},"keyComment":{"type":"string","description":"옵션 키에 대한 추가 설명"},"valueComment":{"type":"string","description":"옵션 값에 대한 추가 설명"},"isOneOfRequiredGroup":{"type":"boolean","description":"categorySalesOptions 내에서 해당 값이 true인 옵션은 하나만 입력 가능. eg) (택1)"}},"description":"카테고리 판매 옵션"}}},"paths":{"/api/v3/shopping-fep/category/{categoryId}/constraint-templates":{"get":{"tags":["상품 카테고리"],"summary":"상품 제약 조건 템플릿 조회","description":"카테고리별 상품 등록/수정 시 적용되는 제약 조건 템플릿을 조회합니다.\n\n## 주요 제약사항\n- 카테고리는 주기적으로 수정될 수 있습니다.\n- 반드시 API를 호출해서 제약사항을 주기적으로 확인 후 기입되도록 구현 부탁드립니다.\n- `categoryId`에 따라 해당 카테고리의 옵션 제약이 적용됩니다.\n- categoryId는 버전 2의 isLeaf = true인 카테고리 ID만 허용됩니다.\n\n## 판매 옵션 (categorySalesOptions)\n상품 등록 시 `stocks.options`에 입력할 수 있는 옵션 정보입니다.\n- `groupName`은 `categorySalesOptions`의 `key`, `valueName`은 `valueCandidates`에 포함되는 값만 허용 (valueCandidates가 빈 배열일 경우 자유)\n- `unitValues`가 있을 경우 valueName은 해당 단위로 끝나는 값이어야 합니다.\n- `keyComment`와 `valueComment`가 있을 경우 해당 내용을 참조하여 입력해야 합니다.\n- `isOption = false`일 경우 필수 (2025.06.16: salesOption은 isOption 여부와 관계없이 전부 필수값입니다.)\n- `isOneOfRequiredGroup = true`인 그룹 중 **최소 1개 이상** 반드시 포함해야 등록 가능\n- `categorySalesOptions.id = 373` (key=\"수량\")의 경우 재고 수량이 아닌, 옵션의 구성 수량을 의미합니다. 토스 쇼핑 파트너스에서 노출되는 구성 수량과 일치합니다.","operationId":"getProductConstraintTemplates","parameters":[{"name":"categoryId","in":"path","description":"카테고리 ID (말단 카테고리만 허용)","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/GetProductConstraintTemplatesFepResponse"}}}}}}}}}}}
```

## 정보제공 고시 카테고리 목록 조회

> 상품등록에 필요한 정보제공 고시 카테고리를 조회합니다. 상세내용은 정보제공 고시 항목 조회 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":{"ListNoticeCategoriesResponse":{"required":["items"],"type":"object","properties":{"items":{"type":"array","description":"정보제공고시 카테고리 코드 목록","items":{"$ref":"#/components/schemas/ListNoticeCategoriesResponseItem"}}},"description":"상품 정보제공 고시 카테고리 코드 응답"},"ListNoticeCategoriesResponseItem":{"required":["categoryCode","firstCategoryName","secondCategoryName"],"type":"object","properties":{"categoryCode":{"type":"string","description":"카테고리 코드"},"firstCategoryName":{"type":"string","description":"1차 카테고리 이름"},"secondCategoryName":{"type":"string","description":"2차 카테고리 이름"}},"description":"상품 정보제공 고시 카테고리 코드 항목"}}},"paths":{"/api/v3/shopping-fep/notices/category-codes":{"get":{"tags":["정보제공고시"],"summary":"정보제공 고시 카테고리 목록 조회","description":"상품등록에 필요한 정보제공 고시 카테고리를 조회합니다. 상세내용은 정보제공 고시 항목 조회 API로 조회가 필요합니다.","operationId":"listNoticesCategories_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","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/ListNoticeCategoriesResponse"}}}}}}}}}}}
```

## 정보제공 고시 항목 조회

> 정보제공 고시 항목을 조회합니다.\
> 정보제공 고시 카테고리 목록 조회 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":{"GetNoticeFepResponse":{"required":["items"],"type":"object","properties":{"items":{"type":"array","description":"상품 정보제공 고시 항목","items":{"$ref":"#/components/schemas/GetNoticeResponseFepItem"}}},"description":"상품 정보제공 고시 항목 응답"},"GetNoticeResponseFepItem":{"required":["id","title"],"type":"object","properties":{"id":{"type":"integer","description":"상품 정보제공 고시 항목 식별용 ID","format":"int64"},"title":{"type":"string","description":"(삭제 예정) 상품 정보제공 고시 항목"}},"description":"정보제공 고시 항목"}}},"paths":{"/api/v3/shopping-fep/notices":{"get":{"tags":["정보제공고시"],"summary":"정보제공 고시 항목 조회","description":"정보제공 고시 항목을 조회합니다.\n정보제공 고시 카테고리 목록 조회 API를 통해 얻은 카테고리 코드를 이용하여 호출합니다.\n응답은 상품 등록시에 활용하게 됩니다.","operationId":"listNotices_1","parameters":[{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}},{"name":"categoryCode","in":"query","description":"카테고리 코드","required":true,"schema":{"type":"string","enum":["CLOTHING","SHOES","BAG","FASHION_MISCELLANEOUS_GOODS","BEDDING_CURTAIN","FURNITURE","VIDEO_APPLIANCES","SEASONAL_APPLIANCES","OFFICE_APPLIANCES","SMALL_ELECTRONICS","PORTABLE_COMMUNICATION_DEVICES","HOME_APPLIANCES","OPTICAL_DEVICES","AUTO_SUPPLIES","MEDICAL_DEVICES","KITCHEN_UTENSILS","COSMETICS","PRECIOUS_METAL","AGRICULTURAL_MARINE_LIVESTOCK_PRODUCTS","PROCESSED_FOOD","HEALTH_FUNCTIONAL_FOOD","CHILD_PRODUCTS","INSTRUMENT","SPORTS_PRODUCTS","CONSUMER_CHEMICAL_PRODUCTS","BIOCIDE_PRODUCTS","QUASI_DRUG","BOOK","ACCOMMODATION","PACKAGE_TOUR","AIRLINE_TICKET","RENTAL_CAR","RENTAL_WATER_PURIFIER_BIDET_AIR_CLEANER","RENTAL_BOOK_BABY_EVENT_GOODS","DIGITAL_CONTENT","GIFT_CARD","MOBILE_COUPON","MOVIE_SHOW","ETC_SERVICE","ETC_GOODS","NAVIGATION"]}}],"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","InvalidRequest","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/GetNoticeFepResponse"}}}}}}}}}}}
```

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

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