상품 등록 안내
이용량 제한
상품 등록/수정시에는 초당 30건 이하로 요청해주셔야 합니다. 초과시에는 이용량 초과로 인해 요청이 실패할 수 있습니다.
•
response_body의 error.errorCode = “TOO_MANY_REQUEST”로 응답이 내려오게 됩니다.
API 호출 순서
상품등록시 아래 API들을 이용하여 상품에 대한 메타데이터를 API에 채워주시면 됩니다.
•
•
•
URL
/api/v3/products:register-free-option
Method
POST
RequestBody(to Edit)
필드명 | 하위 필드 1 | 하위 필드 2 | 필수 여부 | 타입 | 설명 |
name | O | String | 상품명
정규식 기준: ^[0-9a-zA-Z가-힣 ()\-·\[\]/&+,~.*_#]{1,100}$ | ||
brandName | String | 브랜드명
정규식 기준 : [0-9a-zA-Z가-힣 *()-_+/.,]{1,50} | |||
categoryId | O | Number | 상품 카테고리 ID, 카테고리중에 isLeaf=true인 최하위 카테고리ID만 가능 | ||
stocks | O | List | 재고 목록 | ||
options | O | List | 재고 옵션그룹 이름 & 옵션값 이름
카테고리 제약사항에 따라 제한됩니다.
제약사항이 있는 경우에는 반드시 제약사항에 따라 입력이 가능하며 그외 옵션은 입력이 불가합니다.
기존 옵션이 부재한 상품의 경우에도 카테고리 제약사항에 맞게 입력이 필요합니다. | ||
groupName | O | String | 재고 옵션그룹 이름 (ex: 색상)
• groupName은 카테고리 제약사항 categorySalesOptions의 key
• isOption = false일 경우 필수
• isOneOfRequiredGroup = true인 그룹 중 최소 1개 이상 반드시 포함해야 등록 가능
• 허용 개수: 1~3개
• 허용 글자: [0-9a-zA-Z가-힣*()-_+/.]{1,10} | ||
valueName | O | String | 재고 옵션값 이름 (ex: 블랙)
• valueName은 valueCandidates에 포함되는 값만 허용 (valueCandidates가 빈 배열일 경우 자유)
• unitValues가 있을 경우 valueName은 해당 단위로 끝나는 값이어야합니다.
• keyComment와 valueComment가 있을 경우 해당 내용을 참조하여 입력해야합니다.
• 허용 개수: 1~30개
• 허용 글자: [0-9a-zA-Z가-힣*()-_+/.]{1,30} | ||
remainingCount | O | Number | 재고 수량
remainingCount가 0인 경우, 품절 상태로 자동 등록됩니다. | ||
isHide | O | Boolean | 숨김 여부 | ||
isMainPrice | O | Boolean | 대표 가격 여부
반드시 1개만 true여야 합니다. | ||
isSoldOut | O | Boolean | 품절 여부 | ||
originPrice | O | Number | 정상가 | ||
salePrice | O | Number | 판매가 (할인된 가격) | ||
isPurchasableAlone | Boolean | 단독 구매 가능 여부 (기본값 true)
해당 필드가 false인 옵션을 구매하는 경우에는 반드시, true인 옵션도 구매해야 구매가 가능합니다.
ex:
- 구매가능 : isPurchasableAlone true 본상품 + isPurchasableAlone false 사은품
- 구매 불가 : isPurchasableAlone false 사은품 | |||
searchOption | 어드민 상의 검색 키워드 (1 ~10자 이내) | ||||
searchOptionWithValue | O | Map<String, String> | • 카테고리 제약사항의 categorySearchOptions 를 참고
value는 valueCandidates에 포함되는 값만 허용 (valueCandidates가 빈 배열일 경우 빈값으로 올려주시면 됩니다)
• unitValues가 있을 경우에는 value는 해당 단위로 끝나는 값이어야합니다.
• keyComment와 valueComment가 있을 경우 해당 내용을 참조하여 입력해야합니다.
• isOption = false일 경우 필수
• ex:
"searchOptionWithValue" : { "용도": "실내용", "소재": "플라스틱", ... } | ||
managementCode | String | 옵션 관리 코드 | |||
representativeThumbnailImage | String | 옵션 별 대표 썸네일 이미지 URL | |||
order | O | Number | 정렬 순서 | ||
images | O | List | 이미지 목록(THUMBNAIL 1개, DESCRIPTION or DESCRIPTION_HTML1개 등록 필수)
이미지 url은 기존 사용하시는 사이트 이미지 URL을 업로드해주시면 내부적으로 다운로드하여 등록하게 됩니다. 만약 다운로드에 실패할 경우, 상품등록에 실패할 수 있습니다. | ||
type | O | String | 유형
• THUMBNAIL : 상품 썸네일 이미지, 1개 필수, 1개만 등록 가능합니다.
최소크기 600 x 600, 비율 : 1:1, 용량 2MB이하, JPG/PNG
• DESCRIPTION : 상품 설명 이미지, 1~50개
최소가로크기 600, 용량 5MB이하, JPG/PNG/GIF
• AD : 상품 광고 이미지, 0~1개
최소크기 600 x 240, 비율 2.5:1, JPG/PNG
• DESCRIPTION_HTML : 상품 설명 html, 1개 | ||
url | String | 이미지 URL 최대 255자 | |||
html | String | 상세 설명 이미지 HTML
html의 경우, 서버에서 sanitization 후 저장 | |||
order | O | Number | 정렬순서 (0부터 증가) | ||
exposure | O | Object | 사용자 노출과 관련된 정보 | ||
searchKeywords | O | List<String> | 어드민상 검색 태그
searchOption과 달리 제약사항 없이 자유롭게 입력 가능합니다.
없으면 emptyList로 요청. 키워드 당 1~10 글자 허용
실제 검색에 활용되는 키워드입니다.
허용 정규식 : [0-9a-zA-Z가-힣]{1,10} | ||
description | O | String | 상품 설명(0~1500글자)
AI 상품 추천에 사용돼요. 자세히 적을수록 더 적합한 고객에게 추천할 수 있어요. | ||
serialNumber | String | 모델명
허용 정규식: [0-9a-zA-Z가-힣 -_]{1,50} | |||
isTaxFree | O | Boolean | true(면세), false(과세) | ||
deliveryPolicy | O | Object | 배송 정책 | ||
deliveryMethod | O | Enum | 배송 방식
NORMAL : 일반 배송
TODAY_DELIVERY : 오늘 출고 | ||
deliveryDeadline | String | 출고 마감 시각 ("12시", "1시", "2시" 중 택1) | |||
deliveryLocationId | Number | 배송비 묶음 그룹 ID, null이면 묶음배송 불가
참고 | |||
deliveryFeeType | O | String | 배송비 유형
FREE : 무료
PAID : 유료
CONDITIONALLY_FREE : 조건부 무료배송 | ||
deliveryFee | O | Number | 기본 배송비 | ||
minimumPurchasePrice | O | Number | 조건부 무료배송 시 무료배송 조건 금액 | ||
isJejuAndIslandsMountainsDelivery | O | Boolean | 제주/도서산간 배송 가능여부 true/false | ||
jejuDeliveryFee | O | Number | 제주도 추가 배송비, isJejuAndIslandsMountainsDelivery 가 true일 경우 적용됩니다. | ||
islandsMountainsDeliveryFee | O | Number | 도서 산간 추가 배송비, isJejuAndIslandsMountainsDelivery 가 true일 경우 적용됩니다. | ||
exchangeOrReturnPolicy | O | Object | 교환/반품 정책 | ||
exchangeRefundLocationId | O | Number | 교환/반품지 ID
교환/반품지 조회 API 참조 | ||
refundOneWayDeliveryFee | O | Number | 반품 편도 배송비 | ||
exchangeRoundTripDeliveryFee | O | Number | 교환 왕복 배송비 | ||
applicationMethodDescription | O | String | 교환,환불 방법 설명, 1~500자 | ||
applicationTermDescription | O | String | 교환,환불 신청 가능 기간 설명, 1~500자 | ||
notice | O | Object | 상품 정보제공 고시 | ||
categoryCode | O | String | 상품 정보제공 고시 카테고리코드
| ||
items | O | List | 상품 정보제공 고시 항목 목록
| ||
id | O | Number | 정보제공 고시 항목 ID | ||
content | O | String | 고시 항목 내용(판매자 입력 정보)
1~4000자 | ||
isCultureDeduction | O | Boolean | 문화비 소득공제 가능 여부 | ||
managementCode | String | 상품 관리 코드 |
ResponseBody
필드명 | 하위 필드 1 | 하위 필드 2 | 필수 여부 | 타입 | 설명 |
resultType | O | String | 응답 결과 유형, 요청 성공실패 판단 기준
SUCCESS : 성공
FAIL : 실패 | ||
success | Object | 성공시 제공 | |||
id | O | Number | 상품 ID | ||
error | Object | 에러 객체, 에러 발생 시 제공 | |||
errorCode | O | String | 에러 코드 | ||
reason | String | 에러 사유 |
재고 stocks 옵션 예시
optionValue_1 x optionValue_2 x optionValue_3 x … x optionValue_n 순열로 나열하여 재고 정보 입력
•
ex) 종류 3개 * 컬러 2개 * 사이즈 2개 = 총 12개
종류 | 컬러 | 사이즈 |
불고기맛 | 블랙 | M |
불고기맛 | 블랙 | L |
불고기맛 | 화이트 | M |
불고기맛 | 화이트 | L |
매운닭갈비맛 | 블랙 | M |
매운닭갈비맛 | 블랙 | L |
매운닭갈비맛 | 화이트 | M |
매운닭갈비맛 | 화이트 | L |
허니갈릭맛 | 블랙 | M |
허니갈릭맛 | 블랙 | L |
허니갈릭맛 | 화이트 | M |
허니갈릭맛 | 화이트 | L |
RequestBody 예시
"stocks": [
{
"options": [
{
"groupName": "상품",
"valueName": "불고기맛"
},
{
"groupName": "컬러",
"valueName": "블랙"
},
{
"groupName": "사이즈",
"valueName": "M"
},
],
"remainingCount": 100,
"isHide": false,
"isMainPrice": true,
"isSoldOut": false,
"originPrice": 20000,
"salePrice": 18000,
"isPurchasableAlone": true,
"managementCode": "test",
"representativeThumbnailImage": "https://picsum.photos/200"
},
{
"options": [
{
"groupName": "상품",
"valueName": "불고기맛"
},
{
"groupName": "컬러",
"valueName": "블랙"
},
{
"groupName": "사이즈",
"valueName": "L"
},
],
"remainingCount": 100,
"isHide": false,
"isMainPrice": false,
"isSoldOut": false,
"originPrice": 20000,
"salePrice": 18000,
"isPurchasableAlone": true,
"managementCode": "test",
"representativeThumbnailImage": "https://picsum.photos/200"
},
{
"options": [
{
"groupName": "상품",
"valueName": "불고기맛"
},
{
"groupName": "컬러",
"valueName": "화이트"
},
{
"groupName": "사이즈",
"valueName": "M"
},
],
"remainingCount": 100,
"isHide": false,
"isMainPrice": false,
"isSoldOut": false,
"originPrice": 20000,
"salePrice": 18000,
"isPurchasableAlone": true,
"managementCode": "test",
"representativeThumbnailImage": "https://picsum.photos/200"
},
{
"options": [
{
"groupName": "상품",
"valueName": "불고기맛"
},
{
"groupName": "컬러",
"valueName": "화이트"
},
{
"groupName": "사이즈",
"valueName": "L"
},
],
"remainingCount": 100,
"isHide": false,
"isMainPrice": false,
"isSoldOut": false,
"originPrice": 20000,
"salePrice": 18000,
"isPurchasableAlone": true,
"managementCode": "test",
"representativeThumbnailImage": "https://picsum.photos/200"
},
{
"options": [
{
"groupName": "상품",
"valueName": "매운닭갈비맛"
},
{
"groupName": "컬러",
"valueName": "블랙"
},
{
"groupName": "사이즈",
"valueName": "M"
},
],
"remainingCount": 100,
"isHide": false,
"isMainPrice": false,
"isSoldOut": false,
"originPrice": 20000,
"salePrice": 18000,
"isPurchasableAlone": true,
"managementCode": "test",
"representativeThumbnailImage": "https://picsum.photos/200"
},
...
]
Kotlin
복사
상품등록 Request body
{
// 상품명
"productName": "string",
// 브랜드명
"brandName": "string",
// 상품 옵션 정보
"items": [{
// 옵션명
"name": "string",
// 수량
"quantity": "number",
// 정상가
"originPrice": "number",
// 판매가
"regularSalePrice": "number",
// 관리 코드
"managementCode": "string"?,
// 아이템 썸네일 이미지 목록. 중요도 순으로 앞순서로 놓으세요
"images": ["string"]?,
"deliveryPolicy": {
// "배송 타입 (`NORMAL`: 일반배송, `NO_DELIVERY`: 배송없음, `DIRECT_DELIVERY`: 직접배송, `PREFERRED_DATE`: 희망일배송, `PRE_ORDER`: 예약배송)"
"deliveryType": "string"?,
//
"groupDeliveryLocationId": "number"?,
// 배송 속도 (NORMAL: 일반 배송, TODAY_DELIVERY: 당일 배송)
"deliverySpeed": "string"?
// 상품 준비 기간 (일 단위)
"preparationDays": number?,
// 출고 마감 시각 (HH:mm 형식)
"deliveryCutoffTime": string?
// 배송비 유형 (FREE, PAID, CONDITIONALLY_FREE)
"deliveryFeeType": string?
// 기본 배송비
"deliveryFee": number?,
// 무료 배송 최소 구매 금액
"minimumPurchasePrice": number?,
// 제주/도서산간 배송 가능 여부
"canLongDistanceDelivery": boolean?
// 제주 배송비
"jejuDeliveryFee": number?,
// 도서산간 배송비
"islandsMountainsDeliveryFee": number,
// 택배사 id
"deliveryCompanyId": nunmber?
}
}],
// descriptionImageUrls와 descriptionHtml는 둘 중에 하나만 null
"images": {
// 썸네일 이미지 url 목록 1 ~ 10개. 중요도 순으로 앞순서로 놓으세요
"thumbnailUrls": ["string"],
// 광고 이미지. 중요도 순으로 앞순서로 놓으세요
"adImageUrls": ["string"],
// 상품 상세 이미지인 경우 url 목록. 이 필드가 null이거나 empty면 descriptionHtml 존재해야 한다. 중요도 순으로 앞순서로 놓으세요
"descriptionImageUrls": ["string"]?,
// 상품 상세 html인 경우. 이 필드가 null이면 descriptionImageUrls가 존재해야 한다. 중요도 순으로 앞순서로 놓으세요
"descriptionHtml": "string"?
},
// 과세 & 면세 여부
"isTaxFree": "boolean",
"exchangeReturnPolicy": {
// 교환 반품지 그룹 id
"exchangeRefundLocationId": "number",
// 반품 배송비 (편도)
"refundOneWayDeliveryFee": "number",
// 교환 배송비(왕복)
"exchangeRoundTripDeliveryFee": "number",
// "교환/반품 신청 기한 설명
"applicationTermDescription": "string"
},
// 필수 고시정보 notice -> mandatoryNotice
"mandatoryNotice": {
"categoryCode": "string",
"items": [{
"id": "number",
"content": "string"
}]
},
// 연동사 기준 카테고리 및 기타 정보 (각각 최대 길이 몇자로 할지 고민)
// 메타데이터 항목이 늘어날 수 있어 보여서 depth를 하나 더 두었습니다
"metadata": {
// 연동사 기준 카테고리 패스
// ex. 식품>냉장/냉동식품>냉장냉동 간편조리>만두>군만두
"category_path": "string"?
}?,
// 연동사 기준 상품을 식별할 수 있는 코드
"partnerProductCode": "string"
// 문화비 소득공제 대상
"isCultureDeduction": "boolean",
// 상품 관리 코드. 최대 20자
"managementCode": "string"?
}
JavaScript
복사
상품등록 Response body(sample)
{
"resultType": "SUCCESS",
"error": null,
"success": {}
}
JavaScript
복사
여기부터
상품 등록 요청 (Apply)
request
{
// 상품명
"productName": "string",
// 브랜드명
"brandName": "string",
// stocks에서 이름 변경
"items": [{
// 자유 옵션명
"name": "string",
// 수량
"quantity": "number",
// 정상가
"originPrice": "number",
// 판매가
"regularSalePrice": "number",
// 관리 코드
"managementCode": "string"?,
// 아이템 썸네일 이미지 목록. 중요도 순으로 앞순서로 놓으세요
"images": ["string"]?,
"deliveryPolicy": {
// "배송 타입 (`NORMAL`: 일반배송, `NO_DELIVERY`: 배송없음, `DIRECT_DELIVERY`: 직접배송, `PREFERRED_DATE`: 희망일배송, `PRE_ORDER`: 예약배송)"
"deliveryType": "string"?,
//
"groupDeliveryLocationId": "number"?,
// 배송 속도 (NORMAL: 일반 배송, TODAY_DELIVERY: 당일 배송)
"deliverySpeed": "string"?
// 상품 준비 기간 (일 단위)
"preparationDays": number?,
// 출고 마감 시각 (HH:mm 형식)
"deliveryCutoffTime": string?
// 배송비 유형 (FREE, PAID, CONDITIONALLY_FREE)
"deliveryFeeType": string?
// 기본 배송비
"deliveryFee": number?,
// 무료 배송 최소 구매 금액
"minimumPurchasePrice": number?,
// 제주/도서산간 배송 가능 여부
"canLongDistanceDelivery": boolean?
// 제주 배송비
"jejuDeliveryFee": number?,
// 도서산간 배송비
"islandsMountainsDeliveryFee": number,
// 택배사 id
"deliveryCompanyId": nunmber?
}
}],
// descriptionImageUrls와 descriptionHtml는 둘 중에 하나만 null
"images": {
// 썸네일 이미지 url 목록 1 ~ 10개. 중요도 순으로 앞순서로 놓으세요
"thumbnailUrls": ["string"],
// 광고 이미지. 중요도 순으로 앞순서로 놓으세요
"adImageUrls": ["string"],
// 상품 상세 이미지인 경우 url 목록. 이 필드가 null이거나 empty면 descriptionHtml 존재해야 한다. 중요도 순으로 앞순서로 놓으세요
"descriptionImageUrls": ["string"]?,
// 상품 상세 html인 경우. 이 필드가 null이면 descriptionImageUrls가 존재해야 한다. 중요도 순으로 앞순서로 놓으세요
"descriptionHtml": "string"?
},
// 과세 & 면세 여부
"isTaxFree": "boolean",
"exchangeReturnPolicy": {
// 교환 반품지 그룹 id
"exchangeRefundLocationId": "number",
// 반품 배송비 (편도)
"refundOneWayDeliveryFee": "number",
// 교환 배송비(왕복)
"exchangeRoundTripDeliveryFee": "number",
// "교환/반품 신청 기한 설명
"applicationTermDescription": "string"
},
// 필수 고시정보 notice -> mandatoryNotice
"mandatoryNotice": {
"categoryCode": "string",
"items": [{
"id": "number",
"content": "string"
}]
},
// 연동사 기준 카테고리 및 기타 정보 (각각 최대 길이 몇자로 할지 고민)
// 메타데이터 항목이 늘어날 수 있어 보여서 depth를 하나 더 두었습니다
"metadata": {
// 연동사 기준 카테고리 패스
// ex. 식품>냉장/냉동식품>냉장냉동 간편조리>만두>군만두
"category_path": "string"?
}?,
// 연동사 기준 상품을 식별할 수 있는 코드
"partnerProductCode": "string"
// 문화비 소득공제 대상
"isCultureDeduction": "boolean",
// 상품 관리 코드. 최대 20자
"managementCode": "string"?
}
JSON
복사
response
{
// 응답 결과 타입, SUCCESS / FAIL
"resultType": "string"?,
// 에러 응답, resultType FAIL 시 제공
"error": {
"errorCode": "string"?,
"reason": "string"?
}?,
// 성공시 제공, 별도 내용이 없습니다. {}으로 반환
"success": {}?
}
JSON
복사