**版本：202601**

# 根据 SPU 获取数据分析

**POST** `/openapi/2026-01/data-analysis/spu`

通过 SPU、SKU 或专辑维度分析商品，提供详细的销售数据洞察。

## 请求

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `type` string (required)

  分析对象类型，可选值：`product`、`variant`、`collection`
- `begin_time` string (required)

  开始时间：Unix 时间戳（秒），以字符串形式传递（例如 "1748736000"）；需小于 end\_time，通常取目标时区当天 0 点
- `end_time` string (required)

  结束时间：Unix 时间戳（秒），以字符串形式传递（例如 "1781481600"）；需大于 begin\_time，通常取次日时区当天 0 点
- `cursor` string

  分页游标
- `page_size` int32

  每页记录数

  **默认值：** `10`
- `page` int32

  页码（从 1 开始），与 cursor 互斥
- `time_zone` int32

  时区偏移（小时）；推荐范围 -12 至 14
- `sort_by` string

  排序字段，可选值：

  *   `created_at`：商品创建时间
  *   `first_published_at`：首次上架时间
  *   `published_at`：最近上架时间
  *   `product_op_updated_at`：商品最后操作更新时间
  *   `order_count`：订单数量
  *   `sales_count`：销售数量
  *   `sales_total`：总销售额
  *   `net_sales_total`：净销售额
  *   `discount`：折扣金额
  *   `tax`：税费金额
  *   `views_count`：浏览次数
  *   `add_to_cart_count`：加购次数
  *   `add_to_cart_rate`：加购率
  *   `view_client_count`：独立浏览用户数
  *   `add_cart_client_count`：独立加购用户数
  *   `add_to_cart_conversion_rate`：加购转化率
  *   `transform_rate`：整体转化率
- `sort_direction` string

  排序方向，可选值：`asc`（升序）、`desc`（降序）
- `collection_id` string

  专辑 ID（传入后将按该专辑筛选结果）
- `keyword` string

  搜索关键词；非空时将按 title、ID、brief、SKU、SPU、tags、note 进行模糊匹配
- `search_model` string

  搜索模式，可选值：`base`（默认，基础模式）、`advanced`（高级模式，启用 `filter` 字段）
- `filter` string

  高级筛选条件（JSON 字符串）；仅当 `search_model` 为 `advanced` 时生效

  结构为扁平 JSON 对象：每个筛选 key 对应一个叶子 `{"operator": "...", "value": ...}`， 多个 key 之间为 AND（本接口不支持 OR 组合）。

  要传的 value 类型由 operator 决定（大小写不敏感）：

  *   `in` / `not in` -> value 为字符串数组，例如 `["SPU001", "SPU002"]`
  *   `like` / `not like` -> value 为字符串，例如 `"shirt"`
  *   `=` `>` `>=` `<` `<=` -> value 为标量（字符串或数字），例如 `10`

  key 与 value 的对应：

  *   列表类 `spu` `sku` `product_id` `title` `tag_list` -> 数组
  *   区间类 `price_min`/`price_max`、`cost_price_min`/`cost_price_max`、`compare_at_price_min`/`compare_at_price_max`、`created_at_min`/`created_at_max`、`updated_at_min`/`updated_at_max` -> 标量
  *   布尔类 `published` `sub_category` -> `"true"` / `"false"`
  *   其他 `collection_id` `keyword` `vendor` `category` `product_note` `sales_platform` -> 字符串

  未识别的 key 会被静默忽略（请求仍返回 200），筛选「不生效」时优先核对 key 拼写。

  例如：`{"spu": {"operator": "in", "value": ["SPU001", "SPU002"]}}`
- `with_impression` boolean

  是否在返回中包含曝光数据
- `filter_crawler_type` string

  爬虫过滤策略，控制统计是否剔除爬虫/机器人流量。可选值：

  *   `no_filter_crawler`：不过滤，统计全部流量（默认）
  *   `official_crawler`：过滤掉已知爬虫/机器人
- `sub_type` string

  分组粒度，仅当 `type` 为 `collection` 时生效。可选值：

  *   `collection`（默认）：按专辑分组，`product_id` 为空
  *   `collection_product`：按专辑 × 商品分组
  *   `product`：按商品分组

