获取授权状态

你可以使用本接口获取 TikTok One（TTO）Creator Marketplace 营销活动的 Spark Ads 授权状态。

请求

地址 https://business-api.tiktok.com/open_api/v1.3/tcm/tt_video/status/

方法 GET

Header

|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|由 TTO Creator Marketplace 账户授权的访问令牌。<br>详情参见[从 TTO Creator Marketplace 账户获取授权和访问令牌](https://business-api.tiktok.com/portal/docs/obtain-authorization-and-authentication-from-a-tto-creator-marketplace-account/v1.3)。|

参数

将这些参数放置在查询字符串部分。

|字段|类型|描述|
|---|---|---|
|video_id {必填}|string|在达人账号下创建的视频的 ID。<br><br>该视频需要满足以下要求：<ul><li>该视频已上传并标记为品牌内容，并且达人已通过由 [/tto/tcm/campaign/create/](1815693549459458.html) 生成的邀请链接(`invite_link`)将视频与一个 TTO Creator Marketplace 营销活动绑定。<ul><li>可以通过 [/tto/tcm/campaign/](1815693562720258.html) 或 [/tto/tcm/report/](1815693573340162.html) 获取 `video_id`。</li></ul></li></ul>|
|tcm_account_id {必填}|string|TTO Creator Marketplace 账号 ID。<br><br>要获取您可以通过 Access-Token 访问的 TTO Creator Marketplace 账号 ID，使用接口 `/tto/oauth2/tcm/`。|

示例

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/tcm/tt_video/status/?tcm_account_id={{tcm_account_id}}&video_id={{video_id}}' \
--header 'Access-Token: {{Access-Token}}'
(/code)

|Field|Data Type|Description|
|---|---|---|
|code |number|返回码。完整返回码列表及描述参见 [附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息。更多信息参见 [附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|request_id|string|请求的日志 ID，唯一标识一个请求。|
|data |object|返回数据。|
#| video_id | string | 视频的 ID。|
#| auth_status | string | 授权状态。<br><br>枚举值：<ul><li>`WAITING`：达人尚未拒绝或批准您的授权请求。<br>达人会在其 TikTok 应用中收到关于您请求的通知，并可通过应用内的系统通知页面批准或拒绝该请求。即使达人已在“品牌内容和广告”设置中启用“广告授权”，只要未批准您的请求，`auth_status` 仍为 `WAITING`。不过，此时您将可以获取到 `auth_code`，从而可以将视频授权给广告主账号。</li><li>`REJECTED`：达人已拒绝您的授权请求。</li><li>`ACCEPTED`：达人已批准您的授权请求。</li></ul>|
#| auth_status_updated_time | string | `auth_status` 最近一次更新的时间。<br><br>例如，当 `auth_status` 从 `WAITING` 变为 `ACCEPTED`。|
#| num_remaining_request | number | 仅返回与 TTCM 订单关联的视频。<br><br>请求 Spark Ads 授权的剩余次数。在授权请求被拒绝或批准前，您最多剩余 30 次请求授权的机会。|
#| requested_authorization_days | number | 您申请授权时指定授权的有效期（按天计），或申请更新已批准授权的有效期。<br><br>枚举值：`7`、`30`、`60`、`365`。<br><br>默认值：`30`。<br><br><p><span style="color:darkred"><b>注意</b></span>：实际有效期（`auth_code_end_time` - `auth_code_start_time`）可能与请求的有效期不同，因为达人在批准请求时可选择任意有效期（`7`、`30`、`60`、`365`）。|
#| auth_code | string | 仅在 `auth_status` 为 `ACCEPTED` 时返回。<br><br>用于订单中视频推广的授权码。|
#| auth_code_start_time | string | 仅在 `auth_status` 为 `ACCEPTED` 时返回。<br><br>授权码生效的 UTC+0 日期和时间。|
#| auth_code_end_time | string | 仅在 `auth_status` 为 `ACCEPTED` 时返回。<br><br>授权码过期的 UTC+0 日期和时间。|
#| auth_code_status | string | 仅在 `auth_status` 为 `ACCEPTED` 时返回。<br><br>授权码状态。<br><br>枚举值：<ul><li>`NOT_USED`：授权码已生成，但尚未使用。</li><li>`IN_USE`：授权码已生成，且正在使用中。</li><li>`EXPIRED`：授权码已生成，且已过期。</li><li>`DELETED`：授权码已被删除。</li></ul>|

示例

授权请求待处理时

(code curl http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "auth_status": "WAITING",
        "auth_status_updated_time": "{{auth_status_updated_time}}",
        "requested_authorization_days": 30,
        "video_id": "{{video_id}}"
    }
}
(/code)

授权请求被批准时

(code curl http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "auth_code": "{{auth_code}}",
        "auth_code_end_time": "{{auth_code_end_time}}",
        "auth_code_start_time": "{{auth_code_start_time}}",
        "auth_code_status": "NOT_USED",
        "auth_status": "ACCEPTED",
        "auth_status_updated_time": "{{auth_status_updated_time}}",
        "requested_authorization_days": 30,
        "video_id": "{{video_id}}"
    }
}
(/code)

授权请求被拒绝时

(code curl http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "auth_status": "REJECTED",
        "auth_status_updated_time": "{{auth_status_updated_time}}",
        "requested_authorization_days": 30,
        "video_id": "{{video_id}}"
    }
}
(/code)