从关键词到逐页浏览类目
关键词搜索能快速给出样本，但没有第二页。先用中文词作为 `body.query` 调用 `post-1688-search`，挑一条相关结果并读取其 `category_ids`，这些 id 按从宽到细的顺序排列。把其中一个 id 作为 `body.category_id` 传给 `post-1688-category-offers`，在 `has_next` 为 true 时逐步增加 `body.page`，最多到第 200 页；各页固定含 30 个商品。
联系前先评估工厂
用产品关键词调用 `post-1688-supplier-search`。根据返回的数据比较各行，例如 `workers`、`floor_area_sqm`、`repeat_buyer_rate` 和 `third_party_audit`，然后从 `offer_ids` 中取 id，逐个作为 `body.offer_id` 传给 `post-1688-product-detail` 查看价格与规格，再传给 `post-1688-product-reviews` 查看买家反馈。
用其他语言浏览
面向不懂中文的读者，可以调用 `post-1688-categories`，把 `body.language` 设为例如 `ru`，并把 `body.depth` 设为 1 以获得精简的一级类目，需要时再获取更深层级；完整类目树约 2.4 MB。每个节点在 `name_zh` 中保留中文名称，便于把类目与中文搜索词对应起来。
这些数据特有的陷阱
用同一关键词再次调用 `post-1688-search` 不会翻页：结果只在大约 38 个不同商品之间轮换，因此不要把重复调用当作新的覆盖范围。商品搜索结果行也不含起订量和阶梯价，且关键词结果主要是推广商品。`post-1688-supplier-search` 返回空的工厂列表是真实答案，重复调用也不会改变。1688 显示 100+ 时 `review_count` 为下限值；没有评价的商品在 `post-1688-product-reviews` 中返回空列表和零计数。只接受契约字段名，因此请发送 `body.query`，而不是 `q` 或 `keyword`。
[
{
"body": {
"query": "蓝牙耳机"
}
},
{
"body": {
"category_id": "1031910",
"page": 2
}
},
{
"body": {
"offer_id": "864971848115",
"max_rotations": 4
}
}
]服务端请求模板
以下服务端模板以此 API 的第一个操作为例，演示认证与请求标识。请根据场景选择操作，并在 API 页面查看其当前可用状态与价格。超时后，使用同一个 Idempotency-Key 重发未改变的请求。
网关请求始终使用 POST。
使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。
# Server-side only. Set ATLAS_API_KEY in your secret manager.
# Set ATLAS_API_ORIGIN to your configured deployment origin.
# Every gateway operation is called with POST.
# Only operations shown as enabled on the API page can be called.
# Generate once per intent; retain the same value on status checks.
REQUEST_ID="$(uuidgen)"
curl --request POST 'https://apigate.vercel.app/api/v1/alibaba-1688/post-1688-categories' \
--header "Content-Type: application/json" \
--header "x-api-key: $ATLAS_API_KEY" \
--header "Idempotency-Key: $REQUEST_ID" \
--data '{"body":{"depth":1,"language":"ru"}}'接入检查清单
- API 密钥保存在服务端密钥管理器中，从不发送到浏览器。
- 每个请求携带自己的 Idempotency-Key，并保留到请求得到最终结果为止。
- 集成读取 ok 与 error.code，并按错误码表处理每个错误码。
- 使用原标识检查结果不确定的 POST，绝不盲目更换标识重试。
- 已在 API 页面查看该操作的当前可用状态与价格。