更新广告账户
您可以使用本接口更新商务中心下的广告账户。您还可以使用本接口来更新自动分配模式下商务中心的广告账户月度预算。支持增量更新。您必须是商务中心管理员用户。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径|/v1.2/advertiser/update/|/v1.3/advertiser/update/|
|请求参数类型|advertiser_id: number|advertiser_id: string |
|请求参数类型名称|need_submit_task|need_submit_certificate|
|新增请求参数| /|budget_update_type<br>request_id|
|新增返回参数| /|one_click_set_amount`|
## 请求
**地址** https://business-api.tiktok.com/open_api/v1.3/advertiser/update/
**方法** POST
**Header**
``` xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。 |
|Content-Type {必填}|string|请求消息类型.<br>允许值: `"application/json"`。 |
参数
|字段|类型|描述|
|---|---|---|
| advertiser_id {+条件必填} | string |必传 `advertiser_id` 和 `bc_id` 其中之一。<ul><li>若想更新单个广告账号的非预算设置，传入`advertiser_id`。</li><li>若想更新单个或多个广告账号的预算，传入`bc_id`。</li></ul><br> 广告账号 ID。 |
| advertiser_name | string | 广告账号名称。|
| company | string | 公司名称。<br><br>若想确认是否支持通过 API 更新该广告账户的公司名称，可调用 [/advertiser/info/](1739593083610113.html) 并将`fields`设置为`["company_name_editable"]`。<ul><li>若返回的`company_name_editable`为`true`，您可使用本字段更新公司名称。</li><li>若返回的`company_name_editable`为`false`，您需联系您的 TikTok 代表更新公司名称。</li></ul> |
| contact_name | string | 联系人姓名。|
| contact_email | string | 联系邮箱。 |
| contact_number | string | 联系电话。 |
| promotion_link | string | 推广链接，长度不能超过 255 个字符。 |
| license_no | string |营业执照编号。<br><br><p><span style="color:darkred"><b>注意</b></span>：注册地为中国大陆，中国香港地区，或巴西，墨西哥时支持本字段。 |
| license_image_id | string | 营业执照照片 ID。 |
| qualification_images | object[] |额外资质证明照片。|
#| image_id | string |额外资质证明照片 ID。 |
| address | string |收据上显示的公司地址。<br><br>长度范围：1-1,024 字符。 |
| tax_map | dict[string] |计费和发票税号。不同国家采用不同的字段。例如，法国使用`vat`, 巴西使用 `tax_id` |
| need_submit_certificate | boolean |是否想要提交新的资质证明进行审核。<br><br>支持的值：`true`，`false`。<br><br><p><span style="color:darkred"><b>注意</b></span>: 仅当更新以下任一字段时，将此字段设置为 `true`：<ul><li>`compnay`</li><li>`promotion_link`</li><li>`license_no`</li><li>`license_image_id`</li><li>`qualification_images`</li></ul>如果上述字段均未发生变化，请省略此参数，以避免重新触发营业执照审核流程。 |
| bc_id {+条件必填} | string |必传 `advertiser_id` 和 `bc_id` 其中之一。<ul><li>若想更新单个广告账号的非预算设置，传入`advertiser_id`。</li><li>若想更新单个或多个广告账号的预算，传入`bc_id`。</li></ul><br> 商务中心 ID。<br><br><p><span style="color:darkred"><b>注意</b></span>： 只有拥有财务经理权限（`finance_role` 为 `MANAGER`）的用户才能在商务中心执行更新预算和重置预算消耗操作。您可以使用[/bc/member/invite/](https://ads.tiktok.com/marketing_api/docs?id=1739939455765505) 和 [/bc/member/update/](https://ads.tiktok.com/marketing_api/docs?id=1739516055670786)设置或更改成员权限。 |
| budget_update_type| string | <ul><li>仅当传入 `bc_id` 时支持本字段。</li><li>传入 `advertiser_id` 时不支持本字段。</li></ul><br>您想对预算执行的更改类型。<br><br>枚举值：<ul><li>`UPDATE`：更新预算模式和预算金额。<ul><li>若将本字段设置为 `UPDATE`，需传入`advertiser_budgets` 对象中的 `advertiser_id` 和 `budget`，`budget_mode` 为可选字段。</li></ul></li><li>`RESET`：将广告账号的预算消耗重置为 0。 <ul><li>仅支持对预算模式为自定义（`budget_mode` 为 `CUSTOM_BUDGET`）的广告账号执行重置预算消耗操作。</li><li>若将本字段设置为 `RESET`，仅需传入`advertiser_budgets` 对象中的 `advertiser_id`。若传入了 `budget_mode` 和 `budget` 字段，将忽略`budget_mode` 和 `budget`。</li></ul></li><li>`INCREMENTAL_UPDATE`：增加或减少当前广告账户预算。</li><li>`ONE_CLICK_SET`：将广告账户预算一键设置为最小值。此时无需传入对象数组 `advertiser_budgets` 中的 `budget` 字段。您可通过返回参数 `one_click_set_amount` 获取更改后的预算。</li></ul>默认值：`UPDATE`。<br><br><p><span style="color:darkred"><b>注意</b></span>：`UPDATE`和`RESET`只能对竞价广告账户使用。 |
|request_id|string|仅当 `budget_update_type` 为 `INCREMENTAL_UPDATE` 时生效。<br><br>请求 ID。<br>此字段支持接口幂等，可防止重复发送相同的请求。如果多次使用相同的请求 ID 重试请求，则只有一个会成功。<br>该 ID 和返回参数中的 `request_id` 不同。返回的 `request_id` 用于唯一标识一次 HTTP 请求。<br><br>该值应为一个 32 位字符串。<br><br>示例: `123456789`。<br><br><p><span style="color:darkred"><b>注意</b></span>: 使用 `request_id` 实现广告账号预算增量更新的幂等性目前为白名单功能。如需使用此功能，请联系您的 TikTok 销售代表。</p>|
| advertiser_budgets {+条件必填}| object[] | 传入 `bc_id` 时，本字段必填。<br><br>一个或多个广告账户要更新的预算设置信息。<br><br>最大数量：<ul><li>当 `budget_update_type` 为 `UPDATE` 或 `RESET` 时：50。</li><li>当 `budget_update_type` 为 `INCREMENTAL_UPDATE` 或 `ONE_CLICK_SET` 时：1。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：每个广告账户的月度预算、日预算和自定义预算<b>一天内最多更新 20 次<b>。 |
#|advertiser_id {+条件必填}| string | 传入 `advertiser_budgets` 时，本字段必填。<br><br>广告账户 ID。广告账号需属于所指定的 `bc_id`。 |
#|budget_mode| string | <ul><li>仅当 `budget_update_type` 为 `UPDATE`，`RESET` 或 `ONE_CLICK_SET` 时生效。</li><li>`budget_update_type` 为 `INCREMENTAL_UPDATE` 时，不支持本字段。</li></ul><br>广告账户预算模式。<br><br>枚举值：<ul><li>`UNLIMITED`：不限。广告账户无预算限制。</li><li> `MONTHLY_BUDGET`：月预算。广告账号在月度预算内消耗信用额度。</li><li>`DAILY_BUDGET`：日预算。广告账号在日预算内消耗信用额度。</li><li>`CUSTOM_BUDGET`：自定义预算。广告账号在单次自定义预算内消耗信用额度。</li></ul>`budget_update_type` 为 `UPDATE` 时的默认值：`MONTHLY_BUDGET`。<br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若您未对广告账号的预算模式进行定制，广告账户的预算模式将默认为`UNLIMITED`。</li><li> 合约广告账户无法使用月度预算、日预算和自定义预算进行余额共享。 </li></ul> |
#| budget {+条件必填}| float | `budget_mode` 为 `MONTHLY_BUDGET`、`DAILY_BUDGET` 或 `CUSTOM_BUDGET` 时本字段必填。<br><br><ul><li>当 `budget_update_type` 为 `UPDATE` 或 `RESET` 时，本字段代表广告账户预算，保留两位小数。<ul><li> 若`budget_mode`设置为`UNLIMITED`，则忽略此字段。</li><li> 若`budget_mode`设置为`MONTHLY_BUDGET`，传入月预算。</li><li> 若`budget_mode`设置为`DAILY_BUDGET`，传入日预算。</li><li> 若`budget_mode`设置为`CUSTOM_BUDGET`，传入自定义预算。</li></ul></li><li>当 `budget_update_type` 为 `INCREMENTAL_UPDATE` 时，本字段代表广告账户预算的修改金额。<ul><li>若想增加当前预算，需将 `budget` 设置为一个正数，例如 100。</li><li>若想减少当前预算，需将 `budget` 设置为一个负数，例如 -10。</li></ul></li><li>当 `budget_update_type` 为 `ONE_CLICK_SET` 时，忽略本字段。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>： 若`budget_mode` 设置为`MONTHLY_BUDGET`/`DAILY_BUDGET`/`CUSTOM_BUDGET`，`budget`应不低于105%的当月/当日/当次消耗。您可以使用[/report/integrated/get/](https://ads.tiktok.com/marketing_api/docs?id=1740302848100353)接口来请求报表，获取广告账户的消耗情况（即指标`spend`）。 |
示例
更新单个广告账户的非预算设置
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/advertiser/update/' \
--header 'Access-Token: {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"advertiser_id": "{{advertiser_id}}",
"advertiser_name": "{{advertiser_name}}",
"address":"{{address}}"
}'
(/code)
(code Java java)
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;
import org.apache.http.client.utils.URIBuilder;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
public class Demo {
private static final String ACCESS_TOKEN = "xxx";
private static final String PATH = "/open_api/v1.3/advertiser/update/";
private static final ObjectMapper mapper = new ObjectMapper();
/**
* Build request URL
*
* @param path Request path
* @return Request URL
*/
private static String buildUrl(String path) throws URISyntaxException {
URI uri = new URI("https", "business-api.tiktok.com", path, "", "");
return uri.toString();
}
/**
* Send POST request
*
* @param jsonStr Args in JSON format
* @return Response in JSON format
*/
private static String post(String jsonStr) throws IOException, URISyntaxException {
OkHttpClient client = new OkHttpClient().newBuilder().build();
String url = buildUrl(PATH);
RequestBody body = RequestBody.create(MediaType.parse("application/json"), jsonStr);
Request request = new Request.Builder()
.url(url)
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Access-Token", ACCESS_TOKEN)
.build();
Response response = client.newCall(request).execute();
return response.body().string();
}
public static void main(String[] args) throws IOException, URISyntaxException {
Long advertiser_id = ADVERTISER_ID;
String advertiser_name = ADVERTISER_NAME;
String company = COMPANY;
String contact_name = CONTACT_NAME;
String contact_email = CONTACT_EMAIL;
String contact_number = CONTACT_NUMBER;
String promotion_link = PROMOTION_LINK;
String license_no = LICENSE_NO;
String license_image_id = LICENSE_IMAGE_ID;
String image_id = IMAGE_ID;
String address = ADDRESS;
List < String > tax_map_list = TAX_MAP;
String tax_map = mapper.writeValueAsString(tax_map_list);
String need_submit_certificate = NEED_SUBMIT_CERTIFICATE;
// Args in JSON format
String myArgs = String.format("{\"advertiser_id\": \"%s\", \"advertiser_name\": \"%s\", \"company\": \"%s\", \"contact_name\": \"%s\", \"contact_email\": \"%s\", \"contact_number\": \"%s\", \"promotion_link\": \"%s\", \"license_no\": \"%s\", \"license_image_id\": \"%s\", \"qualification_images\": [{\"image_id\": \"%s\"}], \"address\": \"%s\", \"tax_map\": %s, \"need_submit_certificate\": \"%s\"}",advertiser_id, advertiser_name, company, contact_name, contact_email, contact_number, promotion_link, license_no, license_image_id, image_id, address, tax_map, need_submit_certificate);
System.out.println(post(myArgs));
}
}
(/code)
(code Python python)
# coding=utf-8
import json
import requests
from six import string_types
from six.moves.urllib.parse import urlencode, urlunparse # noqa
ACCESS_TOKEN = "xxx"
PATH = "/open_api/v1.3/advertiser/update/"
def build_url(path, query=""):
# type: (str, str) -> str
"""
Build request URL
:param path: Request path
:param query: Querystring
:return: Request URL
"""
scheme, netloc = "https", "business-api.tiktok.com"
return urlunparse((scheme, netloc, path, "", query, ""))
def post(json_str):
# type: (str) -> dict
"""
Send POST request
:param json_str: Args in JSON format
:return: Response in JSON format
"""
url = build_url(PATH)
args = json.loads(json_str)
headers = {
"Access-Token": ACCESS_TOKEN,
"Content-Type": "application/json",
}
rsp = requests.post(url, headers=headers, json=args)
return rsp.json()
if __name__ == '__main__':
advertiser_id = ADVERTISER_ID
advertiser_name = ADVERTISER_NAME
company = COMPANY
contact_name = CONTACT_NAME
contact_email = CONTACT_EMAIL
contact_number = CONTACT_NUMBER
promotion_link = PROMOTION_LINK
license_no = LICENSE_NO
license_image_id = LICENSE_IMAGE_ID
image_id = IMAGE_ID
address = ADDRESS
tax_map_list = TAX_MAP
tax_map = json.dumps(tax_map_list)
need_submit_certificate = NEED_SUBMIT_CERTIFICATE
# Args in JSON format
my_args = "{\"advertiser_id\": \"%s\", \"advertiser_name\": \"%s\", \"company\": \"%s\", \"contact_name\": \"%s\", \"contact_email\": \"%s\", \"contact_number\": \"%s\", \"promotion_link\": \"%s\", \"license_no\": \"%s\", \"license_image_id\": \"%s\", \"qualification_images\": [{\"image_id\": \"%s\"}], \"address\": \"%s\", \"tax_map\": %s, \"need_submit_certificate\": \"%s\"}" % (advertiser_id, advertiser_name, company, contact_name, contact_email, contact_number, promotion_link, license_no, license_image_id, image_id, address, tax_map, need_submit_certificate)
print(post(my_args))
(/code)
(code PHP php)
$ACCESS_TOKEN = "xxx";
$PATH = "/open_api/v1.3/advertiser/update/";
/**
* Build request URL
* @param $path : Request path
* @return string
*/
function build_url($path)
{
return "https://business-api.tiktok.com" . $path;
}
/**
* Send POST request
* @param $json_str : Args in JSON format
* @return bool|string : Response in JSON format
*/
function post($json_str)
{
global $ACCESS_TOKEN, $PATH;
$curl = curl_init();
$url = build_url($PATH);
curl_setopt_array($curl, array(
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $json_str,
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json",
"Access-Token: " . $ACCESS_TOKEN,
),
));
$response = curl_exec($curl);
curl_close($curl);
return $response;
}
$advertiser_id = ADVERTISER_ID;
$advertiser_name = ADVERTISER_NAME;
$company = COMPANY;
$contact_name = CONTACT_NAME;
$contact_email = CONTACT_EMAIL;
$contact_number = CONTACT_NUMBER;
$promotion_link = PROMOTION_LINK;
$license_no = LICENSE_NO;
$license_image_id = LICENSE_IMAGE_ID;
$image_id = IMAGE_ID;
$address = ADDRESS;
$tax_map_list = TAX_MAP;
$tax_map = json_encode($tax_map_list);
$need_submit_certificate = NEED_SUBMIT_CERTIFICATE;
/* Args in JSON format */
$my_args = sprintf("{\"advertiser_id\": \"%s\", \"advertiser_name\": \"%s\", \"company\": \"%s\", \"contact_name\": \"%s\", \"contact_email\": \"%s\", \"contact_number\": \"%s\", \"promotion_link\": \"%s\", \"license_no\": \"%s\", \"license_image_id\": \"%s\", \"qualification_images\": [{\"image_id\": \"%s\"}], \"address\": \"%s\", \"tax_map\": %s, \"need_submit_certificate\": \"%s\"}", $advertiser_id, $advertiser_name, $company, $contact_name, $contact_email, $contact_number, $promotion_link, $license_no, $license_image_id, $image_id, $address, $tax_map, $need_submit_certificate);
echo post($my_args);
(/code)
更新多个广告账户的预算设置
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/advertiser/update/' \
--header 'Access-Token: {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"bc_id": "{{bc_id}}",
"budget_update_type":"UPDATE",
"advertiser_budgets": [
{
"advertiser_id": "{{advertiser_id}}",
"budget_mode": "CUSTOM_BUDGET",
"budget": {{budget}}
},
{
"advertiser_id": "{{advertiser_id}}",
"budget_mode": "UNLIMITED"
}
]
}'
(/code)
重置预算模式为自定义的广告账户的预算消耗
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/advertiser/update/' \
--header 'Access-Token: {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"bc_id": "{{bc_id}}",
"budget_update_type":"RESET",
"advertiser_budgets": [
{
"advertiser_id": "{{advertiser_id}}"
}
]
}'
(/code)
增加广告账户预算
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/advertiser/update/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data '{
"bc_id": "{{bc_id}}",
"budget_update_type": "INCREMENTAL_UPDATE",
"advertiser_budgets": [{
"advertiser_id": "{{advertiser_id}}"
"budget": 100
}]
}'
(/code)
减少广告账户预算
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/advertiser/update/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data '{
"bc_id": "{{bc_id}}",
"budget_update_type": "INCREMENTAL_UPDATE",
"advertiser_budgets": [{
"advertiser_id": "{{advertiser_id}}"
"budget": -12
}]
}'
(/code)
将广告账户预算设置为最小值
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/advertiser/update/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data '{
"bc_id": "{{bc_id}}",
"budget_update_type": "ONE_CLICK_SET",
"advertiser_budgets": [{
"advertiser_id": "{{advertiser_id}}"
}]
}'
(/code)
返回
|字段|类型|描述|
|---|---|---|
|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|返回数据 。 |
#| list| object[] |仅在请求中指定了`bc_id`和`advertiser_budgets`时返回本字段。<br><br>更新了预算设置的广告账号列表。|
##| advertiser_id| string|广告账户 ID。|
##| status| string | 更新的操作状态。<br><br>枚举值：<ul><li> `SUCCESS`：更新成功。</li><li> `FAILED`：更新失败。</li></ul>|
##| error_msg| string | 报错信息。<br><br>`status` 为 `SUCCESS` 时，本字段值将为 null。|
##| one_click_set_amount | number | 为该广告账户设置的最低预算金额。<br><br>仅当请求中 `budget_update_type` 设置为 `ONE_CLICK_SET` 时返回非 null 值。 |
示例
更新单个广告账户的非预算设置
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {}
}
(/code)
更新多个广告账户的预算设置
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"list": [
{
"advertiser_id": "{{advertiser_id}}",
"error_msg": null,
"status": "{{status}}"
},
{
"advertiser_id": "{{advertiser_id}}",
"error_msg": null,
"status": "{{status}}"
}
]
}
}
(/code)
重置预算模式为自定义的广告账户的预算消耗
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"list": [
{
"advertiser_id": "{{advertiser_id}}",
"status": "SUCCESS",
"error_msg": null
}
]
}
}
(/code)
增加广告账户预算
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"list": [
{
"advertiser_id": "{{advertiser_id}}",
"error_msg": null,
"one_click_set_amount": null,
"status": "SUCCESS"
}
]
}
}
(/code)
减少广告账户预算
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"list": [
{
"advertiser_id": "{{advertiser_id}}",
"error_msg": null,
"one_click_set_amount": null,
"status": "SUCCESS"
}
]
}
}
(/code)
将广告账户预算设置为最小值
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"list": [
{
"advertiser_id": "{{advertiser_id}}",
"error_msg": null,
"one_click_set_amount": 0,
"status": "SUCCESS"
}
]
}
}
(/code)