1688商品搜索接口，我第一个项目就栽在一个特别朴素的认知上：我以为它跟淘宝京东的搜索接口是一回事，拿到返回就能直接当货源档案用。结果第一次拉回来一批数据，我看着 price 字段里那串数字，以为是批发价，拿去做成本测算，后来跟供应商一聊才发现，那个价是第一档阶梯价，量小的时候能拿到，你要的量大反而可能不是这个数。更别说 min_order 起订量、混批规则、诚信通资质这些东西，搜索接口给的全是摘要，真正的批发档案得拿着 num_iid 去详情接口补。搜索负责“找到”，详情负责“看清”，这两件事从头到尾就是分开的。
翻页这事，total 和 page_count 一个字都别信
这几乎是1688搜索接口最统一的坑，所有踩过的人都会提一遍。返回里 total 写着“共 8600 件商品”，page_count 写着“共 172 页”，你照着这个数写循环，翻到三四十页 item_list 就开始返回空数组了。1688的搜索接口存在深层分页上限，有文档写 page 最大支持100页，但这100页不等于 page_count 那个数，total 和 page_count 只是预估值，官方文档和你用的封装接口都会明确告诉你不能作为分页循环依据。
翻页的正确写法，是把 item_list 为空当作终止信号。再稳一点，加个“连续两页空就 break”的保险，别跟 page_count 较劲。page_size 也有上限，不同封装有的写50有的写100，你填500上去大概率被截断或者直接报错。
还有一个容易忽略的细节：翻页过程中商品是实时变动的，同一个商品可能在两页里都出现，也可能翻着翻着就下架消失了。拿到数据之后先按 num_iid 去重，别等入库了才发现一列重复的货源。
B2B的字段口径，跟零售平台完全不是一套逻辑
1688搜索接口返回的核心字段包括 num_iid、标题、展示批发价、划线价、近30天销量、最小起订量、主图、店铺信息、发货省市，还有 is_ad 广告标记。做货源初筛和比价够用，但有几个地方得提前把口径搞清楚。
price 是展示价，不是成交价。 它通常只展示第一档阶梯价，你采购量到了更高档位，单价跟这个数不是一回事。拿来做粗略排序可以，做成本测算得靠详情接口的 step_price 数组。
min_order 是B2B独有的门槛字段。 零售平台看的是单件价格，1688看的是“多少件起批”。同样一个批发价，MOQ 5件和MOQ 500件是完全不同的生意，筛选的时候这个字段要单独拎出来。
is_ad 先过滤掉。 搜索结果里混着付费推广商品，这个字段为 true 的时候不是自然搜索结果。做品类均价统计或者价格分布分析之前，先按 is_ad 筛一遍，不然数会被拉偏。
sales 是近30天成交，不是实时库存。 拿来做热度参考没问题，但库存和真实可售量得走详情接口。1688基础接口里的 stock_num 还带着缓存，不含占用和锁定，真要防超卖得用高级实时库存接口。
签名和时间戳，劝退点不在“会不会”，在“细不细”
1688的签名机制跟淘宝的MD5不是一回事，标准是HMAC-SHA1加Base64编码，参数按ASCII升序拼接，时间戳必须是13位毫秒级。有人卡了一天半，最后发现是时间戳用了10位秒级，鉴权直接失败。签名本身不难，难的是这些细节一个都不能错：排序、编码、时间戳精度、时区偏差，错一个就是 Invalid signature 或者 error_code: 40，报错信息还不告诉你错在哪个参数。
QPS才是批量采集真正的天花板
接口调通之后，真正的约束是频率。1688基础API（商品搜索、详情这些）确实免费，但免费不等于无限——搜索类默认QPS大约在10次/秒，超了返回 ISP_FLOW_CONTROL_LIMIT 或 HTTP 429，不扣钱但直接失败。也有文档写官方 alibaba.uniform.search.goods.query 的QPS限制是≤5，不同接口版本和封装之间有差异，接之前先看你自己用的那个接口的文档。
10 QPS听起来不算低，但你要批量拉几十个关键词、每个词翻十几页，算一下就知道排队要排多久。客户端做个令牌桶把单Key压到8到9 QPS留点余量，是基本操作；同企业多AppKey轮询、买资源包提频，都是正规的解法，但个人开发者账号的天花板就摆在那里，日调用量也有限制。自己从零搭一条稳定的批量采集链路，花在限流和重试上的时间，可能比写业务逻辑还多。
接口真正省掉的，是把“翻货源”变成“筛货源”
手动在1688搜一个词，翻几页，看到价格合适的点进去，再翻详情，抄阶梯价和起批量，一家一家比。三十家供应商比下来，前面看的数早就模糊了，最后靠的是印象。
接口拉回来的是结构化数据，num_iid、批发价、MOQ、销量、发货地、是否实力商家各占一列，几十上百条结果往表里一放，筛选才有意义。按MOQ过滤掉起订量太高的，按发货地筛掉物流不划算的，按 is_ad 剔掉广告位，剩下的候选池再拿着 num_iid 去详情接口批量补阶梯价和供应商资质。搜索负责把候选池建起来，详情负责把决策数据填进去，这个分工理顺了，货源比价才做得下去。
极致了数据在1688这块覆盖了商品搜索和商品详情两个方向。搜索接口按关键词返回商品列表，num_iid、标题、批发价、销量、MOQ、店铺信息、发货地这些核心字段都有，拿回来直接能进表格排序和筛选；详情接口传 num_iid 补全阶梯价、SKU库存、供应商资质、代发规则这些批发档案，搜索拿到的摘要和详情拿到的完整数据能对上。接入方式按手里的牌选：有技术团队直接对接API，传关键词和分页参数，返回结构化JSON；不想写代码的用飞书「多平台数据采集助手」插件，配置关键词和采集频率，数据自动写进多维表格，定时更新也能设；完全不想碰技术的，联系客服定制，告诉对方搜什么词、要哪些字段、什么频率交付，直接给数据表。
合规这条线还是老规矩。商品公开信息和批发价采集来做选品分析没问题，商品详情图文和供应商数据批量下载二次分发是另一回事。走官方接口或者合规的第三方封装接口，比用爬虫硬刚1688的风控要稳，账号和IP拿去赌稳定性，不划算。
总结
1688商品搜索API这件事，第一课不是“怎么调通”，是“搜索给的是摘要，详情才是档案”。total 和 page_count 是预估值，翻页以 item_list 为空为终止，page_size 有上限，拿到数据先按 num_iid 去重。B2B字段里，price 是第一档展示价，min_order 是起批门槛，is_ad 要过滤，sales 是近30天参考不是实时库存。签名用HMAC-SHA1加13位毫秒时间戳，QPS在5到10之间，批量采集先把配额算清楚再写循环。自己维护限流和重试的成本不低，极致了数据这边1688搜索和详情都有覆盖，API、飞书插件、客服定制三条路按团队情况挑。先把“搜索建池、详情补档”这个分工搞清楚，再谈数据怎么用。
