풀필먼트 스타배송 추천옵션 관리 API

Description

옵션 등록/수정 : [PUT] https://sa2.esmplus.com/item/v1/goods/{goodsNo}/recommended-options
등록한 옵션 조회 : [GET] https://sa2.esmplus.com/item/v1/goods/{goodsNo}/recommended-options
카테고리별 옵션코드 조회 : [GET] https://sa2.esmplus.com/item/v1/options/recommended-opts?catCode={siteCatCode}
옵션별 선택항목코드 조회 : [GET] https://sa2.esmplus.com/item/v1/options/recommended-opts/{recommendedOptNo}

3PL상품은 추천옵션으로 사용 가능하며, 선택형 / 2개 조합선택형 옵션으로 등록/수정 할 수 있습니다.
3PL상품의 경우, 텍스트형 옵션은 사용 불가합니다.
카테고리별 사용 가능한 주문옵션의 유형이 다르므로 추천옵션코드/선택항목코드 조회 API를 통해 조회된 코드를 사용합니다.

Request Description

항목	항목명	필수여부	Type	Description
type	추천옵션 타입 (ESM상 주문옵션)	Y	int	추천옵션 사용여부 0:옵션미사용 1: 선택형(최대 20개까지 가능)/independent 2: 2개조합형(최대 200개까지 가능)/combination * 옵션 타입이 선택형일 경우, independent / 2개 조합형일 경우, combination 항목값으로 필수 연동 * 추천옵션은 상품의 G/A 카테고리가 모두 추천옵션 허용 될 경우만 등록/수정 가능 *옵션 가능개수는 추후 변경될 수 있음
isStockManage	옵션재고관리	Y	Boolean	추천옵션 사용일 경우 필수
independent > recommendedOptNo	(선택형/조합형) 추천옵션코드	Y	int	추천옵션 사용일 경우 필수 추천옵션코드조회 API에서 매칭된 코드 입력
independent > details > recommendedOptValueNo	(선택형/조합형) 추천옵션항목코드	Y	int	추천옵션 사용일 경우 필수 추천옵션선택항목코드조회 API에서 매칭된 코드 입력
independent > details > recommendedOptValue > koreanText	(선택형/조합형) 추천옵션항목 (국문)직접입력		string	추천옵션항목코드를 사용하지 않고 직접입력할 경우 *색상 등 직접입력 허용된 추천옵션코드에서만 사용 가능
independent > details > recommendedOptValue > englishText	(선택형/조합형) 추천옵션항목 (영문)직접입력		string
independent > details > recommendedOptValue > chineseText	(선택형/조합형) 추천옵션항목 (중문)직접입력		string
independent > details > recommendedOptValue > japaneseText	(선택형/조합형) 추천옵션항목 (일문)직접입력		string
independent > details > recommendedOptValue > exposeLanguage	노출언어 선택		int	옵션 다국어 중, 구매자에게 노출되고 싶은 언어 선택 *조회 시, 무조건 0으로 내려감 1 :한국어 2: 영어한글표시 3: 영어 직접입력한 경우, 영어한글표시가 없기때문에 한국어가 영어한글표시로 들어감
independent > details > isSoldOut	(선택형/조합형) 품절여부	Y	Boolean	추천옵션 사용일 경우 필수 옵션의 품절여부 제어(옵션 재고수량으로 제어하지 않음) true : 품절 false : 판매
independent > details > isDisplay	(선택형/조합형) 노출여부	Y	Boolean	추천옵션 사용일 경우 필수 옵션의 노출여부 제어 true : 노출 false : 미노출
independent > details > qty > gmkt	(선택형/조합형) G마켓 재고수량	Y	int	추천옵션 사용일 경우 필수 1~99999로 설정 *3PL 상품은 입력한 값이 무시되고 해당 SKU의 재고가 자동으로 연동됩니다.
independent > details > qty > iac	(선택형/조합형) 옥션 재고수량	Y	int	추천옵션 사용일 경우 필수 1~99999로 설정 *3PL 상품은 입력한 값이 무시되고 해당 SKU의 재고가 자동으로 연동됩니다.
independent > details > manageCode	(선택형/조합형) 판매자옵션관리코드	Y	int	추천옵션 사용일 경우 필수 해당 옵션의 판매자가 관리하는 코드 입력
independent > details > epinCode	ESM 상품분류코드	Y		현재 API 제공하지 않아 null로 호출
independent > details > skuInfo > skuId	SKU번호	Y	int	추천옵션 사용일 경우 필수 해당 추천옵션의 SKU코드 입력
independent > details > skuInfo > owQty	SKU 출고방식	Y	int	추천옵션 사용일 경우 필수 해당 추천옵션 SKU당 출고수 입력
text > details > value > isDisplay	(텍스트형) 노출여부	Y		3PL상품은 텍스트형 옵션 사용불가함으로 null로 호출
text > details > value > recommendedOptNo	(텍스트형) 추천옵션코드	Y		3PL상품은 텍스트형 옵션 사용불가함으로 null로 호출
catCode	Site카테고리코드	Y	Path	카테고리별 추천옵션코드 조회 request Path값 G마켓 or 옥션 사이트카테고리 코드 입력
recommendedOptNo	추천옵션그룹코드	Y	Path	추천옵션별 선택항목코드 조회 request Path값

