商品 API 响应模型

使用 response_format: "standard"（默认）时，商品端点返回下列类型。权威 TypeScript 定义：packages/shared/src/products.ts。

响应信封 {#envelope}

Endpoint	结构
`detail`, `parse`	`{ product: StandardProductDetail, request_id }`
`search`, `search-by-image`	`StandardProductList & { request_id }`
`upload-image`	`{ channel, image_id, request_id }`

StandardProductDetail {#standard-product-detail}

商品页与结账用的完整商品快照。映射到订单：搜索/详情 id → lines[].id（兼容 offer_id、淘宝 mi_id）；variants[].sku_id → spec_id（采购订单）。

标识与渠道

字段	类型	说明
`id`	string	淘宝 = `mi_id`（下单传 `lines[].id`；会周期性变化，勿长期缓存）。1688 = `offerId`。微店目前为 `prod_weidian_{source_product_id}`
`channel`	string	`1688`、`taobao` 或 `weidian`
`source_product_id`	string	1688 = `offerId`（与 `id` 相同）；淘宝 = 原 `item_id`
`source_url`	string	规范商品页 URL

本地化文本（`title`、`description`）

字段	类型	说明
`original`	string	卖场原文（通常为中文）
`translated`	string \| null	按请求 `language` 翻译的文本
`language`	string	`translated` 的语言区域
`description`	object \| null	长描述（常为 HTML）

定价（`price`、`price_tiers[]`）

所有金额为 CNY 元（非分）。优先使用 promotion_amount，否则用 display_amount。

字段	类型	说明
`price.original_amount`	number	1 件标价（1688 有 `retailPrice` 时用零售价）
`price.display_amount`	number	买家可见 1 件价（CNY）
`price.promotion_amount`	number \| null	适用时的促销单价
`price.original_currency` / `display_currency`	string	恒为 `CNY`
`variants[].price.wholesale_amount`	number \| null	1688 SKU 批发价（≥2 件；仅新零售价货盘）
`price_tiers[]`	array	1688 批发阶梯（新货盘首档 ≥2）；淘宝为空
`min_order_quantity`	number \| null	1688 用上游起订量；淘宝零售默认 `1`
`distribution_min_quantity`	number \| null	1688 代发最低量

媒体（`images[]`、`videos`）

字段	类型	说明
`images[].url`	string	图片 CDN URL
`images[].type`	enum	`main`、`gallery` 或 `variant`
`videos.main` / `videos.detail`	string \| null	1688 视频；淘宝为 `null`

属性 vs 规格变体

仅 variants[] 驱动 SKU 选择与订单行。

字段	作用
`attributes[]`	CPV 规格——仅展示，不用于 SKU 解析
`variants[]`	可购 SKU 矩阵，含价格、库存、规格

变体对象（`variants[]`）

字段	类型	说明
`sku_id`	string	创建订单时作为 `spec_id` 传入
`upstream_sku_id`	string \| null	1688 数字 `skuId`
`attributes[]`	array	规格维度（颜色、尺码等）
`attributes[].name` / `value`	string	展示文案（按请求 `language` 翻译）
`attributes[].original_name` / `original_value`	string	稳定中文键，用于分组 / 匹配
`attributes[].prop_id`	string \| null	上游属性 ID（字符串；淘宝 `prop_id`；1688 `attributeId`）。有值时优先于名称文本
`attributes[].value_id`	string \| null	上游属性值 ID（字符串；淘宝 `value_id`）。1688 无 valueId → `null`
`attributes[].image`	string \| null	规格配图 / 色块图
`price`	object	SKU 级价格（元）
`stock`	number	可用数量；`0` = 缺货
`image`	string \| null	SKU 主图
`shipping`	object \| null	1688 SKU 件重尺（见下表）；淘宝为 `null`
`min_order_quantity`	number \| null	1688 商品级下发到各 SKU；淘宝默认 `1`
`distribution`	object \| null	1688 代发定价

SKU 件重尺（`variants[].shipping`）

映射自 1688 上游 productShippingInfo.skuShippingDetails（SkuShippingDetail）。淘宝无此数据，恒为 null。空值或 0 的尺寸/重量会规范为 null；若该 SKU 完全无件重尺数据，整个 shipping 为 null。

字段	类型	说明
`width_cm`	number \| null	宽，cm（商家自填）
`length_cm`	number \| null	长，cm
`height_cm`	number \| null	高，cm
`weight_kg`	number \| null	重，kg
`official_width_cm`	number \| null	官方测量宽度，cm
`official_length_cm`	number \| null	官方测量长度，cm
`official_height_cm`	number \| null	官方测量高度，cm
`official_weight_kg`	number \| null	官方测量重量，kg
`ai_weight_kg`	number \| null	AI 预测重量，kg
`ai_weight_accuracy`	string \| null	AI 预测重量在该商品叶子类目的准确率（如 `80%`）
`source`	string \| null	件重尺来源（如 `商家自填`）

运费估算可优先使用 official_*，其次商家自填尺寸/重量，再用 ai_weight_kg（并参考 ai_weight_accuracy）。

卖家、运费与元数据

字段	类型	说明
`seller.id` / `seller.name`	string	店铺 ID 与展示名
`seller.shop_url`	string \| null	店铺链接
`shipping.shipping_from`	string \| null	国内发货地区
`shipping.domestic_shipping_fee`	object \| null	预估国内运费（元）
`metadata.raw_category`	string \| null	上游类目
`metadata.brand`	string \| null	申报品牌
`metadata.updated_at`	string	ISO 8601 最后同步时间
`trade_score`	string \| null	1688 质量分

示例（截断）

{
  "product": {
    "id": "554456348334",
    "channel": "1688",
    "source_product_id": "554456348334",
    "title": {
      "original": "...",
      "translated": "...",
      "language": "en"
    },
    "price": {
      "display_amount": 29.9,
      "promotion_amount": 24.9
    },
    "variants": [
      {
        "sku_id": "b266e0...",
        "upstream_sku_id": "12123313",
        "stock": 100,
        "shipping": {
          "width_cm": 10,
          "length_cm": 10,
          "height_cm": 10,
          "weight_kg": 1.2,
          "official_width_cm": 5,
          "official_length_cm": 12,
          "official_height_cm": 14,
          "official_weight_kg": 0.001,
          "ai_weight_kg": 0.001,
          "ai_weight_accuracy": "80%",
          "source": "商家自填"
        }
      }
    ]
  },
  "request_id": "req_..."
}

各渠道字段可用性

字段	1688	Taobao	Weidian
`videos`, `price_tiers`, `trade_score`	✓	—	视情况
`variants[].shipping`, `distribution`	✓	—	—
`variants[].attributes[].prop_id`	✓（`attributeId`）	✓（`prop_id`）	—
`variants[].attributes[].value_id`	—（`null`）	✓（`value_id`）	—
下单 `lines[].id`	`id` / `offerId`	`id`（`mi_id`）	平台 ID

StandardProductList {#standard-product-list}

来自搜索与以图搜索。items[] 每项为摘要——需调用详情获取 SKU 矩阵。

字段	类型	说明
`channel`	string	查询的卖场
`keyword`	string	关键词回显（纯以图搜索时为空）
`page` / `page_size`	number	已应用的分页
`total`	number	上游总数（可能为近似值）
`items[]`	array	`StandardProductListItem` 对象
`pic_region_info`	object	以图搜索：检测到的裁剪区域

StandardProductListItem

字段	类型	说明
`id`, `channel`, `source_product_id`, `source_url`	string	把 `id` 传给商品详情
`title`	LocalizedTitle	列表标题
`price`	ProductPrice	摘要价格（CNY 元）
`image`	string	缩略图 URL
`seller.name`	string	店铺名称

上传图片响应 {#upload-image-response}

字段	类型	说明
`channel`	string	存储图片的卖场
`image_id`	string	在以图搜索中复用

规格选择 {#variant-selection}

加载详情 → 读取 product.variants。
按 attributes[].original_name 分组做维度选择器（有 prop_id 时也可按 ID 分组）。
随用户每次选择过滤变体；禁用缺货选项。
将匹配的 sku_id 与 source_product_id 传入订单预览。

匹配键： 淘宝在同时有 prop_id + value_id 时优先用 ID——这是稳定的 CPV 身份，可避免多 SKU 共用同一属性名（如大量选项都叫 Color Classification）导致的串配。UI 分组可回退到 original_name + original_value。name / value 仅用于展示。不要根据文案推断语义类型。

{
  "prop_id": "1627207",
  "value_id": "43553464153",
  "name": "Color Classification",
  "value": "[Special for Bicycle Maintenance] Professional 46-Piece Set",
  "original_name": "颜色分类",
  "original_value": "【自行车维修专用】专业46件套",
  "image": "https://img.alicdn.com/..."
}

1688 使用同一结构：prop_id 来自 attributeId，value_id 为 null（上游 SkuAttribute 无 valueId）。

获取支持

需要集成帮助？请联系开发者支持 support@hiobuy.com · 预计 1–2 个工作日内回复

发送邮件