hongben-server/docs/api/front/data-api.md

数据清洗统一接口文档

版本：v2.0.0 更新日期：2025-01-01 基础URL：https://server-msq.fmode.cn 接口前缀：/api/v2/

本文档定义了一套统一的、经过数据清洗后的前端友好接口，将三个平台（Amazon SP-API、Sorftime、TikHub）的原始数据转换为统一格式，便于前端对接。

---

目录

• 1. 设计原则
• 2. 通用类型定义
• 3. 统一响应格式
• 4. 错误码表
• 5. 接口定义
  • 5.1 商品管理 (Products)
  • 5.2 关键词分析 (Keywords)
  • 5.3 类目分析 (Categories)
  • 5.4 订单管理 (Orders)
  • 5.5 Listing 管理 (Listings)
  • 5.6 TikTok 数据 (TikTok)
  • 5.7 监控与订阅 (Monitoring)
  • 5.8 卖家信息 (Sellers)
• 附录：数据来源映射总表

---

1. 设计原则

#	原则	说明
1	统一响应格式	所有接口返回 { code: number, message: string, data: T }
2	字段命名统一	全部使用 camelCase
3	时间格式统一	ISO 8601 格式，如 2025-01-01T12:00:00.000Z
4	金额格式统一	{ amount: number, currency: string }
5	分页格式统一	{ items: T[], total: number, page: number, pageSize: number, hasMore: boolean }
6	精简字段	去除平台特有的冗余字段，只保留前端需要的核心字段

---

2. 通用类型定义

/** 统一响应包装 */
interface ApiResponse<T> {
  /** 业务状态码，0 表示成功 */
  code: number;
  /** 状态描述 */
  message: string;
  /** 响应数据 */
  data: T;
}

/** 统一分页响应 */
interface PaginatedResponse<T> {
  /** 数据列表 */
  items: T[];
  /** 总记录数 */
  total: number;
  /** 当前页码（从 1 开始） */
  page: number;
  /** 每页条数 */
  pageSize: number;
  /** 是否有更多数据 */
  hasMore: boolean;
}

/** 统一金额 */
interface Money {
  /** 金额数值 */
  amount: number;
  /** 货币代码，如 USD、CNY */
  currency: string;
}

/** 统一分页请求参数 */
interface PaginationParams {
  /** 页码，默认 1 */
  page?: number;
  /** 每页条数，默认 20 */
  pageSize?: number;
}

/** 统一时间范围请求参数 */
interface DateRangeParams {
  /** 开始日期 ISO 8601 */
  startDate: string;
  /** 结束日期 ISO 8601 */
  endDate: string;
}

/** 统一商品摘要（多处复用） */
interface ProductSummary {
  /** 统一商品 ID */
  id: string;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 主图 URL */
  imageUrl: string;
  /** 价格 */
  price: Money | null;
  /** 评分（1-5） */
  rating: number | null;
  /** 评论数 */
  reviewCount: number | null;
  /** 类目名称 */
  category: string;
  /** 数据来源平台 */
  platform: 'amazon' | 'sorftime';
}

---

3. 统一响应格式

成功响应

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

错误响应

{
  "code": 40001,
  "message": "缺少必填参数: keyword",
  "data": null
}

分页响应

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [ ... ],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

4. 错误码表

错误码	说明	HTTP 状态码
0	成功	200
40001	缺少必填参数	400
40002	参数格式错误	400
40003	参数值超出范围	400
40101	未授权（缺少认证信息）	401
40102	认证过期	401
40301	无权访问该资源	403
40401	资源不存在	404
40901	请求冲突（重复操作）	409
42901	请求频率超限	429
50001	服务器内部错误	500
50002	Amazon SP-API 调用失败	502
50003	Sorftime API 调用失败	502
50004	TikHub API 调用失败	502
50005	数据清洗转换异常	500
50301	上游服务不可用	503
50401	上游服务响应超时	504

---

5. 接口定义

5.1 商品管理 (Products)

---

GET /api/v2/products/search — 统一搜索商品

聚合 Amazon Catalog Items 搜索 + Sorftime ProductQuery，返回统一格式的商品列表。

数据来源：

平台	原始接口
Amazon	CatalogItemsApi.searchCatalogItems → GET /api/amazon/catalog/items
Sorftime	ProductApi.getProductQuery → POST /api/sorftime/forward → /api/ProductQuery

请求参数：

参数	类型	必填	说明
keyword	string	是	搜索关键词
platform	string	否	数据来源：amazon | sorftime，默认全部
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

// ApiResponse<PaginatedResponse<ProductSummary>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "B0EXAMPLE1",
        "asin": "B0EXAMPLE1",
        "title": "Wireless Bluetooth Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg",
        "price": { "amount": 29.99, "currency": "USD" },
        "rating": 4.5,
        "reviewCount": 1280,
        "category": "Electronics",
        "platform": "amazon"
      }
    ],
    "total": 156,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

GET /api/v2/products/:id — 商品详情

聚合 Amazon CatalogItem 详情 + Sorftime ProductRequest，返回完整商品信息。

数据来源：

平台	原始接口
Amazon	CatalogItemsApi.getCatalogItem → GET /api/amazon/catalog/items/:asin
Sorftime	ProductApi.getProductRequest → POST /api/sorftime/forward → /api/ProductRequest

请求参数：

参数	类型	必填	说明
id (路径)	string	是	商品 ID（ASIN）

响应类型：

interface ProductDetail {
  /** 商品 ID */
  id: string;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 商品描述 */
  description: string;
  /** 图片列表 */
  images: string[];
  /** 价格 */
  price: Money | null;
  /** 评分（1-5） */
  rating: number | null;
  /** 评论数 */
  reviewCount: number | null;
  /** 类目名称 */
  category: string;
  /** 品牌 */
  brand: string;
  /** BSR 销售排名 */
  salesRank: number | null;
  /** 变体列表 */
  variations: {
    asin: string;
    title: string;
    price: Money | null;
    imageUrl: string;
    attributes: Record<string, string>;
  }[];
}

// ApiResponse<ProductDetail>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "B0EXAMPLE1",
    "asin": "B0EXAMPLE1",
    "title": "Wireless Bluetooth Earbuds",
    "description": "High quality wireless earbuds with noise cancellation...",
    "images": [
      "https://images-na.ssl-images-amazon.com/images/I/img1.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/img2.jpg"
    ],
    "price": { "amount": 29.99, "currency": "USD" },
    "rating": 4.5,
    "reviewCount": 1280,
    "category": "Electronics > Headphones",
    "brand": "ExampleBrand",
    "salesRank": 156,
    "variations": [
      {
        "asin": "B0EXAMPLE2",
        "title": "Wireless Bluetooth Earbuds - Black",
        "price": { "amount": 29.99, "currency": "USD" },
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/black.jpg",
        "attributes": { "color": "Black" }
      }
    ]
  }
}

