3.7 주문옵션 관리 API – ESM Trading API

3.7 주문옵션 관리 API

옵션 등록/수정 : [PUT] https://sa.esmplus.com/item/v1/goods/{goodsNo}/recommended-options

등록한 옵션 조회 : [GET] https://sa.esmplus.com/item/v1/goods/{goodsNo}/recommended-options

카테고리별 추천옵션코드 조회 : [GET] https://sa.esmplus.com/item/v1/options/recommended-opts?catCode={siteCatCode}

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

Description
상품2.0은 추천주문옵션으로 사용 가능하며, 선택형 / 2개 조합선택형 / 텍스트형 옵션 등록/수정 할 수 있습니다
카테고리별 사용 가능한 주문옵션의 유형이 다르므로 추천옵션코드/선택항목코드 조회 API를 통해 조회된 코드를 사용합니다
Request Description
G마켓 / 옥션 상품 동시 관리 시, G마켓 ID & 옥션 ID 토큰으로 사용합니다
G마켓 상품만 관리 시, G마켓 ID의 토큰으로 사용합니다
옥션 상품만 관리 시, 옥션 ID의 토큰으로 사용합니다
항목항목명필수여부TypeDescription
type 추천옵션 타입
(ESM상 주문옵션)
Y int추천옵션 사용 여부
0 : 옵션 미사용
1 : 선택형 (최대 50개까지 가능), independent 로 입력
2 : 2개 조합형 (최대 500개까지 가능), combination 로 입력
3 : 3개 조합형 (최대 500개까지 가능), combination 로 입력
4 : 계산형, calculation 로 입력
5 : 텍스트형
6 : 선택형 + 텍스트형
7 : 2개조합형 + 텍스트형
8 : 3개 조합형 + 텍스트형
9 : 선택형 + 계산형
* 추천옵션은 G마켓/옥션 카테고리 모두 추천옵션 허용 경우만 등록/수정 가능
* 텍스트형 옵션 사용하는 경우 itemAddtionalInfo > recommendedOpts > isStockManage (옵션재고관리여부) false로 연동
* 2개 조합형 경우 주문옵션 관리 페이지에서 샘플 확인 가능 (https://etapi.ebaykorea.com/goods/listing/item-docid-3351/)
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 노출언어 선택 옵션 다국어 중, 구매자에게 노출되고 싶은 언어 선택
*조회 시, 무조건 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로 설정
independent > details > qty > iac(선택형/조합형)
옥션 재고수량
Y int추천옵션 사용일 경우 필수
G마켓 옵션 재고수량 입력
1~99999로 설정
independent > details > manageCode(선택형/조합형)
판매자옵션관리코드
Y string추천옵션 사용일 경우 필수
해당 옵션의 판매자가 관리하는 코드 입력
20 byte 이내 입력 가능
text > details > value > isDisplay(텍스트형)
노출여부
Y Boolean 텍스트형 사용할 경우 필수
텍스트형을 상품상세페이지에 노출할 것인지 여부 설정
true : 노출
false : 미노출
text > details > value > recommendedOptNo(텍스트형)
추천옵션코드
Y int추천옵션 사용일 경우 필수
추천옵션선택항목코드조회 API에서 매칭된 코드 입력
calculation > name1 > kor(계산형)
옵션명1
string
calculation > name2 > kor(계산형)
옵션명2
string
calculation > minValue1(계산형)
옵션명1 (name 1) 판매 최소값
int1 이상 입력 가능
calculation > minValue2(계산형)
옵션명2 (name 2) 판매 최소값
int1 이상 입력 가능
calculation > maxValue1(계산형)
옵션명1 (name 1) 판매 최대값
int1 이상 입력 가능
calculation > maxValue2(계산형)
옵션명2 (name 2) 판매 최대값
int1 이상 입력 가능
calculation > unitPrice(계산형)
단가 기준값
int1 이상 입력 가능
calculation > unitType(계산형)
판매 단위
string"mm", "cm", "m", "mg", "g", "kg", "ml", "l“ 만 입력 가능
calculation > unitValue(계산형)
판매 단위값
int1 이상 입력 가능
calculation > manageCode(계산형)
옵션관리코드
string20 byte 이내 입력 가능
catCodeSite카테고리코드YPath카테고리별 추천옵션코드 조회 request Path값
G마켓 or 옥션 사이트카테고리 코드 입력
recommendedOptNo추천옵션그룹코드YPath추천옵션별 선택항목코드 조회 request Path값
JSON_등록/수정JSON_조회Sample Code_등록/수정1Sample Code_등록/수정2Sample Code_등록/수정3
{
  "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
      }
    ],
    "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
      }
    ],
    "recommendedOptNo1": 0,
    "recommendedOptNo2": 0
  },
  "text": {
    "details": [
      {
        "recommendedOptNo": 0,
        "isDisplay": true
      }
    ]
  }
}

