쇼피 API 문서 444개의 변경 기록을 다 세어 봤습니다: 조용히 필수가 되는 항목들

쇼피 API(외부 프로그램이 쇼피 가게 자료를 읽고 쓰도록 열어 둔 연결 규칙) 문서에서 변경은 조용하게 기록됩니다. 기능마다 페이지 맨 아래 Update Log 표에 날짜 하나와 영어 한 줄이 붙는 식입니다.

 
이 한 줄들이 몇 년 동안 얼마나 쌓였는지 직접 세어 봤습니다. 싹마켓 개발 과정에서 2026년 9월 11일, 쇼피 공개 API 문서를 통째로 내려받아 둔 사본이 있었기 때문입니다. 기능(메서드)은 444개이고, 변경 기록 표가 달린 문서는 422개였습니다. 표 안의 기록은 912줄이었고, 그중 날짜가 적힌 890줄을 연도별로 나눴습니다.
 
📊 연도별로 나눈 결과
2021년 3월부터 그해 말까지 134건, 2022년 212건, 2023년 48건, 2024년 131건, 2025년 251건이었습니다. 2026년은 9월 3일 기록까지 114건입니다. 2023년에 한 번 잠잠했다가 2024년부터 다시 늘었고, 가장 많이 쌓인 해는 2025년입니다.
숫자를 그대로 받아들이기 어려운 사정이 두 가지 있습니다. 하나는 문서 손질도 기록에 들어간다는 점입니다. 2022년 7월 한 달에만 87건이 몰렸는데, 그중 56건이 Add Error Example information, 곧 오류 예시를 문서에 더했다는 기록입니다. 기능이 바뀐 게 아니라 설명서가 두꺼워진 것입니다. 2025년 251건 가운데 128건은 New API, 새 기능이 생겼다는 기록입니다.
다른 하나는 오래된 기록이 덜 보인다는 점입니다. 받은 문서에서 기능 하나에 달린 기록은 많아야 5건이었고, 5건을 꽉 채운 기능이 62개였습니다. 그보다 앞선 변경은 이 사본에서 보이지 않으니, 앞쪽 해의 숫자는 실제보다 적게 잡혔을 수 있습니다.

 
🔍 기록이 있어도 놓치기 쉬운 이유
첫째, 흩어져 있습니다. 변경 기록은 기능마다 그 페이지에 따로 달려 있습니다. 사본이 한 폴더에 있었으니 한 번에 셀 수 있었지, 페이지를 하나씩 열었다면 444번을 눌러야 했습니다.
둘째, 내용이 없는 기록도 있습니다. 상품 등록(add_item)과 상품 수정(update_item) 문서에는 2026년 6월 24일자 기록 가운데 내용 칸에 2026-06-17 이라는 날짜만 적힌 줄이 있습니다. 무엇이 바뀌었는지는 기록만 봐서는 알 수 없습니다.
셋째, 기록과 항목 표가 따로 움직입니다. 올해 9월의 사례가 그렇습니다.
 
📌 2026년 9월 1일, 상품 상태 칸
상품 등록 문서의 Update Log 맨 위 줄입니다.
· Condition is required for BR → 상태 값(condition)을 브라질 가게 상품에는 반드시 넣어야 함

 
condition 은 상품이 NEW(새 상품)인지 USED(중고)인지 적는 칸입니다. 그런데 같은 문서의 요청 항목 표에서 이 칸의 필수 표시는 비어 있고, 쇼피 공개 문서 화면에서도 필수 여부가 False 로 나옵니다. 필수라는 말은 설명 끝의 Required for BR 이라는 한 마디에만 나옵니다.
같은 날 글로벌 상품 등록(add_global_item) 문서에도 Condition is required 라는 기록이 붙었습니다. 저희 사본에서 이쪽은 필수 칸이 Y 로 되어 있습니다. 이 기능은 문서에 중국 셀러센터(CNSC) 셀러 전용이라고 적혀 있습니다. 비슷한 기록이 같은 날 붙었는데도, 지금 보이는 모습은 한쪽은 필수 칸, 다른 쪽은 설명 문장으로 갈립니다.
 
