OptionRequest – Kakao Shopping Open API

옵션관리 API에서 사용합니다. 옵션정보와 본상품 재고수량를 포함합니다.

키	타입	필수여부	설명
stockQuantity	Integer	선택	본상품 재고 수량
option	Option	필수	옵션 정보

Option

옵션의 type 필드는 필수 값이며, 옵션 없는 상품일 경우 “NONE” type 으로 전송하시면 됩니다.

독립형 옵션일 경우 정렬 기준을 선택할 수 있으며, simpleSortType 필드 (OptionSortType 타입) 의 값이 비어 있을 경우 default (등록순) 기준이 적용 됩니다.

조합형 옵션일 경우 정렬 기준을 선택할 수 있으며,combinationSortType 필드 (OptionSortType 타입)의 값이 비어 있을 경우 default (등록순) 기준이 적용 됩니다.

작성형 옵션일 경우에는 정렬 기준은 default (등록순) 기준이 적용 됩니다.

조합형 옵션일 경우 combinations 필드 (Array<Combinations> 타입) 와 combinationAttributes 필드(Array<CombinationAttribute> 타입) 는 필수 입력 값입니다.

주의사항

상품 수정 또는 옵션 수정 요청시 옵션의 전체 목록 데이터를 전부 입력해야 합니다.(기 등록한 옵션의 옵션값 텍스트/재고수량/옵션가격 등 일부 정보를 변경하는 경우에도 옵션 전체 목록 데이터를 모두 입력해야 하며, 모든 옵션의 옵션id 값이 포함되어야 합니다.)

기 등록한 옵션명 하위에 일부 옵션값을 추가/삭제 하거나, 옵션명 구분을 추가해야 하는 경우에는 옵션 전체 목록을 신규 등록해 주셔야 합니다.

*조합형 옵션 등록시 옵션가 0원인 옵션이 최소 1개 이상 등록되어야 합니다.

수정 시 주의사항

옵션 수정 api 요청시, 기 등록된 옵션의 옵션 텍스트/재고수량/옵션가격 등 일부 정보를 변경하는 경우에도 
옵션 전체 목록 데이터를 모두 입력해야 하며, 모든 옵션의 옵션id 값이 포함되어야 합니다.

<옵션 없는 상품 샘플>

{
  "type":"NONE"
}

<독립형 옵션 샘플>

{
  "type":"SIMPLE",
  "simples":[
    {
      "name":"사이즈",
      "value":"M",
      "usable":true
    }
  ]
}

<조합형 옵션 샘플>

{
  "type":"COMBINATION",
  "combinations":[
    {
      "name":[
        {
          "key":"사이즈",
          "value":"M"
        },
        {
          "key":"컬러",
          "value":"RED"
        }
      ],
      "price":"0",
      "stockQuantity":50,
      "managedCode":"SY",
      "usable":true
    }
  ],
  "combinationAttributes":[
    {
      "name":"사이즈",
      "value":"M"
    },
    {
      "name":"컬러",
      "value":"RED"
    }
  ],
  "optionDisplay": {
    "useInstantOrder": true,
    "instantOrderTemplateType": "TYPE_1"
  }
}

<작성형 옵션 샘플>

{
  "type":"CUSTOM",
  "customs":[
    {
      "name":"길이를 입력해 주세요.",
      "usable":true
    }
  ]
}

<독립형+작성형 옵션 샘플>

{
  "type":"SIMPLE_CUSTOM",
  "simples":[
    {
      "name":"사이즈",
      "value":"M",
      "usable":true
    }
  ],
  "customs":[
    {
      "name":"길이를 입력해 주세요.",
      "usable":true
    }
  ]
}

<조합형+작성형 옵션 샘플>

{
  "type":"COMBINATION_CUSTOM",
  "combinations":[
    {
      "name":[
        {
          "key":"사이즈",
          "value":"M"
        },
        {
          "key":"컬러",
          "value":"RED"
        }
      ],
      "price":"0",
      "stockQuantity":50,
      "managedCode":"SY",
      "usable":true
    }
  ],
  "combinationAttributes":[
    {
      "name":"사이즈",
      "value":"M"
    },
    {
      "name":"컬러",
      "value":"RED"
    }
  ],
  "customs":[
    {
      "name":"길이를 입력해 주세요.",
      "usable":true
    }
  ],
  "optionDisplay": {
    "useInstantOrder": true,
    "instantOrderTemplateType": "TYPE_1"
  }
}

