naver-shopping-search

SKILL.md

Naver Shopping Search

What this skill does

k-skill-proxy가 네이버 검색 Open API 쇼핑 검색(shop.json)을 우선 사용하고, 키가 없을 때만 네이버 쇼핑/검색의 로그인 없는 공개 BFF JSON endpoint를 단일 검색 요청으로 가져와 상품 후보를 정규화한다.

상품명/검색어로 네이버 쇼핑 후보를 찾는다.

현재 노출 가격, 판매처, 링크, 이미지, 리뷰/구매 수(노출될 때만)를 정리한다.

가격이 낮은 후보와 공식몰/브랜드몰 후보를 분리해서 비교할 수 있다.

주문, 장바구니, 찜, 로그인 세션 접근은 하지 않는다.

When to use

"네이버 쇼핑에서 에어팟 가격 비교해줘"

"네이버 최저가로 커피머신 찾아줘"

"네이버 쇼핑 링크랑 판매처별 가격을 비교해줘"

"이 상품 네이버 쇼핑에서 얼마쯤 해?"

When not to use

회원 전용가, 쿠폰 적용가, 네이버페이 개인화 혜택을 확정해야 하는 경우

주문/장바구니/찜/로그인이 필요한 액션

차단 우회, CAPTCHA 우회, fingerprint spoofing 등 접근 통제를 우회해야 하는 경우

Required inputs

상품명 또는 검색어가 없으면 먼저 물어본다.

권장 질문:

찾을 네이버 쇼핑 상품명이나 검색어를 알려주세요. 예: 에어팟 프로 2세대, 아이폰 15 케이스

검색어가 너무 넓으면 브랜드/용량/모델명을 추가로 물어본다.

Proxy endpoint

기본값은 public/read-only/no-auth 프록시다. 프록시 서버에 NAVER_SEARCH_CLIENT_ID와 NAVER_SEARCH_CLIENT_SECRET이 있으면 공식 Search API를 우선 사용한다.

curl -fsS --get "${KSKILL_PROXY_BASE_URL:-http://127.0.0.1:4020}/v1/naver-shopping/search" \
  --data-urlencode 'q=에어팟 프로 2세대' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'sort=rel'

쿼리 파라미터:

q 또는 query — 검색어. 2글자 이상.

limit — 반환 개수. 기본 10, 최대 40으로 clamp.

page — 페이지. 기본 1. no-key BFF fallback에서는 BFF의 page를 요청하고 해당 페이지 카드만 정규화한다.

sort — rel, date, price_asc, price_dsc, review 중 하나. 알 수 없는 값은 rel.

공식 Search API 경로는 네이버 API sort를 사용한다. 단, 공식 API가 review 정렬을 지원하지 않아 review 요청은 upstream sort=sim으로 조회하고 meta.sort_applied: "unsupported", meta.upstream_sort: "sim"으로 표시한다.

no-key BFF fallback은 rel은 BFF 노출 순서를 유지하고, price_asc/price_dsc/review는 선택된 BFF 페이지 카드 안에서 로컬 정렬한다. BFF 카드에 날짜 필드가 없어 date는 meta.sort_applied: "unsupported"로 표시하고 BFF 노출 순서를 유지한다.

응답 주요 필드:

items[].title

items[].price / items[].price_text

items[].mall_name

items[].url

items[].image_url

items[].review_count, purchase_count, score (노출될 때만)

meta.extraction — naver-openapi, bff-json, embedded-json, html-card, none

meta.sort_applied — upstream, local, unsupported 중 하나

Workflow

검색어를 확인한다.

GET /v1/naver-shopping/search 를 호출한다.

items가 있으면 요청 sort와 meta.sort_applied를 확인한 뒤 가격 낮은 순, 공식/브랜드몰 여부, 리뷰 수 등을 기준으로 3~5개 후보를 짧게 비교한다.

meta.extraction과 조회 시각 기준임을 함께 말한다.

items가 비었거나 upstream 차단/오류가 나면 우회 시도를 반복하지 말고, 검색어를 좁히거나 브라우저 수동 확인을 안내한다.

Response style

가격은 "조회 시점 네이버 쇼핑 노출가"라고 표현한다.

배송비, 쿠폰, 옵션 추가금, 회원 혜택은 비로그인 공개 검색만으로 확정하지 않는다.

판매처 신뢰도는 노출된 판매처명/리뷰 수만 근거로 보수적으로 말한다.

최저가만 단정하지 말고 동률/옵션 차이를 조심한다.

Failure modes

공식 Search API 키가 없어서 BFF fallback을 사용할 때는 네이버가 특정 IP/환경에 418/403 등 bot-block 응답을 줄 수 있다.

no-key fallback은 ns-portal.shopping.naver.com/api/v2/shopping-paged-slot?query=<검색어>&source=shp_gui 공개 JSON path를 사용한다.

검색 결과 BFF JSON 스키마는 비공식 프론트엔드 표면이라 바뀔 수 있다.

가격/품절/배송 정보는 실시간으로 바뀐다.

프록시는 접근 통제 우회를 하지 않는다. 공식 Search API 또는 단일 공개 검색 요청 + 캐시 + rate limit만 사용한다.

Done when

검색어를 확인했다.

네이버 쇼핑 후보를 최소 1개 이상 반환하거나, 왜 반환하지 못했는지 설명했다.

가격/판매처/링크를 조회 시점 기준으로 보수적으로 정리했다.

로그인/주문/차단 우회 범위를 벗어나지 않았다.