# 查询已授权达人

- API 版本：1.10.0
- 最后更新：2026-09-29
- 服务地址：`https://api.ailingtu.com`
- 网页文档：[查询已授权达人](/openapi/creators)
- 完整接口约束：[JSON Schema](/openapi/operations/listCreatorAccounts.json)
- 接口发现：[接口索引](/openapi/operations/index.json)

## GET /v1/creatorAccount/pageList

接口标识：`listCreatorAccounts`

查询 TikTok Shop 已授权达人、目标地区和发布权限。响应中的 id 用于查商品，creatorId 用于创建发布任务。

鉴权：请求头 `x-api-key: <YOUR_API_KEY>`；密钥仅保存在服务端。

成功判断：HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `pageSize` | query | integer | 是 | 每页数量，最大 200 |
| `pageNumber` | query | integer | 是 | 页码，从 1 开始 |
| `valid` | query | boolean | 否 | 是否只返回有效授权，默认 true |
| `authSource` | query | string | 否 | 带货发布传 TIKTOK_SHOP_CREATOR |
| `usernames` | query | string[] | 否 | 重复 Query 参数传递多个用户名 |
| `selectionRegion` | query | string | 否 | 目标地区，例如 US |
| `hasPhotoPermission` | query | boolean | 否 | 仅返回有带货图文权限的账号 |
| `ids` | query | integer[] | 否 | 按账号主键筛选；空数组返回空页，不传不筛选；仍受公司及成员权限限制。 |
| `username` | query | string | 否 | 用户名 |
| `registerRegion` | query | string | 否 | 注册地区 |
| `tagName` | query | string | 否 | 标签名称 |

### 成功响应

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 12345,
        "creatorId": "2077242233106595840",
        "username": "shop_creator",
        "authSource": "TIKTOK_SHOP_CREATOR",
        "oauthRegion": "USA",
        "registerRegion": "US",
        "selectionRegion": "US",
        "targetMarket": "US",
        "valid": true,
        "tagNames": [
          "top-tier"
        ],
        "permissions": [
          "VIDEO_SHOPPABLE_PERMISSION",
          "PHOTO_SHOPPABLE_PERMISSION_PRODUCT"
        ]
      }
    ],
    "total": 1,
    "pageNumber": 1,
    "pageSize": 200,
    "totalPages": 1
  },
  "message": "success"
}
```

### 响应字段

以下列出主要层级；完整结构、联合类型及校验规则以接口 JSON Schema 为准。必填指字段所在对象中的约束。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | integer | 是 | 固定值：0 |
| `message` | string | 否 | — |
| `data` | object | 是 | — |
| `data.list` | object[] | 是 | — |
| `data.list[].id` | integer | 是 | 账号记录 ID，用于商品查询接口。 |
| `data.list[].creatorId` | string | 是 | 达人业务 ID，用于创建发布任务。 |
| `data.list[].username` | string | 是 | — |
| `data.list[].authSource` | string \| null | 是 | 授权来源，历史记录可能为 null。；可选值：TIKTOK_LOGIN_KIT、TIKTOK_BUSINESS_ACCOUNT_API、TIKTOK_SHOP_CREATOR、 |
| `data.list[].oauthRegion` | string | 否 | — |
| `data.list[].registerRegion` | string | 否 | — |
| `data.list[].selectionRegion` | string | 否 | — |
| `data.list[].targetMarket` | string \| null | 否 | — |
| `data.list[].valid` | boolean | 是 | — |
| `data.list[].tagNames` | string[] | 否 | — |
| `data.list[].permissions` | string[] | 是 | — |
| `data.list[].creatorUserId` | string | 否 | — |
| `data.list[].avatar` | string | 否 | — |
| `data.list[].sellerType` | string | 否 | — |
| `data.list[].userType` | string | 否 | — |
| `data.list[].creatorOpenId` | string | 否 | — |
| `data.list[].shopId` | integer \| null | 否 | — |
| `data.list[].shopName` | string \| null | 否 | — |
| `data.list[].createdAt` | string | 否 | — |
| `data.list[].managerList` | object[] | 否 | — |
| `data.list[].managerList[].id` | integer | 否 | — |
| `data.list[].managerList[].userId` | integer | 否 | — |
| `data.list[].managerList[].displayName` | string | 否 | — |
| `data.list[].managerAssigned` | boolean | 否 | — |
| `data.total` | integer | 是 | — |
| `data.pageNumber` | integer | 是 | — |
| `data.pageSize` | integer | 是 | — |
| `data.totalPages` | integer | 否 | — |
| `timestamp` | integer | 否 | 响应时间戳，单位毫秒。 |

### 接入说明与限制

- 带货图文需确认 permissions 包含 PHOTO_SHOPPABLE_PERMISSION_PRODUCT。
- 支持 TIKTOK_BUSINESS_ACCOUNT_API 授权来源，响应补充绑定店铺和账号管理成员信息。

### 错误处理

| HTTP | 说明 |
|---|---|
| 400 | 请求参数或请求体无效，请修正后重试。 |
| 401 | API 密钥缺失或无效，请检查 x-api-key。 |
| 403 | API 密钥没有此接口的调用权限。 |
| 429 | 请求过于频繁，请采用指数退避重试。 |
| 500 | 服务端发生错误；对于暂时性故障采用指数退避重试。 |

业务 code 非零时也应按失败处理。不要对参数、权限或授权错误盲目重试。创建发布或生成任务超时后先查询原任务，避免重复创建。