naver-shopping-search（naver 购物搜索）

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

1. 검색어를 확인한다.
2. GET /v1/naver-shopping/search 를 호출한다.
3. items가 있으면 요청 sort와 meta.sort_applied를 확인한 뒤 가격 낮은 순, 공식/브랜드몰 여부, 리뷰 수 등을 기준으로 3~5개 후보를 짧게 비교한다.
4. meta.extraction과 조회 시각 기준임을 함께 말한다.
5. 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개 이상 반환하거나, 왜 반환하지 못했는지 설명했다.
• 가격/판매처/링크를 조회 시점 기준으로 보수적으로 정리했다.
• 로그인/주문/차단 우회 범위를 벗어나지 않았다.