← 返回目录
📁 API Reference › Subscription

创建订阅

此接口可用于订阅报表指标数据变更、广告账号暂时禁用状态、线索等信息。

根据启用的订阅类型，在以下任一情况下，你将收到通知： - 一个或多个广告账号的 spend、impressions、clicks 或 video_play_actions 报表指标数据发生变更。 - 一个或多个广告账号已暂时禁用或已解除暂时禁用。 - 已创建新线索。 - 你的广告在广告审核时被拒。 - 你的广告或广告组开始产生审美疲劳。 - TikTok 视频与 TTO 营销活动建立关联。 - 涉及一个或多个 API 产品的问题发生、更新或解决。
如需了解更多详情，参见通过订阅 API 订阅广告账号 Webhook 事件。

当你订阅通过线索收集广告（即时表单）收集的线索时，请注意，订阅基于订阅 ID (subscription_id) ，而不是页面 ID (page_id)。 可以在多个订阅中包含同一个页面。

注意
- 订阅广告账号报表指标数据变更目前为白名单功能。如需使用此功能，请通过白名单管理页面申请加入白名单。 - 订阅广告账号暂时禁用状态目前为白名单功能。如需使用此功能，请联系你的 TikTok 销售代表。 - 订阅是相互独立的。如果你针对同一页面创建了两个订阅，取消其中一个订阅不会影响另一个订阅。 - 如果用于配置 Webhook 的 access_token 被撤销（无论是由开发者还是广告主操作），Webhook 订阅将无法继续运行，且不会再接收任何 Webhook 事件。在这种情况下，需重新生成 access_token，并使用新的访问令牌重新配置 Webhook。

v1.2 与 v1.3 接口对比