---

GET /api/v2/products/:id/sales — 商品销量数据

聚合 Amazon Sales OrderMetrics + Sorftime AsinSalesVolume，返回统一的销量趋势数据。

数据来源：

平台	原始接口
Amazon	SalesApi.getOrderMetrics → GET /api/amazon/sales/orderMetrics
Sorftime	ProductApi.getAsinSalesVolume → POST /api/sorftime/forward → /api/AsinSalesVolume

请求参数：

参数	类型	必填	说明
id (路径)	string	是	商品 ID（ASIN）
startDate	string	是	开始日期 ISO 8601
endDate	string	是	结束日期 ISO 8601
granularity	string	否	粒度：day | week | month，默认 day

响应类型：

interface ProductSalesData {
  periods: {
    /** 日期 ISO 8601 */
    date: string;
    /** 销售件数 */
    unitCount: number;
    /** 订单数 */
    orderCount: number;
    /** 销售额 */
    revenue: Money;
  }[];
}

// ApiResponse<ProductSalesData>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "periods": [
      {
        "date": "2025-01-01T00:00:00.000Z",
        "unitCount": 15,
        "orderCount": 10,
        "revenue": { "amount": 449.85, "currency": "USD" }
      },
      {
        "date": "2025-01-02T00:00:00.000Z",
        "unitCount": 22,
        "orderCount": 18,
        "revenue": { "amount": 659.78, "currency": "USD" }
      }
    ]
  }
}

---

GET /api/v2/products/:id/reviews — 商品评论分析

聚合 Amazon CustomerFeedback + Sorftime ProductReviewsQuery，返回评论汇总与主题分析。

数据来源：

平台	原始接口
Amazon	CustomerFeedbackApi → GET /api/amazon/customerFeedback/items/:asin/reviews/topics
Sorftime	ProductApi.getProductReviewsQuery → POST /api/sorftime/forward → /api/ProductReviewsQuery

请求参数：

参数	类型	必填	说明
id (路径)	string	是	商品 ID（ASIN）

响应类型：

interface ProductReviewsData {
  /** 评论汇总 */
  summary: {
    /** 总评论数 */
    total: number;
    /** 平均评分 */
    avgRating: number;
    /** 评分分布（1-5 星各多少） */
    distribution: {
      1: number;
      2: number;
      3: number;
      4: number;
      5: number;
    };
  };
  /** 评论主题分析 */
  topics: {
    /** 主题名称 */
    name: string;
    /** 情感倾向：positive | negative | neutral */
    sentiment: string;
    /** 提及次数 */
    count: number;
  }[];
  /** 评论列表 */
  reviews: {
    /** 评论 ID */
    id: string;
    /** 评分 */
    rating: number;
    /** 评论标题 */
    title: string;
    /** 评论内容 */
    content: string;
    /** 评论时间 ISO 8601 */
    createTime: string;
    /** 评论者名称 */
    author: string;
    /** 是否已验证购买 */
    verified: boolean;
  }[];
}

// ApiResponse<ProductReviewsData>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "summary": {
      "total": 1280,
      "avgRating": 4.5,
      "distribution": { "1": 32, "2": 48, "3": 96, "4": 320, "5": 784 }
    },
    "topics": [
      { "name": "音质", "sentiment": "positive", "count": 456 },
      { "name": "电池续航", "sentiment": "positive", "count": 312 },
      { "name": "连接稳定性", "sentiment": "negative", "count": 89 }
    ],
    "reviews": [
      {
        "id": "R1EXAMPLE",
        "rating": 5,
        "title": "Great sound quality",
        "content": "These earbuds have amazing sound...",
        "createTime": "2025-01-10T08:30:00.000Z",
        "author": "John D.",
        "verified": true
      }
    ]
  }
}

---

GET /api/v2/products/:id/similar — 同类产品

基于 Sorftime SimilarProductRealtimeRequest 获取同类产品列表。

数据来源：

平台	原始接口
Sorftime	ProductApi.getSimilarProductRealtimeRequest → POST /api/sorftime/forward → /api/SimilarProductRealtimeRequest

请求参数：

参数	类型	必填	说明
id (路径)	string	是	商品 ID（ASIN）
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

// ApiResponse<PaginatedResponse<ProductSummary>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "B0SIMILAR1",
        "asin": "B0SIMILAR1",
        "title": "Noise Cancelling Wireless Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/similar1.jpg",
        "price": { "amount": 34.99, "currency": "USD" },
        "rating": 4.3,
        "reviewCount": 890,
        "category": "Electronics",
        "platform": "sorftime"
      }
    ],
    "total": 45,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

5.2 关键词分析 (Keywords)

---

GET /api/v2/keywords/search — 关键词查询

基于 Sorftime KeywordQuery 查询关键词数据。

数据来源：

平台	原始接口
Sorftime	KeywordApi.getKeywordQuery → POST /api/sorftime/forward → /api/KeywordQuery

请求参数：

参数	类型	必填	说明
keyword	string	是	搜索关键词
matchMode	string	否	匹配模式：broad | exact | phrase，默认 broad
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

interface KeywordItem {
  /** 关键词 */
  keyword: string;
  /** 月搜索量 */
  searchVolume: number;
  /** 搜索趋势：up | down | stable */
  trend: string;
  /** 竞争程度：high | medium | low */
  competition: string;
  /** 每次点击费用 */
  cpc: Money;
}

// ApiResponse<PaginatedResponse<KeywordItem>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "keyword": "wireless earbuds",
        "searchVolume": 450000,
        "trend": "up",
        "competition": "high",
        "cpc": { "amount": 1.25, "currency": "USD" }
      },
      {
        "keyword": "wireless earbuds bluetooth",
        "searchVolume": 120000,
        "trend": "stable",
        "competition": "medium",
        "cpc": { "amount": 0.85, "currency": "USD" }
      }
    ],
    "total": 256,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

GET /api/v2/keywords/:keyword/products — 关键词下的产品排名

基于 Sorftime KeywordProductRanking 获取关键词下的产品排名列表。

数据来源：

平台	原始接口
Sorftime	KeywordApi.getKeywordProductRanking → POST /api/sorftime/forward → /api/KeywordProductRanking

请求参数：

参数	类型	必填	说明
keyword (路径)	string	是	关键词
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