JSON
등록/수정
{
  "type": "Unknown",
  "isStockManage": true,
  "independent": {
    "details": [
      {
        "recommendedOptValueNo": 0,
        "recommendedOptValue": {
          "koreanText": "string",
          "englishText": "string",
          "chineseText": "string",
          "japaneseText": "string",
          "exposeLanguage": "Unknown"
        },
        "isSoldOut": true,
        "isDisplay": true,
        "qty": {
          "iac": 0,
          "gmkt": 0
        },
        "manageCode": "string",
        "epinCode": 0,
        "skuInfo": [
          {
            "skuId": 0,
            "owQty": 0
          }
        ]
      }
    ],
    "recommendedOptNo": 0
  },
  "combination": {
    "details": [
      {
        "recommendedOptValueNo1": 0,
        "recommendedOptValueNo2": 0,
        "recommendedOptValue1": {
          "koreanText": "string",
          "englishText": "string",
          "chineseText": "string",
          "japaneseText": "string",
          "exposeLanguage": "Unknown"
        },
        "recommendedOptValue2": {
          "koreanText": "string",
          "englishText": "string",
          "chineseText": "string",
          "japaneseText": "string",
          "exposeLanguage": "Unknown"
        },
        "isSoldOut": true,
        "isDisplay": true,
        "qty": {
          "iac": 0,
          "gmkt": 0
        },
        "manageCode": "string",
        "epinCode": 0,
        "skuInfo": [
          {
            "skuId": 0,
            "owQty": 0
          }
        ]
      }
    ],
    "recommendedOptNo1": 0,
    "recommendedOptNo2": 0
  },
  "text": {
    "details": [
      {
        "recommendedOptNo": 0,
        "isDisplay": true,
        "Value": "string"
      }
    ]
  }
}

조회 - URL만 호출 / Request Body 없음
등록한 옵션 조회
GET https://sa.esmplus.com/item/v1/goods/1695445640/recommended-options

카테고리별 추천옵션코드 조회
GET http://sa.esmplus.com/item/v1/options/recommended-opts?catCode=300023931

추천옵션별 선택항목코드 조회
GET https://sa.esmplus.com/item/v1/options/recommended-opts/976

Response Description