URL만 호출 / Request Body 없음
등록한 옵션 조회
GET https://sa.esmplus.com/item/v1/goods/1158387297/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
{
  "type": 1,
  "isStockManage": true,
  "independent": {
    "details": [
      {
        "recommendedOptValueNo": 9368,
        "recommendedOptValue": {
          "koreanText": "그라파이트",
          "englishText": null,
          "chineseText": null,
          "japaneseText": null,
          "exposeLanguage": 0
        },
        "isSoldOut": false,
        "isDisplay": true,
        "qty": {
          "iac": 10,
          "gmkt": 20
        },
        "manageCode": "AA11",
        "epinCode": null
      },
      {
        "recommendedOptValueNo": 23890,
        "recommendedOptValue": {
          "koreanText": "그린옐로우",
          "englishText": null,
          "chineseText": null,
          "japaneseText": null,
          "exposeLanguage": 0
        },
        "isSoldOut": false,
        "isDisplay": true,
        "qty": {
          "iac": 10,
          "gmkt": 20
        },
        "manageCode": "BB22",
        "epinCode": null
      },
      {
        "recommendedOptValueNo": 0,
        "recommendedOptValue": {
          "koreanText": "흙색",
          "englishText": null,
          "chineseText": null,
          "japaneseText": null,
          "exposeLanguage": 0
        },
        "isSoldOut": false,
        "isDisplay": true,
        "qty": {
          "iac": 10,
          "gmkt": 20
        },
        "manageCode": "CC33",
        "epinCode": null
      }
    ],
    "recommendedOptNo": 1
  },
  "combination": null,
  "text": null
}
{
      "type": 2,
      "isStockManage": false,
      "independent": null,
      "combination": {
        "details": [
          {
            "recommendedOptValueNo1": 15139,
            "recommendedOptValueNo2": 23732,
            "isSoldOut": false,
            "isDisplay": true,
            "qty": {
              "iac": 100,
              "gmkt": 100
            },
            "manageCode": "",
            "epinCode": null
          },
          {
            "recommendedOptValueNo1": 15139,
            "recommendedOptValueNo2": 21773,
            "isSoldOut": false,
            "isDisplay": true,
            "qty": {
              "iac": 100,
              "gmkt": 100
            },
            "manageCode": "",
            "epinCode": null
          },
          {
            "recommendedOptValueNo1": 15139,
            "recommendedOptValueNo2": 23733,
            "isSoldOut": false,
            "isDisplay": true,
            "qty": {
              "iac": 100,
              "gmkt": 100
            },
            "manageCode": "",
            "epinCode": null
          },
          {
            "recommendedOptValueNo1": 15139,
            "recommendedOptValueNo2": 23734,
            "isSoldOut": false,
            "isDisplay": true,
            "qty": {
              "iac": 100,
              "gmkt": 100
            },
            "manageCode": "",
            "epinCode": null
          },
          {
            "recommendedOptValueNo1": 15139,
            "recommendedOptValueNo2": 21789,
            "isSoldOut": false,
            "isDisplay": true,
            "qty": {
              "iac": 100,
              "gmkt": 100
            },
            "manageCode": "",
            "epinCode": null
          },
          {
            "recommendedOptValueNo1": 15139,
            "recommendedOptValueNo2": 23579,
            "isSoldOut": false,
            "isDisplay": true,
            "qty": {
              "iac": 100,
              "gmkt": 100
            },
            "manageCode": "",
            "epinCode": null
          },
          {
            "recommendedOptValueNo1": 15139,
            "recommendedOptValueNo2": 23559,
            "isSoldOut": false,
            "isDisplay": true,
            "qty": {
              "iac": 100,
              "gmkt": 100
            },
            "manageCode": "",
            "epinCode": null
          },
          {
            "recommendedOptValueNo1": 15139,
            "recommendedOptValueNo2": 23622,
            "isSoldOut": false,
            "isDisplay": true,
            "qty": {
              "iac": 100,
              "gmkt": 100
            },
            "manageCode": "",
            "epinCode": null
          },
          {
            "recommendedOptValueNo1": 15139,
            "recommendedOptValueNo2": 23633,
            "isSoldOut": false,
            "isDisplay": true,
            "qty": {
              "iac": 100,
              "gmkt": 100
            },
            "manageCode": "",
            "epinCode": null
          },
          {
            "recommendedOptValueNo1": 15139,
            "recommendedOptValueNo2": 23562,
            "isSoldOut": false,
            "isDisplay": true,
            "qty": {
              "iac": 100,
              "gmkt": 100
            },
            "manageCode": "",
            "epinCode": null
          }
        ],
        "recommendedOptNo1": 1,
        "recommendedOptNo2": 976
      }
    }