필드상세

필드명	타입	필수여부	설명
type	OptionType	필수	옵션타입
simpleSortType	OptionSortType	선택	독립형 리스팅 기준
combinationSortType	OptionSortType	선택	조합형 리스팅 기준
simples	Array<Simple>	선택	독립형 옵션 리스트
combinations	Array<Combination>	선택	조합형 옵션의 최종 리스트
combinationAttributes	Array<CombinationAttribute>	선택	조합형 옵션 리스트
customs	Array<Custom>	선택	작성형 옵션 리스트
optionDisplay	OptionDisplay	선택	옵션 노출 정보

OptionType

옵션타입은 크게 선택형과 작성형으로 구분됩니다.

선택형은 주문시 판매자가 미리 설정해둔 옵션 리스트 중에서 구매자가 선택하는 방식이고, 작성형은 주문시 구매자가 주문하려는 옵션 내용을 직접 작성하는 방식입니다.

‘선택형’은 다시 독립형과 조합형으로 옵션형태가 구분되어 선택할 수 있는데, 그중 조합형만 옵션가, 옵션별 재고수량, 옵션 관리코드 및 옵션이미지를 설정할 수 있습니다.

타입명	설명
NONE	옵션 없음
SIMPLE	독립형
COMBINATION	조합형
CUSTOM	작성형
SIMPLE_CUSTOM	독립형 + 작성형
COMBINATION_CUSTOM	조합형 + 작성형

OptionSortType

독립형 및 조합형 옵션의 정렬 기준을 나타냅니다.

타입명	설명
CREATE	등록순
ABC	가나다순
LOW_PRICE	낮은 가격순
HIGH_PRICE	높은 가격순

Simple

필드 제약사항

# 옵션명
  - 컬러, 사이즈, 스타일 등 상품 선택 속성을 의미하는 옵션명은 숫자로만 이루어 질 수 없습니다.
  - 선택형 옵션의 옵션명은 최대 3개까지 등록 가능하며, 옵션명별 하위 옵션값은 최대 100개까지만 등록 가능합니다.

[
  {
    "name":"사이즈",
    "value":"M",
    "usable":true
  }
]

필드명	타입	필수여부	설명
name	String	필수	옵션명 (옵션명 숫자만 입력 불가)
value	String	필수	옵션값
usable	Boolean	필수	사용여부. 제약사항 참고

Combination

필드 제약사항

# 옵션가
  - 옵션가는 판매가 -50% 이상 +100% 이하 설정 가능 합니다.
  - 최소 10원 단위 설정 가능합니다.
  - 마이너스 옵션가 등록 시도시 즉시할인 설정 체크하여 ‘(판매가+마이너스옵션가(최대값))-즉시할인’ 금액이 마이너스인 경우 
설정 불가 합니다.

# 재고수량
  - 재고수량은 최소 1개 이상 최대 9999개 이하로 설정 가능합니다.

# 문자열 길이제한
  - 선택형,조합형, 작성형 옵션명은 20자까지 입력 가능합니다.
  - 선택형,조합형 옵션값은 25자까지 입력 가능합니다.

# 옵션 등록 갯수 제한
  - 컬러, 사이즈, 스타일 등 상품 선택 속성을 의미하는 옵션명은 최대 3개까지 등록 가능하며, 옵션명별 하위 옵션값은 
최대 100개 까지만 등록 가능합니다.
  - 상품의 하위 최종 옵션 갯수는 최대 1000개로 제한됩니다.

[
  {
    "name":[
        {
          "key":"사이즈",
          "value":"M"
        },
        {
          "key":"컬러",
          "value":"RED"
        }
    ],
    "price":300,
    "stockQuantity":50,
    "managedCode":"SY",
    "usable":true
  }
]

필드명	타입	필수여부	설명
name	Array	필수	조합된 최종 옵션
usable	Boolean	필수	사용여부. 제약사항 참고
price	BigDecimal	필수	옵션가
stockQuantity	Integer	필수	옵션재고
managedCode	String	선택	옵션별 판매자 관리코드