항목	항목명	Type	Description
goodsNo	마스터상품번호	int	조회 시 내려가는 정보
resultCode	결과코드	int	실패 시 내려가는 정보
message	메시지	string	실패 시 내려가는 정보
data	데이터	object	실패 시 내려가는 정보
details > recommendedOptNo	추천옵션코드	int	카테고리별 추천옵션코드 조회 시 내려가는 정보
details > recommendedOptName > kor	(국문) 추천옵션명	string	카테고리별 추천옵션코드 조회 시 내려가는 정보
details > recommendedOptName > eng	(영문) 추천옵션명	string	카테고리별 추천옵션코드 조회 시 내려가는 정보
details > recommendedOptName > jpn	(일문) 추천옵션명	string	카테고리별 추천옵션코드 조회 시 내려가는 정보
details > recommendedOptTypeName	추천옵션구분명	string	카테고리별 추천옵션코드 조회 시 내려가는 정보
type	옵션타입	int	추천옵션별 선택항목코드 조회 시 내려가는 정보 옵션 타입 관련 내부 코드
typeName	옵션타입명	string	추천옵션별 선택항목코드 조회 시 내려가는 정보 추천옵션 관련 내부 구분명
recommendedOptNo	추천옵션코드	int	추천옵션별 선택항목코드 조회 시 내려가는 정보 조회한 추천옵션코드
recommendedOptName > kor	추천옵션명	string	추천옵션별 선택항목코드 조회 시 내려가는 정보 조회한 추천옵션코드의 추천옵션명
recommendedOptName > eng	(영문) 추천옵션명	string	추천옵션별 선택항목코드 조회 시 내려가는 정보
recommendedOptName > chi	(중문) 추천옵션명	string	추천옵션별 선택항목코드 조회 시 내려가는 정보
recommendedOptName > jpn	(일문) 추천옵션명	string	추천옵션별 선택항목코드 조회 시 내려가는 정보
isTextOption	텍스트형 옵션여부	boolean	추천옵션별 선택항목코드 조회 시 내려가는 정보 해당 추천옵션그룹이 텍스트형인지 여부 true: 텍스트형 false: 텍스트형 아님
details > recommendedOptValueNo	선택항목코드	int	추천옵션별 선택항목코드 조회 시 내려가는 정보 사용할 선택항목명의 코드를 옵션 등록 시 입력 * 텍스트형일 경우 내려가지 않음
details > recommendedOptValueName > kor	(국문) 선택항목코드	int	추천옵션별 선택항목코드 조회 시 내려가는 정보 조회한 추천옵션코드에 속하는 선택항목명 노출 * 텍스트형일 경우 내려가지 않음
details > recommendedOptValueName > eng	(영문) 선택항목코드	int	추천옵션별 선택항목코드 조회 시 내려가는 정보 조회한 추천옵션코드에 속하는 선택항목명 노출 * 텍스트형일 경우 내려가지 않음
details > recommendedOptValueName > chi	(중문) 선택항목코드	int	추천옵션별 선택항목코드 조회 시 내려가는 정보 조회한 추천옵션코드에 속하는 선택항목명 노출 * 텍스트형일 경우 내려가지 않음
details > recommendedOptValueName > jpn	(일문) 선택항목코드	int	추천옵션별 선택항목코드 조회 시 내려가는 정보 조회한 추천옵션코드에 속하는 선택항목명 노출 * 텍스트형일 경우 내려가지 않음

JSON_Success

등록/수정
{
  "goodsNo": 0
}

조회
{
  "type": "Unknown",
  "isStockManage": true,
  "independent": {
    "details": [
      {
        "recommendedOptValueNo": 0,
        "recommendedOptValue": {
          "koreanText": "string",
          "englishText": "string",
          "chineseText": "string",
          "japaneseText": "string",
          "exposeLanguage": "Unknown"
        },
        "isSoldOut": true,
        "isDisplay": true,
        "qty": {
          "iac": 0,
          "gmkt": 0
        },
        "manageCode": "string",
        "epinCode": 0,
        "skuInfo": [
          {
            "skuId": 0,
            "owQty": 0
          }
        ]
      }
    ],
    "recommendedOptNo": 0
  },
  "combination": {
    "details": [
      {
        "recommendedOptValueNo1": 0,
        "recommendedOptValueNo2": 0,
        "recommendedOptValue1": {
          "koreanText": "string",
          "englishText": "string",
          "chineseText": "string",
          "japaneseText": "string",
          "exposeLanguage": "Unknown"
        },
        "recommendedOptValue2": {
          "koreanText": "string",
          "englishText": "string",
          "chineseText": "string",
          "japaneseText": "string",
          "exposeLanguage": "Unknown"
        },
        "isSoldOut": true,
        "isDisplay": true,
        "qty": {
          "iac": 0,
          "gmkt": 0
        },
        "manageCode": "string",
        "epinCode": 0,
        "skuInfo": [
          {
            "skuId": 0,
            "owQty": 0
          }
        ]
      }
    ],
    "recommendedOptNo1": 0,
    "recommendedOptNo2": 0
  },
  "text": {
    "details": [
      {
        "recommendedOptNo": 0,
        "isDisplay": true,
        "Value": "string"
      }
    ]
  }
}

카테고리별 옵션조회
{
  "details": [
    {
      "recommendedOptNo": 0,
      "recommendedOptName": {
        "kor": "string"
      },
      "recommendedOptTypeName": "string"
    }
  ]
}

옵션항목코드 조회
{
  "type": 0,
  "typeName": "string",
  "recommendedOptNo": 0,
  "recommendedOptName": {
    "kor": "string"
  },
  "details": [
    {
      "recommendedOptValueNo": 0,
      "recommendedOptValueName": {
        "kor": "string",
        "Eng": "string"
      }
    }
  ]
}

