k-skill/docs/features/naver-shopping-search.md

네이버 쇼핑 가격비교 가이드

이 기능으로 할 수 있는 일

• 네이버 쇼핑 상품 검색
• 현재 노출 가격과 판매처 비교
• 상품 링크/이미지/리뷰 수 등 공개 노출 메타데이터 정리
• 가격 후보를 3~5개로 줄여 보수적으로 추천

먼저 필요한 것

• 인터넷 연결
• k-skill-proxy 실행 또는 KSKILL_PROXY_BASE_URL
• 네이버 로그인/사용자 계정은 필요 없음

공식/공개 표면

• 공개 BFF JSON: https://ns-portal.shopping.naver.com/api/v2/shopping-paged-slot?query=<검색어>&source=shp_gui
• 프록시 endpoint: GET /v1/naver-shopping/search

프록시에 NAVER_SEARCH_CLIENT_ID와 NAVER_SEARCH_CLIENT_SECRET이 있으면 네이버 검색 Open API의 쇼핑 검색(shop.json)을 우선 사용한다. 키가 없으면 네이버 검색/쇼핑 프론트엔드가 사용하는 공개 BFF JSON endpoint를 단일 요청으로 읽는다. BFF fallback은 스키마 변경이나 bot-block 응답이 있을 수 있으며, 접근 통제를 우회하지 않는다.

기본 호출

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/naver-shopping/search' \
  --data-urlencode 'q=에어팟 프로 2세대' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'sort=rel'

로컬 proxy:

curl -fsS --get 'http://127.0.0.1:4020/v1/naver-shopping/search' \
  --data-urlencode 'q=아이폰 15 케이스' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'sort=price_asc'

입력값

• q 또는 query: 검색어. 2글자 이상.
• limit: 반환 개수. 기본 10, 최대 40.
• page: 페이지. 기본 1. no-key BFF fallback은 BFF page를 요청하고 해당 페이지 카드만 정규화한다.
• sort: rel, date, price_asc, price_dsc, review.
  • 공식 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에는 날짜 정렬용 카드 필드가 없어 no-key date 요청은 meta.sort_applied: "unsupported"로 표시하고 BFF 노출 순서를 유지한다.

응답 예시

{
  "items": [
    {
      "rank": 1,
      "product_id": "1234567890",
      "title": "애플 정품 20W USB-C 전원 어댑터",
      "price": 23900,
      "price_text": "23,900원",
      "mall_name": "Apple 공식스토어",
      "url": "https://search.shopping.naver.com/catalog/1234567890",
      "image_url": "https://shop-phinf.pstatic.net/main_1234567890.jpg",
      "category": ["디지털/가전", "휴대폰액세서리"],
      "review_count": 1234,
      "purchase_count": 56,
      "score": 4.8,
      "is_ad": false,
      "source": "bff-json"
    }
  ],
  "query": {
    "q": "애플 어댑터",
    "limit": 10,
    "page": 1,
    "sort": "rel"
  },
  "meta": {
    "query": "애플 어댑터",
    "extraction": "bff-json",
    "item_count": 1,
    "page": 1,
    "sort": "rel",
    "sort_applied": "upstream"
  }
}

기본 흐름

1. 상품명/검색어가 없으면 먼저 물어본다.
2. q로 프록시를 호출한다.
3. 가격, 판매처, 링크가 있는 후보만 비교한다.
4. 가격 낮은 순으로 정리하되, 광고 여부/공식몰/리뷰 수를 함께 언급한다.
5. 가격과 재고는 조회 시점 기준이며 쿠폰·배송비·옵션가는 확정하지 않는다고 말한다.

운영 팁

• 모델명, 용량, 색상, 세대 정보를 검색어에 포함하면 가격 비교 품질이 좋아진다.
• 네이버가 특정 서버/IP에 418/403 등을 반환하면 같은 요청을 반복해 우회하지 말고 사용자에게 수동 확인 또는 검색어 조정을 안내한다.
• no-key fallback은 기존 search.shopping.naver.com/search/all HTML 페이지가 아니라 ns-portal.shopping.naver.com/api/v2/shopping-paged-slot JSON path를 사용한다.
• no-key fallback의 가격/리뷰 정렬은 BFF가 반환한 선택 페이지 내부의 로컬 정렬이다. 전체 네이버 쇼핑 결과에 대한 전역 최저가/최다리뷰 정렬이 필요하면 공식 Search API 키를 설정한다.
• proxy route는 public/read-only/no-auth이며 cache와 rate limit을 사용한다.
• 운영 환경에는 가능하면 NAVER_SEARCH_CLIENT_ID/NAVER_SEARCH_CLIENT_SECRET을 설정해 공식 Search API 경로를 우선 사용한다.