# 抖音精选联盟订单

分页查询抖音精选联盟订单，包含筛选、排序、响应字段和数据单位说明。

import ApiDebugger from '../../../components/ApiDebugger.astro';

## 接口信息

| 项目 | 值 |
| --- | --- |
| 请求方法 | `GET` |
| 请求 URL | `https://backend.biotech-mkt.com/openapi/v1/doudian/order/union-settlement-orders` |
| 接口路径 | `/openapi/v1/doudian/order/union-settlement-orders` |
| 认证方式 | Bearer Access Token |
| 权限要求 | 接口需启用并授权给当前应用 |
| 频控 | 按应用与接口配置 |

<ApiDebugger preset="union-settlement-orders" lang="zh" />

分页查询平台已经同步入库的抖音精选联盟订单。

## 认证与授权

该接口需要 Access Token，并且必须由平台管理员完成接口登记、启用和应用授权。

## 请求参数

### 分页与排序

| 参数                 | 类型    | 默认值 | 说明                                     |
| -------------------- | ------- | ------ | ---------------------------------------- |
| `page`               | integer | `1`    | 页码，从 1 开始                          |
| `page_size`          | integer | `10`   | 每页记录数                               |
| `order_by`           | string  | `id`   | 排序字段，建议使用 `id` 或 `update_time` |
| `order_by_direction` | string  | `desc` | `asc` 或 `desc`                          |

### 文本筛选

以下参数使用包含匹配：

| 参数                   | 说明            |
| ---------------------- | --------------- |
| `order_id`             | 订单号          |
| `shop_name`            | 商家名称        |
| `product_id`           | 商品 ID         |
| `product_name`         | 商品名称        |
| `product_img`          | 商品图片 URL    |
| `media_type`           | 带货体裁代码    |
| `flow_point`           | 订单状态代码    |
| `app`                  | App 名称        |
| `author_buyin_id`      | 达人百应 ID     |
| `author_short_id`      | 作者抖音号      |
| `author_account`       | 作者账号昵称    |
| `distributor_buyin_id` | 独立抖客百应 ID |
| `distributor_name`     | 独立抖客昵称    |

### 精确与多值筛选

以下参数传单个值时使用精确匹配；以 `field[]=a&field[]=b` 传多个值时使用集合匹配：

| 参数                         | 说明                       |
| ---------------------------- | -------------------------- |
| `media_id`                   | 视频或直播间 ID            |
| `app_id`                     | 内容端 App ID              |
| `buyer_app_id`               | 购买端 App ID              |
| `shop_id`                    | 店铺 ID                    |
| `item_num`                   | 商品数量                   |
| `total_pay_amount`           | 订单支付金额，单位元       |
| `pay_goods_amount`           | 预估参与结算金额，单位元   |
| `settled_goods_amount`       | 实际参与结算金额，单位元   |
| `estimated_commission`       | 达人预估佣金，单位元       |
| `real_commission`            | 达人实际佣金，单位元       |
| `estimated_total_commission` | 预估总佣金，单位元         |
| `shop_estimated_commission`  | 商家预估佣金支出，单位元   |
| `shop_real_commission`       | 商家实际佣金支出，单位元   |
| `ads_estimated_commission`   | 独立抖客预估推广费，单位元 |
| `ads_real_commission`        | 独立抖客实际推广费，单位元 |
| `settled_tech_service_fee`   | 平台结算技术服务费，单位元 |
| `commission_rate`            | 达人佣金率，百分比值       |
| `ads_promotion_rate`         | 独立抖客推广费率，百分比值 |
| `tenant_id`                  | 租户 ID                    |
| `dept_id`                    | 部门 ID                    |
| `created_by`                 | 创建者 ID                  |
| `updated_by`                 | 更新者 ID                  |

### 时间筛选

以下参数传单个值时精确匹配；传两个数组值时按闭区间筛选：

| 参数               | 说明               |
| ------------------ | ------------------ |
| `pay_success_time` | 付款时间           |
| `confirm_time`     | 确认收货时间       |
| `settle_time`      | 结算时间           |
| `refund_time`      | 退款时间           |
| `update_time`      | 联盟侧订单更新时间 |
| `created_at`       | 本地记录创建时间   |

建议使用 `YYYY-MM-DD HH:mm:ss` 格式，并通过 URL 编码传递空格。

## 请求示例

```bash
curl --get "https://backend.biotech-mkt.com/openapi/v1/doudian/order/union-settlement-orders" \
  --header "Authorization: Bearer $OPENAPI_ACCESS_TOKEN" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20" \
  --data-urlencode "shop_id=10001" \
  --data-urlencode "flow_point=SETTLE" \
  --data-urlencode "update_time[]=2026-08-01 00:00:00" \
  --data-urlencode "update_time[]=2026-08-26 23:59:59"
```

## 应答字段

`data.list` 中字段随当前数据表记录序列化返回；金额和费率等 Decimal 字段通常表现为保留两位小数的字符串。`data.total` 为符合筛选条件的记录总数。

### 响应结构

| 字段         | 返回类型        | 说明                       |
| ------------ | --------------- | -------------------------- |
| `code`       | integer         | 业务状态码，成功时为 `200` |
| `message`    | string          | 响应消息                   |
| `data`       | object          | 分页响应数据               |
| `data.list`  | `array<object>` | 当前页订单记录             |
| `data.total` | integer         | 符合筛选条件的订单记录总数 |

### 订单与平台字段

