hongben-server/docs/api/sorftime/frontend_guide.md

Sorftime API 前端调用指南

概述

Sorftime 模块通过统一的 转发代理 模式工作。前端所有请求都发送到同一个端点 /api/sorftime/forward，由服务端代理转发到 Sorftime 官方 API。

基础信息

• 请求地址: https://partyvoc.com/api/sorftime/forward
• 请求方法: POST
• Content-Type: application/json
• 认证: 服务端已内置 Token，前端无需传递

请求格式

{
  "path": "/api/接口名称",
  "method": "POST",
  "query": { "domain": 1 },
  "body": { /* Sorftime 官方 API 的请求参数 */ },
  "function": "清洗函数名（可选）"
}

字段	类型	必填	说明
path	string	✅	Sorftime 官方 API 路径，如 /api/ProductQuery
method	string	否	HTTP 方法，默认 POST
query	object	否	URL 查询参数，domain 放这里
body	object	否	请求体参数，透传给 Sorftime 官方 API
function	string	否	服务端数据清洗函数名

domain 参数说明

domain 放在 query 中，表示亚马逊站点：

domain	站点
1	美国 (amazon.com)
2	英国 (amazon.co.uk)
3	德国 (amazon.de)
4	法国 (amazon.fr)
5	日本 (amazon.co.jp)
6	加拿大 (amazon.ca)

---

前端调用示例

1. 商品评论采集（ProductReviewsCollection）

fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/ProductReviewsCollection",
    method: "POST",
    query: { domain: 1 },
    body: {
      ASIN: "B0GMQCC7PF",
      Mode: 1,
      Star: "1,2,3,4,5",
      OnlyPurchase: 1,
      Page: 10
    },
    function: "collectProductReviews"
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

2. 商品搜索（ProductQuery）

fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/ProductQuery",
    method: "POST",
    query: { domain: 1 },
    body: {
      Page: 1,
      Query: "1",
      QueryType: "3",
      pattern: "anker"
    }
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

3. 获取分类树（CategoryTree）

fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/CategoryTree",
    method: "POST",
    query: { domain: 1 },
    body: {},
    function: "cleanCategoryTree"  // 触发服务端清洗，存入 AmazonCategory 表
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

4. ASIN 销量查询（AsinSalesVolume）

fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/AsinSalesVolume",
    method: "POST",
    query: { domain: 1 },
    body: {
      ASIN: "B0GMQCC7PF"
    }
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

5. 关键词查询（KeywordQuery）

消耗 Request: 5

参数说明：

• Pattern: String - 查询模式，支持数据筛选，KeywordQueryPatternObject
• RankCondition: Array - ABA排名范围，如 [1, 1000]
• PageIndex: Integer - 页码索引，默认第1页

• PageSize: Integer - 每页条数，最小20，默认20，最大200

  fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
  path: "/api/KeywordQuery",
  method: "POST",
  query: { domain: 1 },
  body: {
    Pattern: "phone case",
    RankCondition: [1, 1000],
    PageIndex: 1,
    PageSize: 20
  }
  })
  })
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));
  

6. 图搜相似商品（SimilarProductRealtimeRequest）

消耗 Request: 0（异步三步流程）

通过产品图片搜索相似商品，异步流程：请求 → 查状态 → 获取结果

步骤1：发起请求

参数说明：

• Image: String - 产品图片的 Base64 编码，图片大小不超过 1MB

  // 步骤1: 发起相似商品搜索请求（需要产品图片 Base64）
  const imageBase64 = '...'; // 产品图片 Base64 编码
  fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
  path: "/api/SimilarProductRealtimeRequest",
  method: "POST",
  query: { domain: 1 },
  body: {
    Image: imageBase64
  }
  })
  })
  .then(res => res.json())
  .then(data => {
  // data.Data 中包含 TaskId，用于后续查询
  console.log('TaskId:', data);
  })
  .catch(err => console.error(err));
  

步骤2：查询任务状态

// 步骤2: 查询任务状态
fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/SimilarProductRealtimeRequestStatusQuery",
    method: "POST",
    query: { domain: 1 },
    body: {
      TaskId: 12345  // 从步骤1返回的 TaskId
    }
  })
})
.then(res => res.json())
.then(data => console.log('Status:', data))
.catch(err => console.error(err));

步骤3：获取结果

参数说明：

• TaskId: Integer - 从步骤1返回的任务ID

  // 步骤3: 获取相似商品结果
  fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
  path: "/api/SimilarProductRealtimeRequestCollection",
  method: "POST",
  query: { domain: 1 },
  body: {
    TaskId: 12345  // 从步骤1返回的 TaskId
  }
  })
  })
  .then(res => res.json())
  .then(data => {
  // data.Data 为相似商品数组，每项包含：
  // asin, brand, title, category, price, listPrice 等
  console.log('Similar Products:', data);
  })
  .catch(err => console.error(err));
  

