naver-shopping-search

Original：🇺🇸 English
Translated

네이버 쇼핑 공개 BFF JSON을 k-skill-proxy로 조회해 상품 후보, 최저가, 판매처 링크를 보수적으로 가격비교한다.

12installs
Sourcenomadamas/k-skill
Added on

NPX Install

npx skill4agent add nomadamas/k-skill naver-shopping-search

Tags

Translated version includes tags in frontmatter
naver-shoppingk-skill-proxyprice-comparisonapi-proxyshopping-search

SKILL.md Content

View Translation Comparison →

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를 우선 사용한다.
bash
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개 이상 반환하거나, 왜 반환하지 못했는지 설명했다.
  • 가격/판매처/링크를 조회 시점 기준으로 보수적으로 정리했다.
  • 로그인/주문/차단 우회 범위를 벗어나지 않았다.