naver-shopping-search

Naver Shopping Search

本技能的功能

k-skill-proxy 优先使用 Naver 搜索开放 API 购物搜索（shop.json），仅在无密钥时，通过单次搜索请求获取 Naver Shopping/搜索的无需登录的公开 BFF JSON 端点，并对商品候选进行标准化。

• 根据商品名称/搜索词查找 Naver Shopping 候选。
• 整理当前显示价格、销售商、链接、图片、评论/购买数量（仅当显示时）。
• 可分别比较低价候选和官方商城/品牌商城候选。
• 不涉及下单、购物车、收藏、登录会话访问。

使用时机

• “在 Naver Shopping 上比较 AirPods 的价格”
• “在 Naver 上找最低价的咖啡机”
• “比较 Naver Shopping 链接和按销售商的价格”
• “这个商品在 Naver Shopping 上大概多少钱？”

不使用时机

• 需要确定会员专享价、优惠券价、Naver Pay 个性化优惠时
• 需要下单/购物车/收藏/登录的操作
• 需要绕过访问控制（如屏蔽绕过、CAPTCHA 绕过、指纹欺骗等）时

必需输入

如果没有商品名称或搜索词，先询问用户。

推荐提问：

请告诉我您要查找的 Naver Shopping 商品名称或搜索词。例如：AirPods Pro 2代、iPhone 15 手机壳

如果搜索词过于宽泛，进一步询问品牌/容量/型号。

代理端点

默认使用公共/只读/无认证代理。如果代理服务器配置了 NAVER_SEARCH_CLIENT_ID 和 NAVER_SEARCH_CLIENT_SECRET，则优先使用官方 Search API。

curl -fsS --get "${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}/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

工作流程

1. 确认搜索词。
2. 调用 GET /v1/naver-shopping/search。
3. 如果 items 存在，检查请求的排序方式和 meta.sort_applied，然后根据价格从低到高、是否为官方/品牌商城、评论数量等标准，简要比较3~5个候选。
4. 同时说明 meta.extraction 和查询时间。
5. 如果 items 为空或上游屏蔽/出错，不要重复尝试绕过，而是建议缩小搜索词或手动通过浏览器确认。

回复风格

• 价格表述为“查询时 Naver Shopping 显示价格”。
• 不确认运费、优惠券、附加选项费用、会员优惠（仅基于非登录公开搜索）。
• 销售商可信度仅基于显示的销售商名称/评论数量，保守表述。
• 不要断言最低价，注意同价/选项差异。

失败模式

• 当没有官方 Search API 密钥而使用 BFF 回退时，Naver 可能对特定 IP/环境返回 418/403 等机器人拦截响应。
• 无密钥回退使用 ns-portal.shopping.naver.com/api/v2/shopping-paged-slot?query=<검색어>&source=shp_gui 公开 JSON 路径。
• 搜索结果 BFF JSON 模式是非官方前端表面，可能发生变化。
• 价格/缺货/配送信息实时变化。
• 代理不绕过访问控制。仅使用官方 Search API 或单次公开搜索请求 + 缓存 + 速率限制。

完成条件

• 已确认搜索词。
• 至少返回1个 Naver Shopping 候选，或解释为何无法返回。
• 基于查询时间保守整理价格/销售商/链接。
• 不超出登录/下单/绕过访问控制的范围。