商品关键词搜索 API

POST /v1/products/search — 关键词搜索，返回分页商品列表。

淘宝 → 上游 /traffic/item/search
1688 → 上游 product.search.keywordQuery

某渠道不支持的字段会静默忽略（无额外响应头）。

公共请求字段

字段	必填	说明
`channel`	是	`1688` \| `taobao`
`keyword`	是	搜索词
`language`	否	默认 `en`
`page` / `page_size`	否	分页（淘宝每页最多 20）
`response_format`	否	`standard`（默认）或 `upstream`
`sort_field`	否	`price` \| `sales` \| `credit`（`credit` 仅 1688；淘宝忽略）
`sort_order`	否	`asc` \| `desc`（默认 `asc`；需配合 `sort_field`）
`price_start` / `price_end`	否	价格区间，单位元（支持小数，如 `19.9`）
`ship_within_hours`	否	`0`（当日）\| `24` \| `48`
`category_ids`	否	类目 ID，逗号分隔。仅 1688；淘宝忽略
`product_collection_id`	否	商机货盘 ID。仅 1688；淘宝忽略

排序 `sort_field` + `sort_order`

`sort_field`	`sort_order`	→ 1688	→ 淘宝
`price`	`asc` / `desc`	`{"bid":"asc\|desc"}`	`PRICE_ASC` / `PRICE_DESC`
`sales`	`asc` / `desc`	`{"sale":"asc\|desc"}`	`SALE_QTY_ASC` / `SALE_QTY_DESC`
`credit`	`asc` / `desc`	`{"credit":"asc\|desc"}`	忽略

兼容别名：bid→price，sale→sales。

价格

对外一律元（可小数）。
1688 → priceStart / priceEnd。
淘宝 → filters 的 min_price / max_price（分，Math.round(元 * 100)）。

发货时效 `ship_within_hours`

值	→ 1688 `filter`	→ 淘宝 `filters`
`0`	`shipInToday`	忽略
`24`	`shipIn24Hours`	`24shipping`
`48`	`shipIn48Hours`	`48shipping`

1688 语义筛选（淘宝忽略）

字段	类型	说明
`experience_score_level`	integer	`1`…`4` → `totalEpScoreLv1`…`Lv4`
`product_attrs`	string	逗号分隔：`isOnePsale`、`isOnePsaleFreePost`、`new7`、`new30`、`1688Selection`、`isQqyx`
`filter`	string	高级逗号分隔标签，与上表语义字段合并去重
`sale_filters`	object[]	映射 `saleFilterList`（`sale_type`：`sales7` \| `sales14` \| `sales30` \| `totalSales`，可选 `sale_start` / `sale_end`）
`keyword_translate`	boolean	关键词是否已翻译

兼容（deprecated）：category_id、category_id_list（请用 category_ids）。

请求示例

1688

POST /v1/products/search
{
  "channel": "1688",
  "keyword": "phone case",
  "language": "en",
  "page": 1,
  "page_size": 20,
  "sort_field": "sales",
  "sort_order": "desc",
  "price_start": 10.5,
  "price_end": 99.9,
  "ship_within_hours": 24,
  "experience_score_level": 2,
  "product_attrs": "isOnePsale,1688Selection",
  "filter": "noReason7DReturn",
  "category_ids": "123,456",
  "product_collection_id": "262105288"
}

淘宝

POST /v1/products/search
{
  "channel": "taobao",
  "keyword": "帽子",
  "language": "en",
  "page": 1,
  "page_size": 20,
  "sort_field": "price",
  "sort_order": "asc",
  "price_start": 20,
  "price_end": 100,
  "ship_within_hours": 24
}

响应

StandardProductList — items[] 中为摘要卡片。完整 SKU 矩阵与库存请调用商品详情。

response_format: "upstream" 时返回渠道原厂载荷（见响应格式）。