JSON_Fail

{
   "ResultCode": 0,
   "Message": "string",
   "Data": {}
}

Sample Code_Success

등록/수정
{
  "goodsNo": 1695445640
}

옵션조회 - 선택형
{
    "type": 1,
    "isStockManage": false,
    "independent": {
        "details": [
            {
                "recommendedOptValueNo": 14897,
                "recommendedOptValue": {
                    "koreanText": "검정",
                    "englishText": "Black",
                    "chineseText": "黑色",
                    "japaneseText": "ブラック",
                    "exposeLanguage": 0
                },
                "isSoldOut": false,
                "isDisplay": true,
                "qty": {
                    "iac": 99999,
                    "gmkt": 99999
                },
                "manageCode": null,
                "epinCode": null,
                "skuInfo": [
                    {
                        "skuId": 526713,
                        "owQty": 1
                    }
                ]
            },
            {
                "recommendedOptValueNo": 14900,
                "recommendedOptValue": {
                    "koreanText": "노랑",
                    "englishText": "Yellow",
                    "chineseText": "黄色",
                    "japaneseText": "イエロー",
                    "exposeLanguage": 0
                },
                "isSoldOut": false,
                "isDisplay": true,
                "qty": {
                    "iac": 99999,
                    "gmkt": 99999
                },
                "manageCode": null,
                "epinCode": null,
                "skuInfo": [
                    {
                        "skuId": 526712,
                        "owQty": 1
                    }
                ]
            }
        ],
        "recommendedOptNo": 1
    },
    "combination": null,
    "text": null
}

옵션조회 - 2개 조합형
{
    "type": 2,
    "isStockManage": false,
    "independent": null,
    "combination": {
        "details": [
            {
                "recommendedOptValueNo1": 14897,
                "recommendedOptValueNo2": 14992,
                "recommendedOptValue1": {
                    "koreanText": "검정",
                    "englishText": "Black",
                    "chineseText": "黑色",
                    "japaneseText": "ブラック",
                    "exposeLanguage": 0
                },
                "recommendedOptValue2": {
                    "koreanText": "M",
                    "englishText": "M",
                    "chineseText": "M",
                    "japaneseText": "M",
                    "exposeLanguage": 0
                },
                "isSoldOut": false,
                "isDisplay": true,
                "qty": {
                    "iac": 99999,
                    "gmkt": 99999
                },
                "manageCode": null,
                "epinCode": null,
                "skuInfo": [
                    {
                        "skuId": 526713,
                        "owQty": 1
                    }
                ]
            },
            {
                "recommendedOptValueNo1": 14897,
                "recommendedOptValueNo2": 14991,
                "recommendedOptValue1": {
                    "koreanText": "검정",
                    "englishText": "Black",
                    "chineseText": "黑色",
                    "japaneseText": "ブラック",
                    "exposeLanguage": 0
                },
                "recommendedOptValue2": {
                    "koreanText": "S",
                    "englishText": "S",
                    "chineseText": "S",
                    "japaneseText": "S",
                    "exposeLanguage": 0
                },
                "isSoldOut": false,
                "isDisplay": true,
                "qty": {
                    "iac": 99999,
                    "gmkt": 99999
                },
                "manageCode": null,
                "epinCode": null,
                "skuInfo": [
                    {
                        "skuId": 526712,
                        "owQty": 1
                    }
                ]
            },
            {
                "recommendedOptValueNo1": 14900,
                "recommendedOptValueNo2": 14992,
                "recommendedOptValue1": {
                    "koreanText": "노랑",
                    "englishText": "Yellow",
                    "chineseText": "黄色",
                    "japaneseText": "イエロー",
                    "exposeLanguage": 0
                },
                "recommendedOptValue2": {
                    "koreanText": "M",
                    "englishText": "M",
                    "chineseText": "M",
                    "japaneseText": "M",
                    "exposeLanguage": 0
                },
                "isSoldOut": false,
                "isDisplay": true,
                "qty": {
                    "iac": 99999,
                    "gmkt": 99999
                },
                "manageCode": null,
                "epinCode": null,
                "skuInfo": [
                    {
                        "skuId": 526711,
                        "owQty": 1
                    }
                ]
            },
            {
                "recommendedOptValueNo1": 14900,
                "recommendedOptValueNo2": 14991,
                "recommendedOptValue1": {
                    "koreanText": "노랑",
                    "englishText": "Yellow",
                    "chineseText": "黄色",
                    "japaneseText": "イエロー",
                    "exposeLanguage": 0
                },
                "recommendedOptValue2": {
                    "koreanText": "S",
                    "englishText": "S",
                    "chineseText": "S",
                    "japaneseText": "S",
                    "exposeLanguage": 0
                },
                "isSoldOut": false,
                "isDisplay": true,
                "qty": {
                    "iac": 99999,
                    "gmkt": 99999
                },
                "manageCode": null,
                "epinCode": null,
                "skuInfo": [
                    {
                        "skuId": 526710,
                        "owQty": 1
                    }
                ]
            }
        ],
        "recommendedOptNo1": 1,
        "recommendedOptNo2": 976
    },
    "text": null
}