🧩 필수 표시는 32개 중 7개
상품 등록 문서의 맨 윗단 요청 항목은 32개입니다. 그중 필수로 표시된 것은 가격, 설명, 무게, 상품명, 배송 채널, 카테고리, 이미지 일곱 가지입니다. 나머지 25개 가운데 몇몇은 조건이 붙으면 필수로 바뀝니다.
· attribute_list → 카테고리가 정한 필수 속성은 빠짐없이 넣어야 함
· brand → 카테고리에 따라 브랜드 정보가 필수 (브랜드 목록 조회 get_brand_list 의 is_mandatory, 곧 필수 여부로 확인)
· medicine_id → 인도네시아 현지 셀러용, 처방약·일반약 카테고리에서 빠지면 오류
카테고리마다 달라지는 조건은 조회 기능이 알려 주고, 그 조회 기능에 필수 여부 칸이 생긴 날도 변경 기록에 남아 있습니다.
· get_attribute_tree, 2023년 7월 새 기능 → 속성마다 mandatory(필수 여부)
· get_item_limit, 2024년 6월 → weight_limit·dimension_limit(카테고리별 무게·포장 크기 필수 여부가 이 안에 있음)
· get_item_limit, 2024년 10월 → size_chart_mandatory(사이즈표)
· get_item_limit, 2025년 1월 → gtin_validation_rule(GTIN 검사 규칙)
· get_product_certification_rule, 2025년 4월 새 기능 → 인증 필수 여부
GTIN 은 UPC·EAN·JAN 처럼 상품마다 붙는 8~14자리 식별 번호입니다. 검사 규칙은 세 가지입니다. Mandatory 면 형식이 맞는 번호가 꼭 있어야 하고, Flexible 이면 번호나 번호 없음을 뜻하는 00 중 하나는 꼭 넣어야 하고, Optional 이면 아예 비워도 됩니다.
 
⚠️ 반대로 조용히 빠지거나 이름이 바뀌는 칸
늘어나는 칸만 문제가 아닙니다. 2025년 9월 19일, 상품 등록·수정 문서에 인증 관련 요청 칸 certification_type 이 없어졌다는 기록이 붙었습니다. 계속 보내더라도 시스템이 무시한다고 적혀 있습니다. 보낸 쪽은 값이 들어갔다고 여기기 쉽습니다.
같은 달에는 옵션을 올리는 문서 다섯 개에, 문서에 적힌 옵션 구조 tier_variation 은 폐기됐으니 standardise_tier_variation 구조를 쓰라는 기록이 붙었습니다.
이름이 바뀐 칸도 있습니다. 2026년 7월 17일, 정산 상세(get_escrow_detail) 응답에서 브라질 현지 셀러에게만 나오는 묶음 상품 칸(kit_items) 아래 이름이 바뀌었습니다. 구성품 번호 mt_item_id 는 original_product_id 로, 구성품을 따로 팔 때 가격인 parent_item_price 는 original_price 로 바뀌는 식입니다. 옛 이름으로 값을 찾는 프로그램이라면 그 자리를 찾지 못합니다.
 
✅ 지금 저희가 하는 방식
쇼피 규칙을 확인할 때는 문서 사이트보다 받아 둔 사본을 먼저 찾습니다. 444개가 한 폴더에 있으니 condition 같은 짧은 단어도 모든 기능에서 한 번에 걸러 볼 수 있습니다. 셀러가 직접 할 일은 아니지만, 프로그램이나 외주를 고를 때는 아래를 물어볼 만합니다.
· 상품을 올리기 전에 그 카테고리의 필수 조건을 매번 새로 조회하는가
· 쇼피가 돌려준 영어 오류 문구를 고치지 않고 그대로 보여 주는가
· 정산 자료의 칸 이름이 바뀌었을 때 누가 언제 확인하는가
890건을 세어 보고 남은 결론은 하나입니다. 쇼피에서 필수 항목은 한 번 외우면 끝나는 목록이 아니라, 나라와 카테고리와 날짜에 따라 달라지는 답입니다. 어제 올라간 상품이 오늘 막혔다면 셀러의 실수가 아니라 쇼피 쪽 조건이 바뀐 것일 수 있습니다. 그 가능성을 아는 사장님은 막힌 등록 앞에서 덜 헤맵니다.