商品 API 参考 (v2)

概述

本页完整列出商品 API v2（当前版本，建议新集成使用）的端点、参数和 response 结构：按关键词搜索、以图搜款、获取商品详情、上传图片以及计算淘宝和 1688 上的运费。

如果您正在使用 v1 版本，参见 商品 API v1 (Legacy)。如需分步操作，参见 商品搜索指南。

所有端点均为 POST，要求身份验证请求头（JWT 或 API 密钥），并要求 platform 参数取值为 taobao 或 alibaba。

按关键词搜索商品

POST /v2/products/search

请求示例：

{
  "platform": "taobao",
  "q": "áo thun cotton",
  "lang": "vi",
  "sort": "SALE_QTY_DESC",
  "page": 1,
  "size": 20,
  "filter": {
    "priceRange": { "min": 0, "max": 100 }
  }
}

参数

结果排序（sort）

结果过滤（filter）

ffmOutbound 值

ffmDelivery 值

newArrival 值

sellerLevel 值

以图搜款

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

POST /v2/products/search-by-image

有 2 种以图搜索方式，必须传递以下 2 个参数之一：

1. 通过图片 URL 搜索 — 使用 imgUrl 参数

只能使用来自 Alibaba 的图片链接：*.alicdn.com。

{
  "platform": "taobao",
  "imgUrl": "https://img.alicdn.com/bao/uploaded/i3/694223667/O1CN01zSjKgp1cxXRQZsDLA_!!694223667.jpg",
  "lang": "vi",
  "page": 1,
  "size": 20
}

2. 通过上传的图片搜索 — 使用 imgId 参数

先通过 POST /v2/products/upload-image API 上传图片以获得 imageId，然后将其作为 imgId 传入：

{
  "platform": "alibaba",
  "imgId": "image-123",
  "lang": "vi",
  "page": 1,
  "size": 20
}

参数

* 必须传递 imgUrl 或 imgId 两个参数中的至少一个。

获取商品详情

POST /v2/products/find
POST /v2/products/detail

两个端点使用相同的请求结构并返回商品详情信息。detail 返回更完整的详情，适合需要 1688 数据时使用。

{
  "platform": "taobao",
  "id": "734467086498",
  "lang": "vi"
}

参数

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

商品价格类型

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

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

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

1688 上的卖家等级

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

extra_info 中的字段说明

计算运费

仅适用于淘宝。

POST /v2/products/shipping-fee

{
  "platform": "taobao",
  "id": "734467086498",
  "addressInfo": {
    "country": "VN",
    "state": "Hà Nội",
    "city": "Hà Nội",
    "district": "Hoàn Kiếm"
  }
}

参数

Response 包含 post_fee（运费费用，单位 CNY）、currency、item_id、mi_id、item_resource。

上传图片

用于获取 imageId，以供以图搜索使用（imgId 参数）。

POST /v2/products/upload-image

请求为 multipart/form-data 格式：

Response：{ "imageId": "image-123" }。

Response 结构

response 中的字段名使用 snake_case 形式。每个平台返回各自的商品结构：

• find / detail → 一个商品对象（Product）
• search / search-by-image → { "paginate": { "total", "current", "size" }, "items": [...] }（paginate 项在没有分页信息时可能缺失）

通用字段（两个平台都有）

1688 独有字段

除通用字段外，1688 response 还补充以下字段（按主题分组）：

• 价格： price_range、channel_price、promotion_model、fenxiao_sale_info、is_jxhy
• 媒体： video_urls、white_image、translated_img_urls、translated_white_image
• 语言翻译： description_en、unit_en
• 销量 / 评价： sold、review、level
• 物流： shipping_info
• 分类： top_category_id、second_category_id、third_category_id
• 标识与链接： mp_id、item_type、batch_number、product_cargo_number、original_product_url、seller_shop_url、promotion_url
• 元数据： selling_point、offer_identities、create_date、is_select、certificate_list、seller_mix_setting
• 其他： extra_info、sku_price_ranges

注意： response 中完全缺失的字段意味着该字段不属于您正在调用的平台。值为 null 的字段意味着该请求中没有该字段的数据。

完整的字段列表和详细描述：Swagger API。

常见问题 (FAQ)

为什么通过 API 获取的商品价格与在淘宝/1688 网站上看到的价格不同？

1. 我们使用的 API 属于 Alibaba 的跨境物流系统，价格独立确定 — 与网站上显示的价格相互分离。
2. 与 API 不同，网站能够区分新老客户，因此可以按用户群体应用促销或优惠券 — 这是 API 不支持的能力。

有测试环境吗？

没有。默认账户已获赠 200 次免费请求 用于测试集成。

数据是实时的吗？

是的，数据直接从淘宝和 1688 获取。

支持以图搜款吗？

是的，支持通过图片链接和上传图片搜索。

相关链接

• 操作指南： 商品搜索指南
• Legacy： 商品 API v1 (Legacy)
• 工具： Elim CLI — 从终端搜索商品
• 完整 API 参考： openapi.elim.asia/api