| 字段                | 返回类型 | 说明                                           |
| ------------------- | -------- | ---------------------------------------------- |
| `id`                | integer  | 本地记录 ID                                    |
| `order_id`          | string   | 订单号                                         |
| `shop_id`           | integer  | 店铺 ID                                        |
| `shop_name`         | string   | 商家名称                                       |
| `product_id`        | string   | 商品 ID                                        |
| `product_name`      | string   | 商品名称                                       |
| `product_img`       | string   | 商品图片 URL                                   |
| `item_num`          | integer  | 商品数量                                       |
| `media_id`          | integer  | 视频或直播间 ID                                |
| `media_type`        | string   | `shop_list`、`video`、`live` 或 `others`       |
| `media_type_text`   | string   | 带货体裁中文文本                               |
| `app`               | string   | 内容端 App 名称                                |
| `app_id`            | integer  | `1128` 抖音、`1112` 火山、`32` 西瓜、`13` 头条 |
| `app_id_text`       | string   | 内容端 App 中文文本                            |
| `buyer_app_id`      | integer  | 购买端 App ID，另支持 `2329` 抖音极速版        |
| `buyer_app_id_text` | string   | 购买端 App 中文文本                            |
| `extra`             | string   | 上游其他信息                                   |

### 状态与时间字段

| 字段               | 返回类型    | 说明                                        |
| ------------------ | ----------- | ------------------------------------------- |
| `flow_point`       | string      | `PAY_SUCC`、`REFUND`、`SETTLE` 或 `CONFIRM` |
| `flow_point_text`  | string      | 支付完成、退款、结算或确认收货              |
| `pay_success_time` | string/null | 付款时间                                    |
| `confirm_time`     | string/null | 确认收货时间                                |
| `settle_time`      | string/null | 结算时间                                    |
| `refund_time`      | string/null | 退款时间                                    |
| `update_time`      | string/null | 联盟侧订单更新时间                          |
| `created_at`       | string/null | 本地创建时间                                |
| `updated_at`       | string/null | 本地更新时间                                |

### 金额与费率字段

同步入库时，上游“分”金额会除以 100 转为“元”，上游万分比费率会除以 100 转为百分比值。例如上游金额 `12345` 返回 `123.45` 元，上游费率 `450` 返回 `4.50`。

| 字段                           | 返回类型 | 说明                       |
| ------------------------------ | -------- | -------------------------- |
| `total_pay_amount`             | string   | 订单支付金额，元           |
| `pay_goods_amount`             | string   | 预估参与结算金额，元       |
| `settled_goods_amount`         | string   | 实际参与结算金额，元       |
| `estimated_commission`         | string   | 达人预估佣金收入，元       |
| `real_commission`              | string   | 达人实际佣金收入，元       |
| `estimated_total_commission`   | string   | 预估总佣金，元             |
| `shop_estimated_commission`    | string   | 商家预估佣金支出，元       |
| `shop_real_commission`         | string   | 商家实际佣金支出，元       |
| `ads_estimated_commission`     | string   | 独立抖客预估推广费，元     |
| `ads_real_commission`          | string   | 独立抖客实际推广费，元     |
| `settled_tech_service_fee`     | string   | 平台结算技术服务费，元     |
| `commission_rate`              | string   | 达人佣金率，百分比值       |
| `ads_promotion_rate`           | string   | 独立抖客推广费率，百分比值 |
| `colonel_estimated_commission` | string   | 团长预估服务费，元         |
| `colonel_real_commission`      | string   | 团长结算服务费，元         |
| `colonel_commission_rate`      | string   | 团长服务费率，百分比值     |

### 作者、抖客与团长字段

| 字段                       | 返回类型     | 说明            |
| -------------------------- | ------------ | --------------- |
| `author_buyin_id`          | string       | 达人百应 ID     |
| `author_short_id`          | string       | 作者抖音号      |
| `author_account`           | string       | 作者账号昵称    |
| `aweme_id`                 | string       | 抖音 UID        |
| `distributor_buyin_id`     | string       | 独立抖客百应 ID |
| `distributor_name`         | string       | 独立抖客昵称    |
| `colonel_activity_id`      | string       | 团长活动 ID     |
| `colonel_institution_id`   | string       | 团长机构 ID     |
| `colonel_institution_name` | string       | 团长机构名称    |
| `colonel_colonel_buyin_id` | string       | 团长百应 ID     |
| `tenant_id`                | integer      | 租户 ID         |
| `dept_id`                  | integer      | 部门 ID         |
| `created_by`               | integer/null | 创建者 ID       |
| `updated_by`               | integer/null | 更新者 ID       |

:::note[数据时效]
该接口读取平台已经同步入库的数据，不会在请求时实时调用抖店。数据更新时间以记录的 `update_time` 和平台同步任务状态为准。
:::

## 应答示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [
      {
        "id": 101,
        "order_id": "U202608260001",
        "shop_id": 10001,
        "shop_name": "示例店铺",
        "product_id": "90001",
        "product_name": "示例商品",
        "item_num": 1,
        "media_type": "video",
        "media_type_text": "视频",
        "flow_point": "SETTLE",
        "flow_point_text": "结算",
        "total_pay_amount": "123.45",
        "commission_rate": "4.50",
        "pay_success_time": "2026-08-20 10:00:00",
        "update_time": "2026-08-26 12:00:00"
      }
    ],
    "total": 1
  }
}
```

## 错误码与频控

该接口可能返回 `401`、`403`、`404`、`405`、`429` 或 `503`。频控按“应用 ID + 接口 ID”独立计数；具体处理方式和响应头见[错误与频控](/guides/errors-rate-limits)。