六个 1688 操作的参考说明

端点与请求格式

每个操作在本站都有自己的端点，以 POST 调用：`post-1688-categories` 为 POST /api/v1/alibaba-1688/post-1688-categories，`post-1688-category-offers` 为 POST /api/v1/alibaba-1688/post-1688-category-offers，`post-1688-product-detail` 为 POST /api/v1/alibaba-1688/post-1688-product-detail，`post-1688-product-reviews` 为 POST /api/v1/alibaba-1688/post-1688-product-reviews，`post-1688-search` 为 POST /api/v1/alibaba-1688/post-1688-search，`post-1688-supplier-search` 为 POST /api/v1/alibaba-1688/post-1688-supplier-search。输入都放在 `body` 中。只接受契约中的字段名：`q`、`offerId`、`categoryId`、`pageNo`、`lang` 等替代键名会作为未声明的请求体字段被拒绝。

post-1688-categoriespost-1688-category-offerspost-1688-product-detailpost-1688-product-reviewspost-1688-searchpost-1688-supplier-searchbody

类目树

`post-1688-categories` 没有必填输入。`body.language` 取 9 个值之一：`zh`、`en`、`ru`、`es`、`pt`、`fr`、`de`、`ja` 或 `ko`，默认 `en`。`body.depth` 为 1 到 3 的整数，默认 2；深度 1 返回 54 个一级类目，完整 3 层约 2.4 MB。返回 `items`，含 `id`、`name`、`name_zh`、`level`、`is_leaf` 以及 `children` 或 `child_count`，另有 `count`、`language` 和 `depth`。

post-1688-categoriesbody.languagebody.depth

类目商品

`post-1688-category-offers` 的 `body.category_id` 为必填字符串，例如 `1031910`，可从类目树或搜索结果行中取得。`body.page` 为 1 到 200 的整数，默认 1；各页固定含 30 个商品；与关键词搜索不同，该操作确实会逐页翻过类目中的商品。返回 `items`，含 `id`、`title`、`url`、`image`、`price`、`price_display`、`currency`、`moq`、`listed_on`、`fulfilment`、`certifications` 和 `sales`，另有 `count`、`category_id`、`page` 和 `has_next`。

post-1688-category-offersbody.category_idbody.page

商品详情与评价

`post-1688-product-detail` 和 `post-1688-product-reviews` 的 `body.offer_id` 为必填字符串，可以是商品 id 的数字（如 `864971848115`），也可以是完整的商品链接。详情返回以人民币计的 `price`、`price_type`、`price_tiers`、`moq`、`stock`、`mix`、`sold_count`、`category`、`attributes`、`seller` 和 `variants`，其中 `skus` 带有 `price`、`stock` 和 `weight_kg`；供应商未公布重量时 `weight_kg` 为 null。评价返回一页单条评价：`rating`（满分 5）、`rating_scale`、`good_percent`、`review_count`（1688 显示 100+ 时为下限值）以及 `reviews`，含 `content`、`buyer`、`quantity`、`spec`、`images`、`date` 和 `plus_user`。

post-1688-product-detailpost-1688-product-reviewsbody.offer_id

关键词与工厂搜索

`post-1688-search` 和 `post-1688-supplier-search` 的 `body.query` 为必填的自由文本字符串；中文搜索词结果最丰富，英文或拼音也能匹配。商品搜索返回 `items`，含 `id`、`price`、`seller`、`offer_repurchase_rate`、`shop_repurchase_rate`、`category_ids` 和 `is_ad`，另有 `has_next`，它在该操作中始终为 false：每个关键词只返回约 20 个商品的单一短名单，结果行不含起订量和阶梯价，重复调用会在大约 38 个不同商品之间轮换。工厂搜索返回 `items`，含 `name`、`member_id`、`url`、`location`、`years_on_1688`、`workers`、`floor_area_sqm`（平方米）、`makes`、`medal`、`medal_level`、`repeat_buyer_rate`、`on_time_rate`、`reply_rate_30d`（30 天回复率）、`third_party_audit`、`is_super_factory` 和 `offer_ids`，另有 `count`、`query` 和 `note`。它是每个关键词的精选短名单而不是索引：部分关键词不会返回工厂，空列表是真实答案。`third_party_audit` 表示工厂是否经过 SGS 等机构的第三方验厂。

post-1688-searchpost-1688-supplier-searchbody.query

共用的可选输入

6 个操作都还接受 `body.max_rotations`，为 1 到 8 的整数，默认 4。它设定一次调用在放弃前最多尝试的次数。超出范围的值会被拒绝。

body.max_rotations

类目树

POST /api/v1/alibaba-1688/post-1688-categories

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "depth": 1,
    "language": "ru"
  }
}

null

类目商品

POST /api/v1/alibaba-1688/post-1688-category-offers

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "category_id": "1031910"
  }
}

null

商品详情

POST /api/v1/alibaba-1688/post-1688-product-detail

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "offer_id": "864971848115"
  }
}

null

买家评价

POST /api/v1/alibaba-1688/post-1688-product-reviews

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "offer_id": "864971848115"
  }
}

null

关键词搜索

POST /api/v1/alibaba-1688/post-1688-search

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "query": "蓝牙耳机"
  }
}

null

工厂搜索

POST /api/v1/alibaba-1688/post-1688-supplier-search

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "query": "蓝牙耳机"
  }
}

null