7. ASIN 关键词排名（ASINKeywordRanking）

fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/ASINKeywordRanking",
    method: "POST",
    query: { domain: 1 },
    body: {
      ASIN: "B0GMQCC7PF"
    }
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

---

可用接口完整列表

分类相关

path	说明	数据清洗函数
/api/CategoryTree	获取分类树	cleanCategoryTree
/api/CategoryRequest	分类请求	-
/api/CategoryProducts	分类下的商品	-

商品相关

path	说明	数据清洗函数
/api/ProductRequest	商品数据请求（含产品趋势）	-
/api/ProductQuery	商品搜索	-
/api/AsinSalesVolume	ASIN 销量数据	-
/api/ProductVariationHistory	商品变体历史	-
/api/ProductReviewsCollection	商品评论采集	collectProductReviews
/api/ProductReviewsCollectionStatusQuery	评论采集状态查询	-
/api/ProductReviewsQuery	商品评论查询	-
/api/SimilarProductRealtimeRequest	相似商品实时请求（需 Image Base64）	-
/api/SimilarProductRealtimeRequestStatusQuery	相似商品请求状态（需 TaskId）	-
/api/SimilarProductRealtimeRequestCollection	相似商品结果采集（需 TaskId）	-

关键词相关

path	说明
/api/KeywordQuery	关键词查询（需 Pattern/RankCondition/PageIndex/PageSize）
/api/KeywordSearchResults	关键词搜索结果
/api/KeywordRequest	关键词请求
/api/KeywordSearchResultTrend	关键词搜索趋势
/api/CategoryRequestKeyword	分类关键词请求
/api/ASINRequestKeyword	ASIN 关键词请求
/api/KeywordProductRanking	关键词商品排名
/api/ASINKeywordRanking	ASIN 关键词排名
/api/KeywordBatchSubscription	关键词批量订阅
/api/KeywordTasks	关键词任务列表
/api/KeywordBatchTaskUpdate	关键词批量任务更新
/api/KeywordBatchScheduleList	关键词批量计划列表
/api/KeywordBatchScheduleDetail	关键词批量计划详情

榜单与卖家相关

path	说明
/api/BestSellerListSubscription	畅销榜订阅
/api/BestSellerListTask	畅销榜任务
/api/BestSellerListDelete	畅销榜删除
/api/BestSellerListDataCollect	畅销榜数据采集
/api/ProductSellerTasks	商品卖家任务
/api/ProductSellerTaskUpdate	卖家任务更新
/api/ProductSellerTaskScheduleList	卖家任务计划列表
/api/ProductSellerTaskScheduleDetail	卖家任务计划详情
/api/ASINSubscription	ASIN 订阅
/api/ASINSubscriptionQuery	ASIN 订阅查询
/api/ASINSubscriptionCollection	ASIN 订阅采集

---

ProductQuery 的 QueryType 说明

QueryType	说明
1	基于 ASIN 查询同类产品（需先调 ProductRequest）
2	基于类目（nodeId）查询
3	查询品牌旗下热销产品（如 AnkerDirect）
4	查看亚马逊各榜单热销产品
5	查看卖家 Collection 旗下热销产品
6	基于 ABA 关键词查热销产品（仅支持 ABA 关键词）
7	基于产品标题或属性包含词查产品
8	限定售价范围查产品（单位为最小单位，如美国站为分）
10	限定查询季节性产品
11	限定上架时间范围查产品（日期格式 yyyy-MM-dd）
12	限定星级范围查产品
13	限定评论数范围查产品
14	限定发货方式查产品

---

数据清洗函数

cleanCategoryTree

用于 /api/CategoryTree，自动将分类数据清洗后存入 Parse Server 的 AmazonCategory 表。

存储字段映射：

AmazonCategory 字段	来源	说明
categoryId	Id	分类 ID
domain	query.domain	站点
parentId	ParentId	父分类 ID
nodeId	NodeId	节点 ID
name	Name	英文名称
cnName	CNName	中文名称
url	URL	分类链接
dataUpdatedAt	自动	更新时间

collectProductReviews

用于 /api/ProductReviewsCollection，采集商品评论数据。

---

响应格式

Sorftime 官方 API 返回数据直接透传，常见响应结构：

// 成功
{
  "Code": 200,
  "Message": "success",
  "Data": { /* 具体数据 */ }
}

// 积分不足
{
  "Code": 4,
  "Message": "积分余额不足"
}

注意事项

1. 所有接口统一通过 POST /api/sorftime/forward 转发
2. domain 参数放在 query 中，不是 body 中
3. function 字段用于触发服务端数据清洗（注意不是 functionName）
4. 服务端内置重试机制（3 次，间隔 1 秒），5xx 错误自动重试
5. 请求超时 30 秒
6. 当前账户积分余额不足时会返回 {Code: 4, Message: "积分余额不足"}