interface RankedProduct extends ProductSummary {
  /** 在该关键词下的排名 */
  rank: number;
}

// ApiResponse<PaginatedResponse<RankedProduct>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "B0EXAMPLE1",
        "asin": "B0EXAMPLE1",
        "title": "Wireless Bluetooth Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg",
        "price": { "amount": 29.99, "currency": "USD" },
        "rating": 4.5,
        "reviewCount": 1280,
        "category": "Electronics",
        "platform": "sorftime",
        "rank": 1
      }
    ],
    "total": 48,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

GET /api/v2/keywords/reverse/:asin — ASIN 反查关键词

聚合 Sorftime ASINRequestKeyword + KeywordRequest，通过 ASIN 反查关联关键词。

数据来源：

平台	原始接口
Sorftime	KeywordApi.getASINRequestKeyword → POST /api/sorftime/forward → /api/ASINRequestKeyword
Sorftime	KeywordApi.getKeywordRequest → POST /api/sorftime/forward → /api/KeywordRequest

请求参数：

参数	类型	必填	说明
asin (路径)	string	是	商品 ASIN
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

interface ReverseKeywordItem {
  /** 关键词 */
  keyword: string;
  /** 该 ASIN 在此关键词下的排名 */
  rank: number;
  /** 月搜索量 */
  searchVolume: number;
  /** 搜索趋势：up | down | stable */
  trend: string;
}

// ApiResponse<PaginatedResponse<ReverseKeywordItem>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "keyword": "wireless earbuds",
        "rank": 3,
        "searchVolume": 450000,
        "trend": "up"
      },
      {
        "keyword": "bluetooth earbuds",
        "rank": 7,
        "searchVolume": 280000,
        "trend": "stable"
      }
    ],
    "total": 89,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

GET /api/v2/keywords/:keyword/trend — 关键词趋势

基于 Sorftime KeywordSearchResultTrend 获取关键词搜索趋势数据。

数据来源：

平台	原始接口
Sorftime	KeywordApi.getKeywordSearchResultTrend → POST /api/sorftime/forward → /api/KeywordSearchResultTrend

请求参数：

参数	类型	必填	说明
keyword (路径)	string	是	关键词

响应类型：

interface KeywordTrendData {
  periods: {
    /** 日期 ISO 8601 */
    date: string;
    /** 搜索量 */
    searchVolume: number;
    /** 搜索结果数 */
    resultCount: number;
  }[];
}

// ApiResponse<KeywordTrendData>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "periods": [
      {
        "date": "2025-01-01T00:00:00.000Z",
        "searchVolume": 450000,
        "resultCount": 3200
      },
      {
        "date": "2025-02-01T00:00:00.000Z",
        "searchVolume": 480000,
        "resultCount": 3350
      }
    ]
  }
}

---

5.3 类目分析 (Categories)

---

GET /api/v2/categories/tree — 类目树

聚合 Amazon Catalog Categories + Sorftime CategoryTree，返回统一的类目树结构。

数据来源：

平台	原始接口
Amazon	CatalogItemsApi.getCatalogCategories → GET /api/amazon/catalog/categories
Sorftime	CategoryApi.getCategoryTree → POST /api/sorftime/forward → /api/CategoryTree

请求参数：

参数	类型	必填	说明
platform	string	否	数据来源：amazon | sorftime，默认全部
domain	string	否	市场域名，如 amazon.com

响应类型：

interface CategoryNode {
  /** 类目 ID */
  id: string;
  /** 类目名称 */
  name: string;
  /** 父类目 ID，顶级为 null */
  parentId: string | null;
  /** 子类目列表 */
  children: CategoryNode[];
  /** 类目下商品数量 */
  productCount: number | null;
}

// ApiResponse<{ items: CategoryNode[] }>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "1234",
        "name": "Electronics",
        "parentId": null,
        "children": [
          {
            "id": "5678",
            "name": "Headphones",
            "parentId": "1234",
            "children": [],
            "productCount": 15600
          }
        ],
        "productCount": 256000
      }
    ]
  }
}

---

GET /api/v2/categories/:id/top-products — 类目热销产品

基于 Sorftime CategoryRequest + CategoryProducts 获取类目下的热销产品。

数据来源：

平台	原始接口
Sorftime	CategoryApi.getCategoryRequest → POST /api/sorftime/forward → /api/CategoryRequest
Sorftime	CategoryApi.getCategoryProducts → POST /api/sorftime/forward → /api/CategoryProducts

请求参数：

参数	类型	必填	说明
id (路径)	string	是	类目 ID
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

interface RankedProduct extends ProductSummary {
  /** 在该类目下的排名 */
  rank: number;
}

// ApiResponse<PaginatedResponse<RankedProduct>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "B0TOP001",
        "asin": "B0TOP001",
        "title": "Best Selling Wireless Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/top1.jpg",
        "price": { "amount": 24.99, "currency": "USD" },
        "rating": 4.7,
        "reviewCount": 5600,
        "category": "Headphones",
        "platform": "sorftime",
        "rank": 1
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

GET /api/v2/categories/:id/keywords — 类目关键词

基于 Sorftime CategoryRequestKeyword 获取类目下的关键词列表。

数据来源：

平台	原始接口
Sorftime	KeywordApi.getCategoryRequestKeyword → POST /api/sorftime/forward → /api/CategoryRequestKeyword

请求参数：

参数	类型	必填	说明
id (路径)	string	是	类目 ID
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

// ApiResponse<PaginatedResponse<KeywordItem>>
// KeywordItem 定义见 5.2 关键词查询

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "keyword": "wireless earbuds",
        "searchVolume": 450000,
        "trend": "up",
        "competition": "high",
        "cpc": { "amount": 1.25, "currency": "USD" }
      }
    ],
    "total": 120,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

5.4 订单管理 (Orders)

仅 Amazon 平台

---

GET /api/v2/orders — 订单列表

基于 Amazon Orders API 获取订单列表。

数据来源：

平台	原始接口
Amazon	OrdersApi.getOrders → GET /api/amazon/orders

请求参数：

参数	类型	必填	说明
startDate	string	是	开始日期 ISO 8601
endDate	string	是	结束日期 ISO 8601
status	string	否	订单状态：pending | shipped | delivered | cancelled
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

interface OrderItem {
  /** 订单 ID */
  orderId: string;
  /** 下单时间 ISO 8601 */
  orderDate: string;
  /** 订单状态 */
  status: string;
  /** 订单总额 */
  total: Money;
  /** 商品件数 */
  itemCount: number;
  /** 买家名称 */
  buyerName: string;
  /** 销售渠道 */
  channel: string;
}