{
  "type": 5,
  "isStockManage": false,
  "independent": null,
  "combination": null,
  "text": {
    "details": [
      {
        "recommendedOptNo": 877,
        "isDisplay": true
      }
    ]
  }
}

Response Description
항목항목명TypeDescription
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_등록/수정JSON_Success_옵션조회JSON_Success_카테고리별 옵션조회JSON_Success_추천옵션항목코드 조회JSON_FailSample Code_Success_등록/수정Sample Code_Success_옵션조회Sample Code_Success_카테고리별 옵션조회Sample Code_Success_추천옵션항목코드 조회Sample Code_Fail
{
  "goodsNo": 0
}
{
  "type": "Unknown",
  "isStockManage": true,
  "independent": [
    {
      "name": {
        "kor": "string",
        "eng": "string",
        "chi": "string",
        "jpn": "string"
      },
      "details": [
        {
          "value": {
            "kor": "string",
            "eng": "string",
            "chi": "string",
            "jpn": "string"
          },
          "isSoldOut": true,
          "isDisplay": true,
          "qty": {
            "iac": 0,
            "gmkt": 0
          },
          "manageCode": "string",
          "epinCode": 0
        }
      ]
    }
  ],
  "combination": {
    "name1": {
      "kor": "string",
      "eng": "string",
      "chi": "string",
      "jpn": "string"
    },
    "name2": {
      "kor": "string",
      "eng": "string",
      "chi": "string",
      "jpn": "string"
    },
    "details": [
      {
        "value1": {
          "kor": "string",
          "eng": "string",
          "chi": "string",
          "jpn": "string"
        },
        "value2": {
          "kor": "string",
          "eng": "string",
          "chi": "string",
          "jpn": "string"
        },
        "isSoldOut": true,
        "isDisplay": true,
        "qty": {
          "iac": 0,
          "gmkt": 0
        },
        "manageCode": "string",
        "epinCode": 0
      }
    ]
  },
  "text": [
    {
      "name": {
        "kor": "string",
        "eng": "string",
        "chi": "string",
        "jpn": "string"
      },
      "isDisplay": true
    }
  ]
}
{
  "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"
      }
    }
  ]
}
{
   "ResultCode": 0,
   "Message": "string",
   "Data": {}
}
{
  "goodsNo": 1158387297
}
{
    "type": 1,
    "isStockManage": false,
    "independent": {
        "details": [
            {
                "recommendedOptValueNo": 885,
                "recommendedOptValue": {
                    "koreanText": "초코브라운",
                    "englishText": null,
                    "chineseText": null,
                    "japaneseText": null,
                    "exposeLanguage": 0
                },
                "isSoldOut": false,
                "isDisplay": true,
                "qty": {
                    "iac": 0,
                    "gmkt": 0
                },
                "manageCode": null,
                "epinCode": null
            }
        ],
        "recommendedOptNo": 1
    },
    "combination": null,
    "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"
            }
        }
    ]
}
{
  "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개 초과했을 경우
1000No Return DataisLeaf가 true가 아닌 카테고리나 추천옵션이 없는 경우