[공지] 필수 구매옵션 입력 의무화 및 API 변경 안내 (2026년 2월 2일 시행)

안녕하세요. 쿠팡입니다.

기존 운영되고 있는 상품정보 정책에 따라, 쿠팡이 요청하는 속성값은 판매를 위한 필수 입력사항입니다. 고객에게 더 나은 쇼핑 경험을 제공하기 위해, 신규 및 기존 등록 상품에 대해 해당 카테고리에서 요구하는 필수 구매옵션 입력 여부에 대한 모니터링을 강화할 예정입니다.

필수 구매옵션 입력이 누락된 경우, 아래와 같이 상품 노출 제한 또는 등록 실패가 발생할 수 있으니 아래 기술 변경 사항을 반드시 확인하시기 바랍니다. 본 정책은 신규 상품뿐만 아니라 기존 등록 상품에 대해서도 순차 적용됩니다.

본 문서의 업데이트 내용은 한국 마켓에만 적용되며, 대만(TW) 사용자에게는 영향을 미치지 않습니다.

1. 정책 개요

• 시행 일자: 2026년 2월 2일부터 순차적 적용
• 주요 조치 내용: 
  • 상품 노출 제한: 필수 구매옵션 누락 시 WING 내 '노출 제한'으로 표시되며 검색 노출이 차단될 수 있습니다.
  • 상품 등록 실패: 필수 구매옵션 누락 시 API를 통한 상품 등록 요청이 거절되거나 최종 등록에 실패할 수 있습니다.

2. API 주요 변경 사항

1）상품 생성 (Product Creation)

필수 속성 누락 시 오류 원인을 명확히 식별할 수 있도록 응답 메시지가 강화되었습니다.

• 응답 스펙 업데이트: details 및 errorItems 필드에 "필수 구매 옵션 (미입력 시 등록/노출 제한) 존재하지 않습니다" 메시지 추가.
• 오류 응답 예시 (ERROR):

{
    "code": "ERROR",
    "message": "[]. 유효하지 않은 구매 옵션 값 혹은 단위가 존재합니다.",
    "details": "... 다음과 같이 필수 구매 옵션 (미입력시 등록/노출 제한)을 입력해주세요. : '총 수량'. 자세한 사항은 아래 errorItems 에서 확인할 수 있습니다.",
    "errorItems": [
        {
            "itemIndex": 0,
            "itemAttributes": [
                {
                    "attributeTypeName": "총 수량",
                    "message": "필수 구매 옵션 (미입력 시 등록/노출 제한) 존재하지 않습니다."
                }
            ]
        }
    ]
}

2）상품 수정 (승인필요) (Modify Product)

오픈 속성(Open Attributes) 관리 방식 업데이트  및 입력값 검증 로직이 강화되었습니다.

• 오픈 속성(Open Attributes) 관리:
  • 삭제 방법: 페이로드의 attributes 리스트에서 해당 속성 요소를 제외하면 삭제됩니다.
  • 식별 방법: [카테고리 메타 정보 조회 API] 응답에 해당 attributeTypeName이 없는 경우 오픈 속성으로 간주합니다.
• 오류 스펙 업데이트 (400 Request Variable Confirmation):
  • 유효하지 않은 데이터 형식/단위 입력 시 오류 발생
  • 카테고리별로 정의된 유효한 값 이외 입력 시 요청 거절

3）상품 목록 페이징 조회 (Product List Paging Query)

노출 제한된 상품을 식별하기 위한 신규 쿼리 파라미터가 추가되었습니다.

• 신규 파라미터: 
  •  violationTypes (String List): 위반 유형 필터링 (NO_VA_V2, MOTA_V2, ATTR)
    • NO_VA_V2:  상품정보 검증이 필요한 상품 (노출제한)
    • MOTA_V2: 누락된 필수 구매옵션을 입력해야하는 상품 (노출제한)
    • ATTR: 옵션 수정이 필요한 상품 (노출낮음)
  • violationTypeAndOr (String): 필터링 논리 연산 설정 (AND, OR)
• 요청 예시: GET /api/v1/marketplace/seller-products?vendorId={vendorId}&violationTypes=ATTR&violationTypes=MOTA_V2&violationTypeAndOr=OR

3. 개발자 대응 요청 사항

1. 에러 핸들링: 상품 생성 시 반환되는 상세 errorItems 메시지를 판매자 시스템 UI에 노출하여 즉각적인 수정이 가능하도록 대응해 주십시오.
2. 노출 제한 상품 점검: [상품 목록 페이징 조회 API]의 violationTypes 파라미터 중 하나인 "MOTA_V2"를 활용해 “필수 구매옵션이 누락”된 상품들을 조회하십시오.
3. 수정 및 승인: 노출 제한을 해제하기 위해 [상품 수정 API]를 통해 유효한 필수 구매옵션을 입력하거나 수정해주세요. 입력/수정 시 상태가 '심사중'으로 변경되며, 승인 완료 후 정상 노출됩니다.

정확한 상품 정보 입력은 고객의 구매 전환율을 높이는 핵심 요소입니다. 판매자님의 성공이 쿠팡의 성공인 만큼, 개발자분들의 적극적인 협조 부탁드립니다.

감사합니다.