```json
{
  "type": "string",
  "begin_time": "string",
  "end_time": "string",
  "cursor": "string",
  "page_size": 10,
  "page": 0,
  "time_zone": 0,
  "sort_by": "string",
  "sort_direction": "string",
  "collection_id": "string",
  "keyword": "string",
  "search_model": "string",
  "filter": "string",
  "with_impression": true,
  "filter_crawler_type": "string",
  "sub_type": "string"
}
```

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `data` object[]

    数据列表

    *   Array \[

    - `utm_source` string

      UTM 来源
    - `utm_medium` string

      UTM 媒介
    - `utm_campaign` string

      UTM 活动名称
    - `utm_term` string

      UTM 关键词
    - `utm_content` string

      UTM 内容
    - `image` string

      图片
    - `title` string

      标题
    - `order_count_original` int32

      原始订单数量
    - `sales_count_original` int32

      原始销售数量
    - `sales_total_original` float

      原始总销售额
    - `net_sales_total_original` float

      原始净销售额
    - `discount_original` float

      原始折扣金额
    - `tax_original` float

      原始税费金额
    - `views_count_original` int32

      原始浏览次数
    - `add_to_cart_count_original` int32

      原始加购次数
    - `views_rate_original` float

      原始浏览率
    - `add_to_cart_rate_original` float

      原始加购率
    - `view_client_count_original` int32

      原始浏览客户端数量
    - `add_cart_client_count_original` int32

      原始加购客户端数量
    - `add_to_cart_conversion_rate_original` float

      原始加购转化率
    - `transform_rate_original` float

      原始转化率
    - `product_id` string

      商品 ID
    - `brief` string

      简要描述
    - `spu` string

      SPU（标准商品单元）
    - `collection` string

      所属专辑
    - `created_at` string

      创建时间（ISO-8601 格式）
    - `first_published_at` string

      首次上架时间（ISO-8601 格式）
    - `published_at` string

      上架时间（ISO-8601 格式）
    - `product_op_updated_at` string

      商品最后操作更新时间（ISO-8601 格式）
    - `published` boolean

      是否已上架
    - `duty_total_original` int32

      原始关税总额
    - `order_count` string

      订单数量
    - `sales_count` string

      销售数量
    - `sales_total` string

      总销售额
    - `net_sales_total` string

      净销售额
    - `discount` string

      折扣金额
    - `tax` string

      税费
    - `views_count` string

      浏览次数
    - `add_to_cart_count` string

      加购次数
    - `views_rate` string

      浏览率
    - `add_to_cart_rate` string

      加购率
    - `view_client_count` string

      浏览客户端数量
    - `add_cart_client_count` string

      加购客户端数量
    - `add_to_cart_conversion_rate` string

      加购到下单转化率
    - `transform_rate` string

      转化率
    - `duty_total` string

      关税总额
    - `seo_url` string

      SEO 友好 URL
    - `impression` string

      曝光次数
    - `collection_id` string

      专辑 ID
    - `collection_title` string

      专辑标题
    - `impression_original` int64

      曝光次数，数值型
    *   \]
  - `count` int32

    记录总数
  - `cursor` string

    分页游标
  - `has_more` boolean

    是否有更多记录

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "data": [
      {
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "image": "string",
        "title": "string",
        "order_count_original": 0,
        "sales_count_original": 0,
        "sales_total_original": 0,
        "net_sales_total_original": 0,
        "discount_original": 0,
        "tax_original": 0,
        "views_count_original": 0,
        "add_to_cart_count_original": 0,
        "views_rate_original": 0,
        "add_to_cart_rate_original": 0,
        "view_client_count_original": 0,
        "add_cart_client_count_original": 0,
        "add_to_cart_conversion_rate_original": 0,
        "transform_rate_original": 0,
        "product_id": "string",
        "brief": "string",
        "spu": "string",
        "collection": "string",
        "created_at": "string",
        "first_published_at": "string",
        "published_at": "string",
        "product_op_updated_at": "string",
        "published": true,
        "duty_total_original": 0,
        "order_count": "string",
        "sales_count": "string",
        "sales_total": "string",
        "net_sales_total": "string",
        "discount": "string",
        "tax": "string",
        "views_count": "string",
        "add_to_cart_count": "string",
        "views_rate": "string",
        "add_to_cart_rate": "string",
        "view_client_count": "string",
        "add_cart_client_count": "string",
        "add_to_cart_conversion_rate": "string",
        "transform_rate": "string",
        "duty_total": "string",
        "seo_url": "string",
        "impression": "string",
        "collection_id": "string",
        "collection_title": "string",
        "impression_original": 0
      }
    ],
    "count": 0,
    "cursor": "string",
    "has_more": true
  }
}
```