下表概述了 v1.2 接口与 v1.3 接口之间的差异。 ``xtable |变更{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径|/v1.2/subscription/subscribe/|/v1.3/subscription/subscribe/| |请求参数名称|object<br>url|subscribe_entity<br>callback_url| |请求参数类型|advertiser_id: number<br>library_id: number<br>page_id: number<br>adgroup_id: number<br>ad_id: number|advertiser_id: string<br>library_id: string<br>page_id: string<br>adgroup_id: string<br>ad_id: string| |v1.3 中已弃用的请求参数| /|tcm_account_id| |新增请求参数| /|tto_tcm_account_id<br>lead_source<br>product_filters<br>notify_frequency| |返回参数类型 |subscription_id: number|subscription_id`: string|


## 请求

**地址** https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/

**方法** POST

**Header**
```xtable
|字段|类型|描述|
|---|---|---|
|Content-Type {必填}|string| 请求的内容类型。此接口需使用 `application/json`。|

参数

| 字段|类型|描述 |
|---|---|---|
|app_id{必填}|string| 你的开发者应用的 ID。若想查找<strong>应用 ID</strong>，前往<strong>[应用管理](https://ads.tiktok.com/marketing_api/apps/)</strong> > <strong>App Detail</strong> > <strong>基本信息</strong>。|
|secret {必填}|string| 你的开发者应用的密钥。若想查找<strong>密钥</strong>，前往<strong>[应用管理](https://ads.tiktok.com/marketing_api/apps/)</strong> > <strong>App Detail</strong> > <strong>基本信息</strong>。 |
|subscribe_entity{必填} |string| 要订阅的对象。<br><br>枚举值：<ul><li>`REPORT_DATA_CHANGE`：一个或多个广告账号的任意 `spend`、`impressions`、`clicks` 和 `video_play_actions` 报表指标数据变更。你需要同时传入 `advertiser_ids`。如需查看这些报表指标的详细说明，参见[基础报表 > 支持的指标](1751443967255553.html)。<br><br><p><span style="color:darkred"><b>注意</b></span>：若想使用 `REPORT_DATA_CHANGE` 值，需确保已为开发者应用启用<b>报表</b> > <b>合并报表</b>权限。</p></li><li>`AD_ACCOUNT_SUSPENSION`：广告账号暂时禁用状态。</li><li>`LEAD`：线索。<ul><li>TikTok 保证 Webhook“至少成功发送一次”。因此，Webhook 接口可能会收到重复的事件。为避免潜在问题，你可以设计将事件作幂等处理，防止处理重复事件。</li></ul></li><li>`AD_GROUP`：广告组审核状态。</li><li>`AD`：广告审核状态。</li><li>`TCM_VIDEOS`：TikTok 视频与 TTO 营销活动建立关联。</li><li>`CREATIVE_FATIGUE`：广告、广告组内的广告或广告主账号内的广告的审美疲劳状态。</li><li>`API_SERVICE_STATUS`：API 服务状态。</li></ul>|
|callback_url {必填} |string| 回调 URL。 |
|subscription_detail {必填}|object| 订阅详情。 |
#|access_token {必填}|string| 授权访问令牌。<br><br>可以通过 [/oauth2/access_token/](1738373164380162.html) 接口获取。<br><br><p><span style="color:darkred"><b>注意</b></span>：如果用于配置 Webhook 的 `access_token` 被撤销（无论是由开发者还是广告主操作），Webhook 订阅将无法继续运行，且不会再接收任何 Webhook 事件。在这种情况下，需重新生成 `access_token`，并使用新的访问令牌重新配置 Webhook。|
#|product_filters|string[]|仅当 `subscribe_entity` 为 `API_SERVICE_STATUS` 时生效。<br><br>要订阅的 API 产品列表。<br><br>枚举值：<ul><li>`BUSINESS_CENTER_API`：商务中心 API。</li><li>`CREATIVES_API`：创意 API。</li><li>`CATALOG_API`：商品库管理工具 API。</li><li>`TIKTOK_STORE_API`：TikTok 店铺 API。</li><li>`CAMPAIGN_API`：推广系列管理 API。</li><li>`REPORTING_API`：报告 API。</li><li>`AUDIENCE_API`：受众 API。</li><li>`STREAMING_API`：流媒体 API。</li><li>`EVENTS_API`：事件 API。</li><li>`ACCOUNTS_API`：账号 API。</li><li>`MENTIONS_API`：提及 API。</li><li>`TIKTOK_ONE_API`：TikTok One API。</li><li>`DISCOVERY_API`：发现 API。</li><li>`SPARK_RECOMMEND_API`：Spark Ads 推荐 API。</li><li>`BUSINESS_MESSAGING_API`：Business Messaging API。</li></ul><br>如果不传入 `product_filters`，你将订阅所有 API 产品的更新。|
#| lead_source | string | 仅当 `subscribe_entity` 为 `LEAD` 时生效。<br><br>要订阅的线索来源。<br><br>枚举值：<ul><li>`INSTANT_FORM`：通过即时表单收集的线索。</li><li>`DIRECT_MESSAGE`：通过已关联企业号的私信收集的线索。</li></ul><br>默认值：`INSTANT_FORM`。|
#| bc_id {+条件必填} | string | 如果 `subscribe_entity` 为 `AD_ACCOUNT_SUSPENSION`，需传入 `bc_id` 或 `advertiser_ids`。<br><br>商务中心 ID。<br>你将订阅属于某个商务中心的所有广告账号的暂时禁用状态。<br><br><p><span style="color:darkred"><b>注意</b></span>：你需要确保拥有商务中心的管理员权限。若想获取你拥有管理员权限的商务中心列表，需使用 [/bc/get/](1737115687501826.html) 接口，并选择返回结果中 `user_role` 为 `ADMIN` 的商务中心。 |
#| advertiser_ids {+条件必填} | string[] | <ul><li>如果 `subscribe_entity` 为 `REPORT_DATA_CHANGE`，此为必填字段。</li><li>如果 `subscribe_entity` 为 `AD_ACCOUNT_SUSPENSION`，需传入 `bc_id` 或 `advertiser_ids`。</li></ul><br>广告主 ID 列表。<br><br><ul><li>当 `subscribe_entity` 为 `REPORT_DATA_CHANGE` 时，你将订阅这些广告账号的任意 `spend`、`impressions`、`clicks` 和 `video_play_actions` 报表指标数据变更。</li><li>当 `subscribe_entity` 为 `AD_ACCOUNT_SUSPENSION` 时，你将订阅可能属于不同商务中心的这些广告账号的暂时禁用状态。 </li></ul><br>最大数量：100。 <br><br><p><span style="color:darkred"><b>注意</b></span>：你需要有权访问这些广告账号。若想获取有权访问的广告账号列表，需使用 [/bc/asset/get/](1739432717798401.html) 接口。将 `asset_type` 设置为 `ADVERTISER` ，并选择返回结果中 `advertiser_role` 为 `ADMIN`、`OPERATOR` 或 `ANALYST` 的广告账号。 |
#| notify_frequency | string | 当 `subscribe_entity` 为 `REPORT_DATA_CHANGE` 时生效。<br><br>通知频次。<br>如果你订阅的广告账号的报表指标数据在最近的通知时间范围内发生了变更，你最多会收到一条 Webhook 通知。<br><br>枚举值：<ul><li>`5_MINUTE`：每 5 分钟一次。</li><li>`15_MINUTE`：每 15 分钟一次。</li><li>`30_MINUTE`：每 30 分钟一次。</li><li>`60_MINUTE`：每 60 分钟一次。</li></ul>默认值：`5_MINUTE`。 |
#|advertiser_id {+条件必填}|string|当 `subscribe_entity` 为 `AD_GROUP`、`AD`、`LEAD` 或 `CREATIVE_FATIGUE` 时生效。<br>广告主 ID。 <ul><li>若想订阅广告组或广告的审核状态（`subscribe_entity` 为 `AD_GROUP` 或 `AD`），`advertiser_id` 为必填字段。</li><li> 若想订阅线索（`subscribe_entity` 为 `LEAD`）： <ul><li>当 `lead_source` 为 `INSTANT_FORM` 或不传入时，需传入 `advertiser_id`（用于订阅使用与广告账号关联的即时表单的线索收集广告带来的线索）或 `library_id`（用于订阅使用与表单库关联的即时表单的线索收集广告带来的线索），`page_id` 为选填字段。</li><li>当 `lead_source` 为 `DIRECT_MESSAGE` 时，需传入 `advertiser_id`（用于订阅通过与广告账号关联的私信广告收集的线索）或 `library_id`（用于订阅通过与表单库关联的私信广告收集的线索），不支持 `page_id`。</li></ul></li><li>若想订阅审美疲劳状态（`subscribe_entity` 为 `CREATIVE_FATIGUE`），`advertiser_id` 为必填字段，可以选择传入 `adgroup_id`、`ad_id`，或两者均不传入。若仅传入 `advertiser_id`，你将订阅该广告账号下所有广告的审美疲劳状态。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：如果 `subscribe_entity` 为 `LEAD` 且已传入 `advertiser_id`，你需要拥有广告账号的管理员权限。若想获取有权访问的广告账号列表，需使用 [/bc/asset/get/](1739432717798401.html) 接口。将 `asset_type` 设置为 `ADVERTISER`，并选择返回结果中 `advertiser_role` 为 `ADMIN` 的广告账号。 |
#|library_id {+条件必填}|string|当 `subscribe_entity` 为 `LEAD` 时生效。<br><br>包含要订阅的线索的表单库 ID。<br><br>你可以通过 [/page/library/get/](https://ads.tiktok.com/marketing_api/docs?id=1740029915327489) 返回的 `library_id` 获取表单库 ID。<br><br><ul><li>若想订阅即时表单线索（`subscribe_entity` 为 `LEAD` 且 `lead_source` 为 `INSTANT_FORM` 或不传入），需传入 `advertiser_id` 或 `library_id`，`page_id` 为选填字段。若仅传入 `advertiser_id`，你将订阅该广告账号 (`advertiser_id`) 下的所有 `page_id`。</li><li>若想订阅私信线索（`subscribe_entity` 为 `LEAD` 且 `lead_source` 为 `DIRECT_MESSAGE`），需传入 `advertiser_id` 或 `library_id`，不支持 `page_id`。</li></ul>|
#|page_id  |string|<ul><li>当 `subscribe_entity` 为 `LEAD` 且 `lead_source` 为 `INSTANT_FORM` 或不传入时生效。</li><li>当 `subscribe_entity` 为 `LEAD` 且 `lead_source` 为 `DIRECT_MESSAGE` 时，不支持此字段。</li></ul> <br>要订阅的即时表单的页面 ID。<br><br>若想获取即时表单列表，需使用 [/page/get/](1820826387779586.html) 接口，并将 `business_type` 设置为 `LEAD_GEN`。<br><br>若想订阅即时表单线索（`subscribe_entity` 为 `LEAD` 且 `lead_source` 为 `INSTANT_FORM` 或不传入），需传入 `advertiser_id` 或 `library_id`，`page_id` 为选填字段。若仅传入 `advertiser_id`，你将订阅该广告账号 (`advertiser_id`) 下的所有 `page_id`。 |
#|adgroup_id {+条件必填} |string| 当 `subscribe_entity` 为 `AD_GROUP` 或 `CREATIVE_FATIGUE` 时生效。<br>广告组 ID。 <ul><li>如果 `subscribe_entity` 为 `AD_GROUP`，此为必填字段。</li><li>如果将 `subscribe_entity` 指定为 `CREATIVE_FATIGUE` 并传入 `advertiser_id` 和 `adgroup_id`，你将订阅传入广告组的审美疲劳状态。</li></ul>|
#|ad_id {+条件必填} |string|  当 `subscribe_entity` 为 `AD` 或 `CREATIVE_FATIGUE` 时生效。<br>广告 ID。<ul><li>如果 `subscribe_entity` 为 `AD`，此为必填字段。</li><li>如果将 `subscribe_entity` 指定为 `CREATIVE_FATIGUE` 并传入 `advertiser_id` 和 `ad_id`，你将订阅传入广告的审美疲劳状态。</li></ul> |
#|tto_tcm_account_id {+条件必填}|string| 当 `subscribe_entity` 为 `TCM_VIDEOS` 时，此为必填字段。<br><br>TTO Creator Marketplace 账号的 ID。<br><br>若想获取可通过 `Access-Token` 访问的账号的 ID，需使用 [/tto/oauth2/tcm/](1815693478150146.html) 接口。|

示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/subscription/subscribe/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "app_id": "{{app_id}}", 
    "secret": "{{secret}}",
    "subscription_detail": {
        "advertiser_id": "{{advertiser_id}}", 
        "access_token": "{{access_token}}", 
        "page_id": "{{page_id}}"
    },  
    "subscribe_entity": "LEAD", 
    "callback_url": "{{callback_url}}"
}'
(/code)

返回

|字段|类型|描述|
|---|---|---|
|code |number|返回码。完整返回码列表及描述参见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|message |string|返回信息。更多信息参见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data |object|返回数据。 |
#|subscription_id |string| 订阅 ID |
|request_id |string| 请求的唯一识别 ID。  |

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}"
    "data": {
        "subscription_id": "{{subscription_id}}"
    },
}
(/code);
← 订阅取消订阅 →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →