naver-shopping-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Naver Shopping Search

Naver购物搜索

What this skill does

本Skill的功能

k-skill-proxy

가 네이버 검색 Open API 쇼핑 검색(

shop.json

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

상품명/검색어로 네이버 쇼핑 후보를 찾는다.
현재 노출 가격, 판매처, 링크, 이미지, 리뷰/구매 수(노출될 때만)를 정리한다.
가격이 낮은 후보와 공식몰/브랜드몰 후보를 분리해서 비교할 수 있다.
주문, 장바구니, 찜, 로그인 세션 접근은 하지 않는다.

k-skill-proxy

优先使用Naver搜索Open API购物搜索(

shop.json

)，仅在无密钥时，通过单次搜索请求获取Naver购物/搜索无需登录的公开BFF JSON端点，对商品候选进行标准化处理。

根据商品名/搜索词查找Naver购物候选商品。
整理当前显示价格、销售商、链接、图片、评论/购买数量（仅在显示时）。
可分离低价候选商品与官方店/品牌店候选商品进行对比。
不访问订单、购物车、收藏、登录会话。

When to use

使用场景

"네이버 쇼핑에서 에어팟 가격 비교해줘"
"네이버 최저가로 커피머신 찾아줘"
"네이버 쇼핑 링크랑 판매처별 가격을 비교해줘"
"이 상품 네이버 쇼핑에서 얼마쯤 해?"

"帮我对比Naver购物上AirPods的价格"
"帮我找Naver上最低价的咖啡机"
"帮我对比Naver购物的链接和各销售商的价格"
"这个商品在Naver购物上大概多少钱？"

When not to use

不适用场景

회원 전용가, 쿠폰 적용가, 네이버페이 개인화 혜택을 확정해야 하는 경우
주문/장바구니/찜/로그인이 필요한 액션
차단 우회, CAPTCHA 우회, fingerprint spoofing 등 접근 통제를 우회해야 하는 경우

需要确定会员专享价、优惠券适用价、Naver Pay个性化优惠的情况
需要下单/加入购物车/收藏/登录的操作
需要绕过拦截、CAPTCHA验证、指纹伪装等访问控制的情况

Required inputs

必要输入

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

권장 질문:

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

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

若无商品名或搜索词，会先询问用户。

推荐提问：

请告知要查找的Naver购物商品名或搜索词。例如：AirPods Pro 2代、iPhone 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

중 하나

默认是公开/只读/无需授权的代理。若代理服务器上存在

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。
```
page
```
— 页码，默认1。无密钥BFF回退时，会请求BFF的
```
page
```
并仅对该页面的卡片进行标准化处理。
```
sort
```
— 可选值为
```
rel
```
、
```
date
```
、
```
price_asc
```
、
```
price_dsc
```
、
```
review
```
，未知值将视为
```
rel
```
。
- 官方Search API路径使用Naver API排序规则，但官方API不支持
```
review
```
  排序，因此
```
review
```
  请求将以上游
```
sort=sim
```
  进行查询，并标记
```
meta.sort_applied: "unsupported"
```
  、
```
meta.upstream_sort: "sim"
```
  。
- 无密钥BFF回退时，
```
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 차단/오류가 나면 우회 시도를 반복하지 말고, 검색어를 좁히거나 브라우저 수동 확인을 안내한다.

确认搜索词。
调用
```
GET /v1/naver-shopping/search
```
接口。
若存在
```
items
```
，确认请求排序方式与
```
meta.sort_applied
```
后，以价格从低到高、是否为官方/品牌店、评论数等为基准，简短对比3~5个候选商品。
同时说明
```
meta.extraction
```
及查询时间基准。
若
```
items
```
为空或上游出现拦截/错误，请勿重复尝试绕过，应提示用户缩小搜索词范围或手动通过浏览器确认。

Response style

回复风格

가격은 "조회 시점 네이버 쇼핑 노출가"라고 표현한다.
배송비, 쿠폰, 옵션 추가금, 회원 혜택은 비로그인 공개 검색만으로 확정하지 않는다.
판매처 신뢰도는 노출된 판매처명/리뷰 수만 근거로 보수적으로 말한다.
최저가만 단정하지 말고 동률/옵션 차이를 조심한다.

价格需表述为“查询时点Naver购物显示价”。
运费、优惠券、选项加价、会员优惠等信息，仅通过未登录公开搜索无法确定，请勿断言。
销售商可信度仅以显示的销售商名称/评论数为依据，保守表述。
请勿仅断言最低价，需注意同价/选项差异。

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만 사용한다.

当无官方Search API密钥而使用BFF回退时，Naver可能对特定IP/环境返回418/403等机器人拦截响应。

无密钥回退使用

ns-portal.shopping.naver.com/api/v2/shopping-paged-slot?query=<검색어>&source=shp_gui

公开JSON路径。

搜索结果BFF JSON Schema属于非官方前端接口，可能发生变化。
价格/缺货/配送信息会实时变化。
代理不会绕过访问控制，仅使用官方Search API或单次公开搜索请求+缓存+速率限制。

Done when

完成条件

검색어를 확인했다.
네이버 쇼핑 후보를 최소 1개 이상 반환하거나, 왜 반환하지 못했는지 설명했다.
가격/판매처/링크를 조회 시점 기준으로 보수적으로 정리했다.
로그인/주문/차단 우회 범위를 벗어나지 않았다.

已确认搜索词。
已返回至少1个Naver购物候选商品，或已说明无法返回的原因。
已依据查询时点保守整理价格/销售商/链接信息。
未超出登录/下单/绕过拦截的范围。