카테고리별 옵션조회
{
    "details": [
        {
            "recommendedOptNo": 976,
            "recommendedOptName": {
                "kor": "사이즈",
                "eng": "Size",
                "chi": "尺寸",
                "jpn": "サイズ"
            },
            "recommendedOptTypeName": "의류"
        },
        {
            "recommendedOptNo": 1,
            "recommendedOptName": {
                "kor": "색상",
                "eng": "Color",
                "chi": "颜色",
                "jpn": "いろ"
            },
            "recommendedOptTypeName": "공통"
        }
    ]
}

추천옵션 코드 조회
    "type": 464,
    "typeName": "의류",
    "recommendedOptNo": 976,
    "recommendedOptName": {
        "kor": "사이즈",
        "eng": "Size",
        "chi": "尺寸",
        "jpn": "サイズ"
    },
    "isTextOption": false,
    "details": [
        {
            "recommendedOptValueNo": 21758,
            "recommendedOptValueName": {
                "korEng": "One Size/Free",
                "kor": "one size/free",
                "eng": "One Size/Free",
                "chi": "均码/Free",
                "jpn": "均码/Free"
            }
        },
        {
            "recommendedOptValueNo": 15391,
            "recommendedOptValueName": {
                "korEng": "XXS",
                "kor": "XXS",
                "eng": "XXS",
                "chi": "XXS",
                "jpn": "XXS"
            }
        }
    ]
}

Sample Code_Fail

{
  "ResultCode":1000,
  "Message":"선택형(Independent) 상세정보(Details) 항목은 20개까지 입력 가능합니다",
  "Data":null
}

Error Code

결과코드	메시지	원인
3000	모든 옵션이 품절인 상태로 등록이 불가합니다	모든 옵션의 isSoldOut이 true일 경우
1000	InvalidApiRequestEx][\"[IAC] 재고수량은 1~99999로 설정해 주세요.\",\"[GMKT] 재고수량은 1~99999로 설정해 주세요.\	재고수량 설정이 1~99999범위 벗어날 경우
3000	[Independent] 옵션 번호 오류 (0)	선택형의 옵션코드가 아닐 경우
1000	설정하신 텍스트형 추천옵션은 해당 카테고리에서 사용하실 수 없습니다	텍스트형의 옵션코드가 사용 불가한 카테고리 등록 상품인 경우
3000	시퀀스에 요소가 없습니다.	카테고리 코드 잘 못 되었거나 없는 카테고리 코드인 경우
1000	조회 된 데이터가 없습니다.	카테고리에 매칭된 옵션이 없을 경우
1000	선택형(Independent) 상세정보(Details) 항목은 20개까지 입력 가능합니다	선택형 항목 값 20개 초과했을 경우
1000	No Return Data	isLeaf가 true가 아닌 카테고리나 추천옵션이 없는 경우
3000	유효하지 않은 SKU_ID 입니다.()	유효하지 않은 skuID 입력한 경우
1000	SKU출고방식은 필수입력 항목입니다.	owQty 미입력한 경우
1000	SKU를 본상품/주문옵션 둘다 매핑시 등록이 불가능합니다.	추천옵션 사용안하는 상품이며, 추천옵션 등록API로 옵션 등록한 경우

'스타배송 API > 상품 등록, 수정' 카테고리의 다른 글

풀필먼트 스타배송 상품 등록/수정/조회 API (0)	2022.11.03
풀필먼트 스타배송 가격/판매상태 관리 API (0)	2022.10.11

ESM Trading API