商品 API v1 (Legacy) 参考

⚠️ Legacy： v1 API 仅会在短期内并行运行。新的集成应使用商品 API v2。

概述

本页完整列出 v1 商品 API 的参数和取值：在淘宝和 1688 上按关键词搜索、以图搜款以及获取商品详情。如需分步操作，参见商品搜索指南。

按关键词搜索商品

详见：搜索商品

POST /v1/products/search

语言翻译（`lang`）

值	描述	平台
vi	越南语	✅ Taobao ✅ 1688
en	英语	✅ Taobao ✅ 1688

翻译数据位于 titleEn 键中。title 键仍为中文数据。

结果排序（`sort`）

值	描述	平台
PRICE_ASC	价格升序	✅ Taobao ✅ 1688
PRICE_DESC	价格降序	✅ Taobao ✅ 1688
SALE_QTY_ASC	销量升序	✅ Taobao ✅ 1688
SALE_QTY_DESC	销量降序	✅ Taobao ✅ 1688
RETENTION_ASC	复购率升序	❌ Taobao ✅ 1688
RETENTION_DESC	复购率降序	❌ Taobao ✅ 1688

结果过滤（`filter`）

过滤条件	描述	平台
price_range	价格区间（单位：CNY）	✅ Taobao ✅ 1688
shop_id	同一卖家的商品	✅ Taobao ✅ 1688
seller_level	卖家等级	❌ Taobao ✅ 1688
is_factory	仅获取超级工厂货源	❌ Taobao ✅ 1688
ffm_outbound	快速发货标准	❌ Taobao ✅ 1688
ffm_delivery	快速配送标准	❌ Taobao ✅ 1688
allow_return	7 天无理由退货	❌ Taobao ✅ 1688
allow_dropship	允许代发货	❌ Taobao ✅ 1688
freeship_for_dropship	允许代发货 + 免邮	❌ Taobao ✅ 1688
new_arrival	新上架商品	❌ Taobao ✅ 1688
platform_pick	平台精选的国内货源	❌ Taobao ✅ 1688
global_pick	平台精选的国际市场货源	❌ Taobao ✅ 1688
dropship_pick	平台精选的代发货货源	❌ Taobao ✅ 1688

`ffm_outbound` 值

值	描述
FFMO1	24 小时内发货率 < 95%
FFMO2	24 小时内发货率 >= 95%
FFMO3	24 小时内发货率 > 99%
FFMO4	48 小时内发货率 < 95%
FFMO5	48 小时内发货率 >= 95%
FFMO6	48 小时内发货率 > 99%

`ffm_delivery` 值

值	描述
FFMD0	当天送达
FFMD1	24 小时内送达
FFMD2	48 小时内送达

`new_arrival` 值

值	描述
7DAY	最近 7 天新上架的商品
30DAY	最近 30 天新上架的商品

`seller_level` 值

值	描述
L1	综合评分 5 星
L2	综合评分 4.5 - 5 星
L3	综合评分 4 - 4.5 星
L4	综合评分低于 4 星

以图搜款

注意： 此功能不适用于免费套餐。

详见：搜索商品

POST /v1/products/search-img

有 2 种以图搜索方式：

1. 通过图片 URL 搜索 — 适用范围：✅ Taobao ✅ 1688

使用 query 参数中的 img_url 键。只能使用来自 Alibaba 的图片链接：*.alicdn.com

2. 通过上传的图片搜索 — 适用范围：✅ Taobao ✅ 1688

要使用此功能，请先通过 Upload image API 将图片上传到 Alibaba 服务器。然后在 query 参数中使用 img_id 键代替 img_url。

获取商品详情

详见：商品详情

POST /v1/products/find

如果遇到 https://e.tb.cn/h.hPY04k4RPfAco8F?tk=0CCI430IUqd 形式的短链接，必须先处理链接以获取原始链接 — 使用 Unshorten link API 获取原始链接和商品 ID。

商品价格类型

价格属性	描述	平台
price	普通价格。对于 1688 是不含免邮的批发价，数量取决于卖家设置。	✅ Taobao ✅ 1688
promotion_price	促销价，低于或等于普通价格。	✅ Taobao ✅ 1688
retail_price	零售价 + 单件起免邮，适用于代发货。通常出现在 1688 精选商品中。	❌ Taobao ✅ 1688
dropship_price	单件零售价，通常等于普通价格。区别在于取决于卖家是否开启代发货。	❌ Taobao ✅ 1688

价格的显示与应用逻辑

一些商品有多类价格，显示与应用逻辑取决于平台。通过 API 获取的价格可能高于在淘宝/1688 网站上直接看到的价格，因为网站的定价机制可能已应用了 API 无法应用的促销和折扣。

警告： 如果您在扩展/网站/应用上向客户展示价格，请附加警告，说明价格可能高于在淘宝/1688 上直接看到的价格。如果发现 API 上的价格更高，请联系客服，以便在下单购买时协助调整价格。

淘宝： 优先显示和应用促销价；如果没有，则使用普通价格。

1688： 价格应用逻辑取决于 quote_type 字段：

值	描述
direct	按 `price` 和 `promotion_price` 获取批发价。
by_sku	按每个 SKU 获取价格。
by_volume	按 `price_range` 获取价格，并取决于最低起购量 `moq`。

1688 上的卖家等级

等级用于确定 1688 上卖家的信誉，通过 seller_type 字段确定。共有 3 个等级：

值	描述
seller	普通卖家。
merchant	专业卖家，已通过 1688 认证。
factory	生产工厂，已通过 1688 认证并满足 1688 直接评估的标准。

`extra_info` 中的字段说明

值	描述
isOnePsale	是否支持代发货？
isSupportMix	是否支持一个订单购买多个商品？
isOnePsaleFreePostage	是否支持代发货 + 免邮？
noReason7DReturn	是否允许 7 天无理由退货？
1688_yx	是否为精选货源？

商品 API v1 (Legacy) 参考

概述

按关键词搜索商品

语言翻译（lang）

结果排序（sort）

结果过滤（filter）

ffm_outbound 值

ffm_delivery 值

new_arrival 值

seller_level 值