// ApiResponse<PaginatedResponse<OrderItem>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "orderId": "111-1234567-1234567",
        "orderDate": "2025-01-15T10:30:00.000Z",
        "status": "shipped",
        "total": { "amount": 59.98, "currency": "USD" },
        "itemCount": 2,
        "buyerName": "John D.",
        "channel": "Amazon.com"
      }
    ],
    "total": 350,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

GET /api/v2/orders/:id — 订单详情

基于 Amazon Orders API 获取订单详情及商品明细。

数据来源：

平台	原始接口
Amazon	OrdersApi.getOrder → GET /api/amazon/orders/:orderId
Amazon	OrdersApi.getOrderItems → GET /api/amazon/orders/:orderId/items

请求参数：

参数	类型	必填	说明
id (路径)	string	是	订单 ID

响应类型：

interface OrderDetail {
  /** 订单 ID */
  orderId: string;
  /** 下单时间 ISO 8601 */
  orderDate: string;
  /** 订单状态 */
  status: string;
  /** 订单总额 */
  total: Money;
  /** 订单商品列表 */
  items: {
    /** ASIN */
    asin: string;
    /** SKU */
    sku: string;
    /** 商品标题 */
    title: string;
    /** 数量 */
    quantity: number;
    /** 单价 */
    price: Money;
    /** 商品图片 */
    imageUrl: string;
  }[];
  /** 配送信息 */
  shipping: {
    /** 收件人 */
    name: string;
    /** 配送方式 */
    method: string;
    /** 配送状态 */
    status: string;
    /** 预计送达时间 ISO 8601 */
    estimatedDelivery: string | null;
  };
  /** 支付信息 */
  payment: {
    /** 支付方式 */
    method: string;
    /** 支付总额 */
    total: Money;
  };
}

// ApiResponse<OrderDetail>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "orderId": "111-1234567-1234567",
    "orderDate": "2025-01-15T10:30:00.000Z",
    "status": "shipped",
    "total": { "amount": 59.98, "currency": "USD" },
    "items": [
      {
        "asin": "B0EXAMPLE1",
        "sku": "WE-BLK-001",
        "title": "Wireless Bluetooth Earbuds - Black",
        "quantity": 2,
        "price": { "amount": 29.99, "currency": "USD" },
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg"
      }
    ],
    "shipping": {
      "name": "John Doe",
      "method": "Standard Shipping",
      "status": "In Transit",
      "estimatedDelivery": "2025-01-20T00:00:00.000Z"
    },
    "payment": {
      "method": "Credit Card",
      "total": { "amount": 59.98, "currency": "USD" }
    }
  }
}

---

GET /api/v2/orders/metrics — 订单统计指标

基于 Amazon Sales OrderMetrics 获取订单统计数据。

数据来源：

平台	原始接口
Amazon	SalesApi.getOrderMetrics → GET /api/amazon/sales/orderMetrics

请求参数：

参数	类型	必填	说明
startDate	string	是	开始日期 ISO 8601
endDate	string	是	结束日期 ISO 8601
granularity	string	否	粒度：day | week | month，默认 day

响应类型：

interface OrderMetricsData {
  periods: {
    /** 日期 ISO 8601 */
    date: string;
    /** 订单数 */
    orderCount: number;
    /** 销售件数 */
    unitCount: number;
    /** 销售额 */
    revenue: Money;
  }[];
}

// ApiResponse<OrderMetricsData>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "periods": [
      {
        "date": "2025-01-01T00:00:00.000Z",
        "orderCount": 45,
        "unitCount": 68,
        "revenue": { "amount": 2034.55, "currency": "USD" }
      },
      {
        "date": "2025-01-02T00:00:00.000Z",
        "orderCount": 52,
        "unitCount": 79,
        "revenue": { "amount": 2367.21, "currency": "USD" }
      }
    ]
  }
}

---

5.5 Listing 管理 (Listings)

仅 Amazon 平台

---

GET /api/v2/listings — Listing 列表

基于 Amazon Listings Items API 获取卖家的 Listing 列表。

数据来源：

