京东搜索这个接口，我踩过最蠢的坑，是拿它当详情接口用。第一次对接完，搜出来一批商品，每条记录里 price、sales、shop_name 都有，我心想这数据挺全，直接把结果存进数据库当商品档案用了。过了两周对数据，发现同一个 SKU 在两次采集里的价格差了快两百块，我以为是接口不稳定，重试了好几遍，最后才被人点醒——搜索接口返回的是“商品摘要”，不是你库存管理需要的那份“商品档案”。价格可能是促销价也可能是划线价，库存压根不在里面，SKU 规格、详情图、完整参数，全得拿着 num_iid 再调详情接口去补。拿搜索当详情用，数据看着能用，实际上到处是缺口。
分页：total 和 page_count，俩都不能信
这是京东搜索接口最统一的坑，几乎所有踩过的人都会提一遍。total 字段写着“共 8600 件商品”，page_count 写着“共 172 页”，你照着这个数去写循环，翻到三四十页的时候 item_list 就开始返回空数组了。京东的搜索接口存在深层分页限制，你能翻到的深度是有限的，total 和 page_count 只是预估值，官方文档和你用的封装接口都会明确告诉你“不能作为分页循环依据”。
翻页的正确写法，不是算页数，是把 item_list 为空当作终止信号。再稳一点，加个“连续两页空就 break”的保险，别跟 total 较劲。pageSize 也不是随便填的，不同权限等级上限不一样，有写 50 的，有写 100 的，你填 500 上去大概率被截断或者直接报错。
参数不多，但每一个都有它的脾气
核心参数就五六个：keyword 关键词、pageIndex 页码、pageSize 每页条数、sortType 排序、价格区间，再加上类目 ID。
中文关键词必须 URL 编码。 这一点吃过亏的人不少，不编码直接传中文，接口不报错，给你返回一个空列表，你以为是关键词没商品，其实是编码没做。
时间戳的精度因封装而异。 有的封装要秒级，有的要毫秒级 13 位，还有的封装对时区敏感，本地时间和服务器时间差超过几分钟直接拒签。签名报错的时候，先查时间戳格式，再查排序，十有八九是这两件事。
排序参数的名字各封装不一样。 有的叫 sort，有的叫 sortType，值也不是传字段名，是传排序方式的代码。这点得按你实际用的那个接口的文档来，别照搬别人的示例。
字段口径：三个地方不看清楚，分析全白做
搜索接口返回的字段，做选品和比价其实够用——num_iid（SKU ID）、标题、价格、销量、主图、店铺名、是否自营、评价数，这些都在。但有三个地方不处理，数据“看起来正常，实际上掺了沙子”。
is_ad 要先过滤掉。 搜索结果里混着京东的付费推广商品，这个字段为 true 的时候，那条记录不是自然搜索结果。你在算品类均价或者做价格分布统计，广告商品会把数拉偏，分析之前先按 is_ad 筛一遍。
price 是展示口径，不是结算口径。 搜索接口给的价格可能是促销价、可能是划线价，券后到手价和原价之间的关系，得看具体字段怎么定义。拿来做初筛排序没问题，当成财务级的准确数字去用，容易翻车。
sales 是近 30 天销量，不是实时成交。 平台展示口径和后台结算口径之间有延迟，拿来做相对比较和初筛可以，追实时成交得回商家后台。
资质和限流，比签名更劝退个人开发者
签名本身不难，参数 ASCII 排序、拼接、HMAC-SHA256 加密转大写，一个下午能摸清楚。真正卡住人的是你有没有资格调、能调多快。
京东搜索相关的接口分两套体系。联盟 API（jd.union.open.goods.query） 个人实名认证就能用，基础 QPS 大概 5，适合比价和导购。宙斯 JOS 的商家接口（jingdong.ware.search 这类） 能拿到的数据更全，但需要企业认证加店铺授权，而且只能查自己店铺的商品，想做竞品扫描走不通。
限流这块，联盟基础权限 QPS 在 3 到 5 左右，企业服务商可以申请到更高，但个人账号的天花板就摆在那里。批量采集的时候，并发数要按 QPS 倒推，别上来就开一堆线程。失败重试也要有节制，连续 4xx 错误会被降权，重试三次还不成功，休眠几秒再继续，比一直硬刚要稳。
接口真正省掉的，是把“搜到的商品”变成“能并排比的表”
手动在京东搜一个关键词，一页几十条，你能看到标题、价格、店铺，但想按“价格低于 200、销量过千、非自营、非广告”筛一遍，眼睛看不过来。接口拉回来的是结构化数据，is_ad、is_self、sales、price 各占一列，往表里一放，筛选和排序才有意义。
极致了数据在京东这块覆盖了商品搜索和商品详情两个方向，搜索接口按关键词返回商品列表，num_iid、标题、价格、销量、店铺信息、是否自营这些核心字段都有，拿回来直接能进表格排序和筛选；详情接口传 SKU ID 补全 SKU 规格、库存和图文，搜索拿到的摘要和详情拿到的档案能对上。接入方式按手里的牌选：有技术团队直接对接 API，传关键词和分页参数，返回结构化 JSON；不想写代码的用飞书「多平台数据采集助手」插件，配置关键词和采集频率，数据自动写进多维表格，定时更新；完全不想碰技术的，联系客服定制，告诉对方搜什么词、要哪些字段、什么频率交付，直接给数据表。
合规这条线还是老规矩。搜索结果和商品公开信息，采集来做选品分析和比价没问题；商品详情图文和用户评价涉及平台和用户的内容权益，批量下载和二次分发是另一回事。走官方接口或者合规的第三方封装接口，比用爬虫硬刚反爬要稳得多，京东对同一IP的高频请求封得很快，拿账号和IP去赌稳定性，不划算。
总结
京东搜索 API 这件事，第一课不是“怎么调通”，是“搜索不是详情”。total 和 page_count 是参考值不是循环依据，翻页以 item_list 为空为终止；pageSize 有上限，中文关键词要 URL 编码，时间戳格式按封装来。字段层面，is_ad 过滤广告，price 和 sales 搞清楚口径再用。资质上，联盟 API 个人能碰但 QPS 有限，JOS 数据全但需要企业认证和店铺授权，批量场景自己硬刚限流成本很高，用封装好的接口把分页和签名接过去更现实。极致了数据这边京东搜索和详情都有覆盖，API、飞书插件、客服定制三条路按团队情况挑。先把“搜索拿摘要、详情补档案”这个分工搞清楚，再谈数据怎么用。