CombinationAttribute

필드 제약사항

# 옵션명
  - 상품 선택 속성을 의미하는 옵션명은 숫자로만 이루어 질 수 없습니다.

# 옵션이미지 설정
  - 조합형 옵션의 최상위 옵션명 하위 옵션값 단위로 옵션이미지 설정이 가능합니다. 
  설정 시, 상품상세 옵션 선택 영역에 해당 이미지가 함께 노출됩니다.
  - 옵션이미지를 설정한 경우, '옵션 바로구매' 설정이 가능합니다. 
  상품상세설명 하단에 옵션별 이미지/상세 이미지/옵션 추가금액 및 옵션별 구매 버튼이 노출되어 옵션 선택이 편리합니다.
  - 옵션상세이미지까지 등록하시면 옵션바로구매 영역에 [자세히] 버튼을 해당 이미지 확인이 가능합니다.

# 옵션이미지/상세이미지 제약사항
  - 옵션이미지 : 1:1 비율로 고정 노출
  - 옵션상세이미지 : 최대 3개까지 등록가능
  - 외부 이미지의 경우, UTF-8 방식을 사용해서 인코딩된 URL만 허용합니다.

[
  {
    "name":"사이즈",
    "value":"M",
    "optionImage": {
      "representImage": {
        "url":"https://st.kakaocdn.net/shoppingstore/product/a.png"
      },
      "optionalImages": [
        {
          "url":"https://st.kakaocdn.net/shoppingstore/product/b.png"
        },{
          "url":"https://st.kakaocdn.net/shoppingstore/product/c.png"
        }
      ]
    }
  },
  {
    "name":"사이즈",
    "value":"L",
    "optionImage": {
      "representImage": {
        "url":"https://st.kakaocdn.net/shoppingstore/product/a.png"
      },
      "optionalImages": [
        {
          "url":"https://st.kakaocdn.net/shoppingstore/product/b.png"
        },{
          "url":"https://st.kakaocdn.net/shoppingstore/product/c.png"
        }
      ]
    }
  },
  {
    "name":"컬러",
    "value":"RED"
  }
]

필드명	타입	필수여부	설명
name	String	필수	조합형 옵션명 (옵션명 숫자만 입력 불가)
value	String	필수	조합형 옵션값
optionImage	OptionImage	선택	옵션 이미지

Custom

필드 제약사항

# 옵션명
  - 상품 선택 속성을 의미하는 옵션명은 숫자로만 이루어 질 수 없습니다.
  - 작성형 옵션명은 최대 5개 까지 등록 가능합니다.

[
  {
    "name":"사이즈를 입력해주세요.",
    "usable":true
  },
  {
    "name":"컬러는 어떤걸 하시겠습니까?",
    "usable":true
  }
]

필드명	타입	필수여부	설명
name	String	필수	작성형 옵션명 (옵션명 숫자만 입력 불가)
usable	Boolean	필수	사용여부. 제약사항 참고

OptionDisplay

필드 제약사항

# 옵션 바로구매
  - 조합형 옵션에 옵션 이미지를 등록하신 경우에만 설정이 가능합니다.

{
  "useInstantOrder": true,
  "instantOrderTemplateType": "TYPE_1"
}

필드명	타입	필수여부	설명
useInstantOrder	Boolean	선택	바로구매 설정 여부
instantOrderTemplateType	InstantOrderTemplateType	선택	바로구매 템플릿 유형

InstantOrderTemplateType

타입명	설명
TYPE_1	1열 (가로형)
TYPE_2	2열 (세로형)

이 섹션의 문서

Option

주의사항

수정 시 주의사항

<옵션 없는 상품 샘플>

<독립형 옵션 샘플>

<조합형 옵션 샘플>

<작성형 옵션 샘플>

<독립형+작성형 옵션 샘플>

<조합형+작성형 옵션 샘플>

필드상세

OptionType

OptionSortType

Simple

필드 제약사항

Combination

필드 제약사항

CombinationAttribute

필드 제약사항

Custom

필드 제약사항

OptionDisplay

필드 제약사항

InstantOrderTemplateType

관련 문서