平台	原始接口
Amazon	ListingsItemsApi.searchListingsItems → `GET /api/amazo

5.5 Listing 管理 (Listings)

仅 Amazon 平台

---

GET /api/v2/listings — Listing 列表

基于 Amazon Listings Items API 获取卖家的 Listing 列表。

数据来源：

平台	原始接口
Amazon	ListingsItemsApi.searchListingsItems → GET /api/amazon/listings/items/:sellerId

请求参数：

参数	类型	必填	说明
sellerId	string	是	卖家 ID
keywords	string	否	搜索关键词
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

interface ListingItem {
  /** SKU */
  sku: string;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 状态：active | inactive | incomplete */
  status: string;
  /** 价格 */
  price: Money | null;
  /** 主图 URL */
  imageUrl: string;
  /** 商品状况：new | used | refurbished */
  condition: string;
  /** 创建时间 ISO 8601 */
  createdAt: string;
}

// ApiResponse<PaginatedResponse<ListingItem>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "sku": "WE-BLK-001",
        "asin": "B0EXAMPLE1",
        "title": "Wireless Bluetooth Earbuds - Black",
        "status": "active",
        "price": { "amount": 29.99, "currency": "USD" },
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg",
        "condition": "new",
        "createdAt": "2024-06-15T08:00:00.000Z"
      }
    ],
    "total": 85,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

GET /api/v2/listings/:sku — Listing 详情

基于 Amazon Listings Items API 获取单个 Listing 的详细信息。

数据来源：

平台	原始接口
Amazon	ListingsItemsApi.getListingsItem → GET /api/amazon/listings/items/:sellerId/:sku

请求参数：

参数	类型	必填	说明
sku (路径)	string	是	商品 SKU

响应类型：

interface ListingDetail {
  /** SKU */
  sku: string;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 状态 */
  status: string;
  /** 价格 */
  price: Money | null;
  /** 主图 URL */
  imageUrl: string;
  /** 商品状况 */
  condition: string;
  /** 问题列表 */
  issues: {
    /** 问题代码 */
    code: string;
    /** 问题描述 */
    message: string;
    /** 严重程度：error | warning | info */
    severity: string;
  }[];
  /** 报价列表 */
  offers: {
    /** 报价类型 */
    offerType: string;
    /** 价格 */
    price: Money;
    /** 配送方式 */
    fulfillment: string;
  }[];
  /** 配送方式：FBA | FBM */
  fulfillment: string;
}

// ApiResponse<ListingDetail>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "sku": "WE-BLK-001",
    "asin": "B0EXAMPLE1",
    "title": "Wireless Bluetooth Earbuds - Black",
    "status": "active",
    "price": { "amount": 29.99, "currency": "USD" },
    "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg",
    "condition": "new",
    "issues": [],
    "offers": [
      {
        "offerType": "B2C",
        "price": { "amount": 29.99, "currency": "USD" },
        "fulfillment": "FBA"
      }
    ],
    "fulfillment": "FBA"
  }
}

---

5.6 TikTok 数据 (TikTok)

数据来源：TikHub API

---

GET /api/v2/tiktok/users/:uniqueId — 用户资料

获取 TikTok 用户的基本资料信息。

数据来源：

平台	原始接口
TikHub	TikTokUserApi → GET /api/tikhub/tiktok/user/info

请求参数：

参数	类型	必填	说明
uniqueId (路径)	string	是	TikTok 用户唯一标识

响应类型：

interface TikTokUser {
  /** 用户 ID */
  userId: string;
  /** 用户唯一标识 */
  uniqueId: string;
  /** 昵称 */
  nickname: string;
  /** 头像 URL */
  avatar: string;
  /** 个人简介 */
  bio: string;
  /** 粉丝数 */
  followerCount: number;
  /** 关注数 */
  followingCount: number;
  /** 获赞数 */
  likeCount: number;
  /** 视频数 */
  videoCount: number;
}

// ApiResponse<TikTokUser>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "userId": "6789012345",
    "uniqueId": "example_user",
    "nickname": "Example Creator",
    "avatar": "https://p16-sign.tiktokcdn.com/avatar/example.jpg",
    "bio": "Content creator | Tech reviews",
    "followerCount": 125000,
    "followingCount": 350,
    "likeCount": 2800000,
    "videoCount": 256
  }
}

---

GET /api/v2/tiktok/videos/:id — 视频详情

获取 TikTok 视频的详细信息。

数据来源：

平台	原始接口
TikHub	TikTokVideoApi → GET /api/tikhub/tiktok/video/info

请求参数：

参数	类型	必填	说明
id (路径)	string	是	视频 ID

响应类型：

interface TikTokVideo {
  /** 视频 ID */
  videoId: string;
  /** 视频描述 */
  description: string;
  /** 封面图 URL */
  coverUrl: string;
  /** 视频播放 URL */
  videoUrl: string;
  /** 视频时长（秒） */
  duration: number;
  /** 发布时间 ISO 8601 */
  createTime: string;
  /** 互动数据 */
  stats: {
    /** 播放量 */
    playCount: number;
    /** 点赞数 */
    likeCount: number;
    /** 评论数 */
    commentCount: number;
    /** 分享数 */
    shareCount: number;
  };
}

// ApiResponse<TikTokVideo>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "videoId": "7123456789012345678",
    "description": "Amazing wireless earbuds review! #tech #earbuds",
    "coverUrl": "https://p16-sign.tiktokcdn.com/cover/example.jpg",
    "videoUrl": "https://v16-webapp.tiktok.com/video/example.mp4",
    "duration": 60,
    "createTime": "2025-01-10T15:30:00.000Z",
    "stats": {
      "playCount": 1250000,
      "likeCount": 85000,
      "commentCount": 3200,
      "shareCount": 12000
    }
  }
}

---

GET /api/v2/tiktok/videos/:id/comments — 视频评论

获取 TikTok 视频的评论列表。

数据来源：

平台	原始接口
TikHub	TikTokVideoApi → GET /api/tikhub/tiktok/video/comments

请求参数：

参数	类型	必填	说明
id (路径)	string	是	视频 ID
cursor	string	否	分页游标，首次请求不传
count	number	否	每次获取条数，默认 20

响应类型：

interface TikTokComment {
  /** 评论 ID */
  commentId: string;
  /** 评论内容 */
  text: string;
  /** 评论者信息 */
  author: {
    userId: string;
    uniqueId: string;
    nickname: string;
    avatar: string;
  };
  /** 点赞数 */
  likeCount: number;
  /** 评论时间 ISO 8601 */
  createTime: string;
  /** 回复列表 */
  replies: TikTokComment[];
}

interface TikTokCommentListResponse {
  items: TikTokComment[];
  /** 是否有更多数据 */
  hasMore: boolean;
  /** 下一页游标 */
  cursor: string;
}

// ApiResponse<TikTokCommentListResponse>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "commentId": "7123456789000000001",
        "text": "Great review! Just ordered a pair.",
        "author": {
          "userId": "1234567890",
          "uniqueId": "tech_fan",
          "nickname": "Tech Fan",
          "avatar": "https://p16-sign.tiktokcdn.com/avatar/fan.jpg"
        },
        "likeCount": 256,
        "createTime": "2025-01-10T16:00:00.000Z",
        "replies": []
      }
    ],
    "hasMore": true,
    "cursor": "cursor_token_abc123"
  }
}

---

GET /api/v2/tiktok/users/:id/followers — 用户粉丝

获取 TikTok 用户的粉丝列表。

数据来源：

平台	原始接口
TikHub	TikTokUserApi → GET /api/tikhub/tiktok/user/followers

请求参数：

参数	类型	必填	说明
id (路径)	string	是	用户 ID
offset	number	否	偏移量，默认 0
count	number	否	每次获取条数，默认 20

响应类型：

interface TikTokUserListResponse {
  items: TikTokUser[];
  /** 是否有更多数据 */
  hasMore: boolean;
  /** 下一页偏移量 */
  offset: number;
}

// ApiResponse<TikTokUserListResponse>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "userId": "9876543210",
        "uniqueId": "follower_user",
        "nickname": "Follower",
        "avatar": "https://p16-sign.tiktokcdn.com/avatar/follower.jpg",
        "bio": "Love tech!",
        "followerCount": 500,
        "followingCount": 200,
        "likeCount": 10000,
        "videoCount": 15
      }
    ],
    "hasMore": true,
    "offset": 20
  }
}

---

GET /api/v2/tiktok/users/:id/following — 用户关注列表

获取 TikTok 用户的关注列表。

数据来源：

平台	原始接口
TikHub	TikTokUserApi → GET /api/tikhub/tiktok/app/v3/user-following

请求参数：

参数	类型	必填	说明
id (路径)	string	是	用户 ID
offset	number	否	偏移量，默认 0
count	number	否	每次获取条数，默认 20

响应类型：

// ApiResponse<TikTokUserListResponse>
// TikTokUserListResponse 定义见 users/:id/followers

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "userId": "1122334455",
        "uniqueId": "following_user",
        "nickname": "Following User",
        "avatar": "https://p16-sign.tiktokcdn.com/avatar/following.jpg",
        "bio": "Tech blogger",
        "followerCount": 80000,
        "followingCount": 150,
        "likeCount": 500000,
        "videoCount": 120
      }
    ],
    "hasMore": true,
    "offset": 20
  }
}

---

GET /api/v2/tiktok/shop/products/:id — TikTok 商品详情

获取 TikTok 小店商品的详细信息。

数据来源：

平台	原始接口
TikHub	TikTokShopApi → GET /api/tikhub/tiktok/shop/product-detail

请求参数：

参数	类型	必填	说明
id (路径)	string	是	TikTok 商品 ID

响应类型：

interface TikTokShopProduct {
  /** 商品 ID */
  productId: string;
  /** 商品标题 */
  title: string;
  /** 商品描述 */
  description: string;
  /** 商品图片列表 */
  images: string[];
  /** 价格 */
  price: Money;
  /** 原价 */
  originalPrice: Money | null;
  /** 销量 */
  soldCount: number;
  /** 评分（1-5） */
  rating: number | null;
  /** 评论数 */
  reviewCount: number;
  /** 店铺名称 */
  shopName: string;
  /** 店铺 ID */
  shopId: string;
  /** 商品分类 */
  category: string;
  /** 商品状态：active | inactive */
  status: string;
}

// ApiResponse<TikTokShopProduct>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "productId": "1729384756012345",
    "title": "Wireless Earbuds Pro Max",
    "description": "Premium wireless earbuds with ANC...",
    "images": [
      "https://p16-oec-ttp.tiktokcdn.com/product/img1.jpg",
      "https://p16-oec-ttp.tiktokcdn.com/product/img2.jpg"
    ],
    "price": { "amount": 19.99, "currency": "USD" },
    "originalPrice": { "amount": 39.99, "currency": "USD" },
    "soldCount": 15600,
    "rating": 4.6,
    "reviewCount": 2340,
    "shopName": "TechStore Official",
    "shopId": "7654321098765",
    "category": "Electronics > Audio",
    "status": "active"
  }
}

---

GET /api/v2/tiktok/ads/:id — 广告详情

获取 TikTok 广告的详细信息。

数据来源：

平台	原始接口
TikHub	TikTokAdsApi → GET /api/tikhub/tiktok/ads/ads-detail

请求参数：

参数	类型	必填	说明
id (路径)	string	是	广告 ID

响应类型：

interface TikTokAdDetail {
  /** 广告 ID */
  adId: string;
  /** 广告标题 */
  title: string;
  /** 广告描述 */
  description: string;
  /** 广告素材 URL */
  mediaUrl: string;
  /** 广告封面 URL */
  coverUrl: string;
  /** 落地页 URL */
  landingPageUrl: string;
  /** 广告主名称 */
  advertiserName: string;
  /** 广告主 ID */
  advertiserId: string;
  /** 投放时长（天） */
  durationDays: number;
  /** 首次投放时间 ISO 8601 */
  firstSeenAt: string;
  /** 最近投放时间 ISO 8601 */
  lastSeenAt: string;
  /** 互动数据 */
  stats: {
    /** 点赞数 */
    likeCount: number;
    /** 评论数 */
    commentCount: number;
    /** 分享数 */
    shareCount: number;
  };
}

// ApiResponse<TikTokAdDetail>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "adId": "ad_7890123456",
    "title": "Wireless Earbuds - 50% OFF",
    "description": "Limited time offer on premium earbuds!",
    "mediaUrl": "https://v16-webapp.tiktok.com/ad/example.mp4",
    "coverUrl": "https://p16-sign.tiktokcdn.com/ad/cover.jpg",
    "landingPageUrl": "https://shop.tiktok.com/product/12345",
    "advertiserName": "TechStore Official",
    "advertiserId": "adv_1234567890",
    "durationDays": 14,
    "firstSeenAt": "2025-01-01T00:00:00.000Z",
    "lastSeenAt": "2025-01-14T23:59:59.000Z",
    "stats": {
      "likeCount": 12500,
      "commentCount": 890,
      "shareCount": 3400
    }
  }
}

---

5.7 监控与订阅 (Monitoring)

数据来源：Sorftime API

---

POST /api/v2/monitoring/bestseller/subscribe — BS榜单订阅

创建 Best Seller 榜单监控订阅任务。

数据来源：

平台	原始接口
Sorftime	MonitorApi.subscribeBestseller → POST /api/sorftime/forward → /api/BestsellerSubscribe

请求参数：

参数	类型	必填	说明
categoryId	string	是	类目 ID
domain	string	是	市场域名，如 amazon.com
frequency	string	否	监控频率：daily | weekly，默认 daily

响应类型：

interface SubscribeResult {
  /** 任务 ID */
  taskId: string;
  /** 订阅状态：active | pending */
  status: string;
  /** 创建时间 ISO 8601 */
  createdAt: string;
}

// ApiResponse<SubscribeResult>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "bs_task_20250101_001",
    "status": "active",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

---

GET /api/v2/monitoring/bestseller/tasks — BS榜单任务列表

获取当前所有 Best Seller 榜单监控任务。

数据来源：

平台	原始接口
Sorftime	MonitorApi.getBestsellerTasks → POST /api/sorftime/forward → /api/BestsellerTasks

请求参数：

参数	类型	必填	说明
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

interface BestsellerTask {
  /** 任务 ID */
  taskId: string;
  /** 类目 ID */
  categoryId: string;
  /** 类目名称 */
  categoryName: string;
  /** 市场域名 */
  domain: string;
  /** 监控频率 */
  frequency: string;
  /** 任务状态：active | paused | expired */
  status: string;
  /** 创建时间 ISO 8601 */
  createdAt: string;
  /** 最近更新时间 ISO 8601 */
  lastUpdatedAt: string | null;
}

// ApiResponse<PaginatedResponse<BestsellerTask>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "taskId": "bs_task_20250101_001",
        "categoryId": "1234",
        "categoryName": "Electronics > Headphones",
        "domain": "amazon.com",
        "frequency": "daily",
        "status": "active",
        "createdAt": "2025-01-01T00:00:00.000Z",
        "lastUpdatedAt": "2025-01-15T06:00:00.000Z"
      }
    ],
    "total": 5,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}

---

GET /api/v2/monitoring/bestseller/:taskId/data — BS榜单数据

获取指定 Best Seller 监控任务的榜单数据。

数据来源：

平台	原始接口
Sorftime	MonitorApi.getBestsellerData → POST /api/sorftime/forward → /api/BestsellerData

请求参数：

参数	类型	必填	说明
taskId (路径)	string	是	任务 ID
date	string	否	查询日期 ISO 8601，默认最新
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

interface BestsellerDataItem {
  /** 排名 */
  rank: number;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 主图 URL */
  imageUrl: string;
  /** 价格 */
  price: Money | null;
  /** 评分 */
  rating: number | null;
  /** 评论数 */
  reviewCount: number | null;
  /** 排名变化：正数上升，负数下降，0 不变 */
  rankChange: number;
  /** 是否新上榜 */
  isNew: boolean;
}

// ApiResponse<PaginatedResponse<BestsellerDataItem>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "rank": 1,
        "asin": "B0TOP001",
        "title": "Best Selling Wireless Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/top1.jpg",
        "price": { "amount": 24.99, "currency": "USD" },
        "rating": 4.7,
        "reviewCount": 5600,
        "rankChange": 0,
        "isNew": false
      },
      {
        "rank": 2,
        "asin": "B0TOP002",
        "title": "Premium Noise Cancelling Headphones",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/top2.jpg",
        "price": { "amount": 49.99, "currency": "USD" },
        "rating": 4.5,
        "reviewCount": 3200,
        "rankChange": 2,
        "isNew": false
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

---

POST /api/v2/monitoring/asin/subscribe — ASIN订阅

创建 ASIN 监控订阅，跟踪指定商品的价格、排名等变化。

数据来源：

平台	原始接口
Sorftime	MonitorApi.subscribeAsin → POST /api/sorftime/forward → /api/AsinSubscribe

请求参数：

参数	类型	必填	说明
asin	string	是	商品 ASIN
domain	string	是	市场域名，如 amazon.com
frequency	string	否	监控频率：daily | weekly，默认 daily

响应类型：

// ApiResponse<SubscribeResult>
// SubscribeResult 定义见 bestseller/subscribe

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "asin_task_20250101_001",
    "status": "active",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

---

GET /api/v2/monitoring/asin/list — ASIN订阅列表

获取当前所有 ASIN 监控订阅。

数据来源：

平台	原始接口
Sorftime	MonitorApi.getAsinSubscriptions → POST /api/sorftime/forward → /api/AsinSubscriptions

请求参数：

参数	类型	必填	说明
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应类型：

interface AsinSubscriptionItem {
  /** 任务 ID */
  taskId: string;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 主图 URL */
  imageUrl: string;
  /** 市场域名 */
  domain: string;
  /** 监控频率 */
  frequency: string;
  /** 当前价格 */
  currentPrice: Money | null;
  /** 任务状态：active | paused | expired */
  status: string;
  /** 创建时间 ISO 8601 */
  createdAt: string;
  /** 最近更新时间 ISO 8601 */
  lastUpdatedAt: string | null;
}

// ApiResponse<PaginatedResponse<AsinSubscriptionItem>>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "taskId": "asin_task_20250101_001",
        "asin": "B0EXAMPLE1",
        "title": "Wireless Bluetooth Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg",
        "domain": "amazon.com",
        "frequency": "daily",
        "currentPrice": { "amount": 29.99, "currency": "USD" },
        "status": "active",
        "createdAt": "2025-01-01T00:00:00.000Z",
        "lastUpdatedAt": "2025-01-15T06:00:00.000Z"
      }
    ],
    "total": 12,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}

---

GET /api/v2/monitoring/asin/data — ASIN订阅数据

获取 ASIN 监控的历史数据（价格、排名变化等）。

数据来源：

平台	原始接口
Sorftime	MonitorApi.getAsinMonitorData → POST /api/sorftime/forward → /api/AsinMonitorData

请求参数：

参数	类型	必填	说明
asin	string	是	商品 ASIN
startDate	string	否	开始日期 ISO 8601
endDate	string	否	结束日期 ISO 8601

响应类型：

interface AsinMonitorDataPoint {
  /** 日期 ISO 8601 */
  date: string;
  /** 价格 */
  price: Money | null;
  /** BSR 排名 */
  salesRank: number | null;
  /** 评分 */
  rating: number | null;
  /** 评论数 */
  reviewCount: number | null;
}

interface AsinMonitorData {
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 数据点列表 */
  dataPoints: AsinMonitorDataPoint[];
}

// ApiResponse<AsinMonitorData>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "asin": "B0EXAMPLE1",
    "title": "Wireless Bluetooth Earbuds",
    "dataPoints": [
      {
        "date": "2025-01-01T00:00:00.000Z",
        "price": { "amount": 29.99, "currency": "USD" },
        "salesRank": 156,
        "rating": 4.5,
        "reviewCount": 1250
      },
      {
        "date": "2025-01-02T00:00:00.000Z",
        "price": { "amount": 27.99, "currency": "USD" },
        "salesRank": 142,
        "rating": 4.5,
        "reviewCount": 1265
      }
    ]
  }
}

---

5.8 卖家信息 (Sellers)

仅 Amazon 平台

---

GET /api/v2/sellers/account — 卖家账户信息

获取当前卖家的账户基本信息。

数据来源：

平台	原始接口
Amazon	SellersApi.getMarketplaceParticipations → GET /api/amazon/sellers/marketplaceParticipations

请求参数：

无

响应类型：

interface SellerAccount {
  /** 卖家 ID */
  sellerId: string;
  /** 卖家名称 */
  name: string;
  /** 账户状态：active | inactive */
  status: string;
  /** 注册市场列表 */
  marketplaces: {
    /** 市场 ID */
    marketplaceId: string;
    /** 市场名称 */
    name: string;
    /** 国家代码 */
    countryCode: string;
    /** 默认货币 */
    defaultCurrency: string;
    /** 是否参与 */
    isParticipating: boolean;
  }[];
}

// ApiResponse<SellerAccount>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "sellerId": "A1EXAMPLE123",
    "name": "ExampleStore",
    "status": "active",
    "marketplaces": [
      {
        "marketplaceId": "ATVPDKIKX0DER",
        "name": "Amazon.com",
        "countryCode": "US",
        "defaultCurrency": "USD",
        "isParticipating": true
      },
      {
        "marketplaceId": "A1F83G8C2ARO7P",
        "name": "Amazon.co.uk",
        "countryCode": "GB",
        "defaultCurrency": "GBP",
        "isParticipating": true
      }
    ]
  }
}

---

GET /api/v2/sellers/marketplaces — 卖家市场列表

获取卖家已注册的市场列表及参与状态。

数据来源：

平台	原始接口
Amazon	SellersApi.getMarketplaceParticipations → GET /api/amazon/sellers/marketplaceParticipations

请求参数：

无

响应类型：

interface MarketplaceItem {
  /** 市场 ID */
  marketplaceId: string;
  /** 市场名称 */
  name: string;
  /** 国家代码 */
  countryCode: string;
  /** 默认语言 */
  defaultLanguage: string;
  /** 默认货币 */
  defaultCurrency: string;
  /** 域名 */
  domain: string;
  /** 是否参与 */
  isParticipating: boolean;
}

// ApiResponse<{ items: MarketplaceItem[] }>

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "marketplaceId": "ATVPDKIKX0DER",
        "name": "Amazon.com",
        "countryCode": "US",
        "defaultLanguage": "en_US",
        "defaultCurrency": "USD",
        "domain": "amazon.com",
        "isParticipating": true
      },
      {
        "marketplaceId": "A1F83G8C2ARO7P",
        "name": "Amazon.co.uk",
        "countryCode": "GB",
        "defaultLanguage": "en_GB",
        "defaultCurrency": "GBP",
        "domain": "amazon.co.uk",
        "isParticipating": true
      }
    ]
  }
}

---

附录：数据来源映射总表

以下表格列出所有 /api/v2/ 统一接口与原始平台接口的完整映射关系。

5.1 商品管理 (Products)

统一接口	方法	原始平台	原始接口
/api/v2/products/search	GET	Amazon	GET /api/amazon/catalog/items
/api/v2/products/search	GET	Sorftime	POST /api/sorftime/forward → /api/ProductQuery
/api/v2/products/:id	GET	Amazon	GET /api/amazon/catalog/items/:asin
/api/v2/products/:id	GET	Sorftime	POST /api/sorftime/forward → /api/ProductRequest
/api/v2/products/:id/sales	GET	Amazon	GET /api/amazon/sales/orderMetrics
/api/v2/products/:id/sales	GET	Sorftime	POST /api/sorftime/forward → /api/AsinSalesVolume
/api/v2/products/:id/reviews	GET	Amazon	GET /api/amazon/customerFeedback/items/:asin/reviews/topics
/api/v2/products/:id/reviews	GET	Sorftime	POST /api/sorftime/forward → /api/ProductReviewsQuery
/api/v2/products/:id/similar	GET	Sorftime	POST /api/sorftime/forward → /api/SimilarProductRealtimeRequest

5.2 关键词分析 (Keywords)

统一接口	方法	原始平台	原始接口
/api/v2/keywords/search	GET	Sorftime	POST /api/sorftime/forward → /api/KeywordQuery
/api/v2/keywords/:keyword/products	GET	Sorftime	POST /api/sorftime/forward → /api/KeywordProductRanking
/api/v2/keywords/reverse/:asin	GET	Sorftime	POST /api/sorftime/forward → /api/ASINRequestKeyword
/api/v2/keywords/reverse/:asin	GET	Sorftime	POST /api/sorftime/forward → /api/KeywordRequest
/api/v2/keywords/:keyword/trend	GET	Sorftime	POST /api/sorftime/forward → /api/KeywordSearchResultTrend

5.3 类目分析 (Categories)

统一接口	方法	原始平台	原始接口
/api/v2/categories/tree	GET	Amazon	GET /api/amazon/catalog/categories
/api/v2/categories/tree	GET	Sorftime	POST /api/sorftime/forward → /api/CategoryTree
/api/v2/categories/:id/top-products	GET	Sorftime	POST /api/sorftime/forward → /api/CategoryRequest
/api/v2/categories/:id/top-products	GET	Sorftime	POST /api/sorftime/forward → /api/CategoryProducts
/api/v2/categories/:id/keywords	GET	Sorftime	POST /api/sorftime/forward → /api/CategoryRequestKeyword

5.4 订单管理 (Orders)

统一接口	方法	原始平台	原始接口
/api/v2/orders	GET	Amazon	GET /api/amazon/orders
/api/v2/orders/:id	GET	Amazon	GET /api/amazon/orders/:orderId
/api/v2/orders/:id	GET	Amazon	GET /api/amazon/orders/:orderId/items
/api/v2/orders/metrics	GET	Amazon	GET /api/amazon/sales/orderMetrics

5.5 Listing 管理 (Listings)

统一接口	方法	原始平台	原始接口
/api/v2/listings	GET	Amazon	GET /api/amazon/listings/items/:sellerId
/api/v2/listings/:sku	GET	Amazon	GET /api/amazon/listings/items/:sellerId/:sku

5.6 TikTok 数据 (TikTok)

统一接口	方法	原始平台	原始接口
/api/v2/tiktok/users/:uniqueId	GET	TikHub	GET /api/tikhub/tiktok/user/info
/api/v2/tiktok/videos/:id	GET	TikHub	GET /api/tikhub/tiktok/video/info
/api/v2/tiktok/videos/:id/comments	GET	TikHub	GET /api/tikhub/tiktok/video/comments
/api/v2/tiktok/users/:id/followers	GET	TikHub	GET /api/tikhub/tiktok/user/followers
/api/v2/tiktok/users/:id/following	GET	TikHub	GET /api/tikhub/tiktok/app/v3/user-following
/api/v2/tiktok/shop/products/:id	GET	TikHub	GET /api/tikhub/tiktok/shop/product-detail
/api/v2/tiktok/ads/:id	GET	TikHub	GET /api/tikhub/tiktok/ads/ads-detail

5.7 监控与订阅 (Monitoring)

统一接口	方法	原始平台	原始接口
/api/v2/monitoring/bestseller/subscribe	POST	Sorftime	POST /api/sorftime/forward → /api/BestsellerSubscribe
/api/v2/monitoring/bestseller/tasks	GET	Sorftime	POST /api/sorftime/forward → /api/BestsellerTasks
/api/v2/monitoring/bestseller/:taskId/data	GET	Sorftime	POST /api/sorftime/forward → /api/BestsellerData
/api/v2/monitoring/asin/subscribe	POST	Sorftime	POST /api/sorftime/forward → /api/AsinSubscribe
/api/v2/monitoring/asin/list	GET	Sorftime	POST /api/sorftime/forward → /api/AsinSubscriptions
/api/v2/monitoring/asin/data	GET	Sorftime	POST /api/sorftime/forward → /api/AsinMonitorData

5.8 卖家信息 (Sellers)

统一接口	方法	原始平台	原始接口
/api/v2/sellers/account	GET	Amazon	GET /api/amazon/sellers/marketplaceParticipations
/api/v2/sellers/marketplaces	GET	Amazon	GET /api/amazon/sellers/marketplaceParticipations