商品 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}
商品页与结账用的完整商品快照。映射到订单：source_product_id → offer_id，variants[].sku_id → spec_id（采购订单）。
标识与渠道
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | HIOBuy 复合键：{channel}_{source_product_id} |
channel | string | 1688、taobao 或 weidian |
source_product_id | string | 1688 = offerId；淘宝 = mi_id（订单 API 必填） |
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 | 促销前标价 |
price.display_amount | number | 买家可见价格（CNY） |
price.promotion_amount | number | null | 适用时的促销单价 |
price.original_currency / display_currency | string | 恒为 CNY |
price_tiers[] | array | 1688 批发阶梯价；淘宝为空 |
min_order_quantity | number | null | 1688 起订量（MOQ） |
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 | 规格维度（颜色、尺码等） |
price | object | SKU 级价格（元） |
stock | number | 可用数量；0 = 缺货 |
image | string | null | SKU 主图 |
shipping | object | null | 1688 包裹尺寸（用于运费） |
distribution | object | null | 1688 代发定价 |
卖家、运费与元数据
| 字段 | 类型 | 说明 |
|---|---|---|
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": "1688_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...",
"stock": 100
}
]
},
"request_id": "req_..."
}各渠道字段可用性
| 字段 | 1688 | Taobao | Weidian |
|---|---|---|---|
videos, price_tiers, trade_score | ✓ | — | 视情况 |
variants[].shipping, distribution | ✓ | — | — |
订单用 source_product_id | offerId | 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 | 用 source_product_id 拉取详情 |
title | LocalizedTitle | 列表标题 |
price | ProductPrice | 摘要价格（CNY 元） |
image | string | 缩略图 URL |
seller.name | string | 店铺名称 |
上传图片响应 {#upload-image-response}
| 字段 | 类型 | 说明 |
|---|---|---|
channel | string | 存储图片的卖场 |
image_id | string | 在以图搜索中复用 |