← 返回目录
📁 API Reference › Catalog Products

通过文件 URL 上传商品

您可以使用本接口以文件 URL 的方式上传商品，系统将会异步录入文件中的商品。您将会从返回中得到一个任务处理 ID（feed_log_id）。通过该ID您可以调用/catalog/product/log/查看任务的处理状态和最终结果。

和普通上传商品接口/catalog/product/upload/不同，该接口主要用于商品库的初始化以及每日定时全量更新商品。

目前本接口只允许上传CSV格式的商品库更新源。 不同类型的商品库对应的商品库更新源CSV模板不同。以下为不同类型的商品库对应的模板： - 电商商品库模板 - 酒店商品库模板 - 航班商品库模板 - 目的地商品库模板 - 娱乐商品库模板 - 汽车库存商品库模板 - 汽车型号商品库模板 - 短剧商品库模版
商品图片（image_link）规格必须大于等于500x500像素，否则商品将无法通过审核。详细信息请参考商品图片要求。

注意
- 娱乐商品库目前在 Alpha 测试阶段，是仅向受邀开发者开放的白名单功能。如需使用此功能，请联系您的TikTok销售代表，但无法保证申请就能入选。 - 短剧商品库目前在测试阶段，是仅向受邀开发者开放的白名单功能。如需使用此功能，请联系您的 TikTok 销售代表，但无法保证申请就能入选。 - 同一商品库下SKU唯一，且仅归属于某一更新源。针对某SKU的所有操作需要在其归属的更新源下进行。 - 一个更新源只能同时处理一个文件任务，若当前任务未完成，新的任务会提交失败。请等待当前任务处理完成后再发送下一个任务。商品处理速度大约是 500万/小时，受服务负载影响，该数值仅供参考。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径| /v1.2/catalog/product/file/| /v1.3/catalog/product/file/| |请求参数类型|bc_id: number<br>catalog_id: number|bc_id: string<br>catalog_id: string| |请求参数名称和类型 |feeds_id: number|feed_id: string| |新增请求参数|/|update_mode: string| |返回参数类型|feed_log_id: number|feed_log_id`: string|


## 请求

**地址** https://business-api.tiktok.com/open_api/v1.3/catalog/product/file/

**方法** POST

**Header**

```xtable
|字段|类型|描述|
|--- |--- |--- |
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型。<br>允许格式：`application/json`。|

参数

|字段|类型|描述|
|--- |--- |--- |
|bc_id {必填}|string|商务中心ID。|
|catalog_id {必填}|string|商品库ID。|
|feed_id|string|更新源ID。|
|file_url {必填}|string|商品上传文件（CSV 格式）的下载地址。建议商品数量不要超过 20,000,000 个。<br><br><ul><li>目前 API 只允许上传 CSV 格式的文件。不同类型的商品库的 CSV 模版如下：<ul><li>[电商商品库模板](https://bytedance.feishu.cn/sheets/shtcnZ3VnFbOO64OiFNZRhlz8Db)</li><li>[酒店商品库模板](https://bytedance.feishu.cn/sheets/FJNUsA17Xhp540t41Kecq8ZInCf)<ul><li> 若 CSV 文件包含别名字段，系统将自动将别名字段映射到对应的已有字段。若想了解别名字段和对应的已有字段，可查看<a href="#item-link-酒店商品库的别名字段">酒店商品库的别名字段</a>。</li></ul></li><li>[航班商品库模板](https://bytedance.feishu.cn/sheets/SII0sykCGhEObgtJaENcPSDpnyc)<ul><li> 若 CSV 文件包含别名字段，系统将自动将别名字段映射到对应的已有字段。若想了解别名字段和对应的已有字段，可查看<a href="#item-link-航班商品库的别名字段">航班商品库的别名字段</a>。</li></ul></li><li>[目的地商品库模板](https://bytedance.feishu.cn/sheets/OvJIsVlNfhl30ttKs7MciksInPh)</li><li> [娱乐商品库模板](https://bytedance.feishu.cn/sheets/MrBAsQuGchn0pQtRRiyc47lynyg)</li><li>[汽车库存商品库模板](https://bytedance.sg.larkoffice.com/sheets/QuGIs2PgjhXLtOtDLaBceZnVnVg)</li><li>[汽车型号商品库模板](https://bytedance.sg.larkoffice.com/sheets/RjwhsCwlIhepPHtOq1SlD868g8b)</li><li>[短剧商品库模版](https://bytedance.sg.larkoffice.com/sheets/SmHxs8C4oh0mKWtenOslDZ0Sg6b)</li></ul> 若想获取每个商品参数的详细描述，请查看[对象数组`products`参数](https://business-api.tiktok.com/portal/docs?id=1740497429681153#item-link-对象数组products参数)。<br>  若想了解 JSON 格式中的字段及其枚举值在 CSV 模版中的对应字段和枚举值，请查看[ JSON 结构与 CSV 模版中的商品参数对比](https://bytedance.sg.larkoffice.com/sheets/RRBzsvD6PhBJdKtqrg2lJ21Zgtg?sheet=gJ73Xi) 。</li><li>商品图片（`image_link`）规格必须大于等于500x500像素，否则商品将无法通过审核。详细信息请参考[商品图片要求](https://ads.tiktok.com/marketing_api/docs?id=1739578479392770)。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>如需将定向多个地域的短剧上传至短剧商品库，需多次调用 [/catalog/product/upload/](1740497429681153.html) 接口并传入相同的 `series_id` 和不同的 `country`设置 。上传后，可以通过 [/catalog/product/get/](1740564136678402.html) 接口中的 `target_config` 和 `additional_product_list` 获取同一短剧的合并后的定向设置。<ul><li>例如，如果将`country` 分别设置为 `&#123;"region_code": "US"&#125;`（即短剧商品库的主要定向地域）和 `&#123;"region_code": "VN"&#125;`（即短剧商品库的一个额外定向地域）从而上传两次短剧，则[/catalog/product/get/](1740564136678402.html) 接口返回的 `list.target_config.region_code` 将为 `US`，`list.additional_product_list.region_code` 将为 `VN`。</li></ul></li><li>如果附加图片 URL 中包含逗号（,），需先对逗号进行 URL 编码，替换为 %2C，然后再将该 URL 传入此字段中。<br>例如，针对以下两个 URL：`https://img.example.com/product.jpg?width=800&height=600&quality=85&format=webp` 和<br>`https://img.example.com/product_800x600<b>,</b>q85<b>,</b>webp.jpg`，应将本字段设置为`["https://img.example.com/product.jpg?width=800&height=600&quality=85&format=webp","https://img.example.com/product_800x600<b>%2C</b>q85<b>%2C</b>webp.jpg"]`。</li></ul>|
|update_mode|string|更新模式。该模式仅单次有效，只应用于当前请求。<br>枚举值：<ul><li>`OVERWRITE`：在本模式下，您上传的商品文件中的商品将替换商品库中当前的所有商品。</li><li>`INCREMENTAL`：在本模式下，您上传的商品文件中的商品将增加到商品库中。请注意若您上传了商品库中已有的商品（SKU ID重复），则该商品的数据将由您上传文件中的该商品对应数据所覆盖。</li></ul>默认值：`INCREMENTAL`。<br><p><span style="color:darkred"><b>注意</b></span>：若您传入了 `feed_id`，则您通过本字段指定的更新模式不会影响指定的更新源的更新模式。 |

酒店商品库的别名字段

下表列出了酒店商品库中可用的别名字段和对应已有字段。例如，如果指定了 image[0].url，该字段将会自动映射为 image_link。

| 现有字段 {30%} | 对应别名字段 {60%} |
|---|---|
| `name` | `hotel_name` |
| `image_link` | `image[0].url` |
| `video_link` | `video[0].url` |
| `address` | `addr1`<br>`address.addr1` |
| `secondary_address` | `addr2`<br>`address.addr2` |
| `tertiary_address` | `addr3`<br>`address.addr3` |
| `neighborhood` | `neighborhood[0]` |
| `rating_system` | `guest_rating[0].rating_system` |
| `max_score` | `guest_rating[0].max_score` |
| `guest_ratings.score` | `guest_rating[0].score` |
| `guest_ratings.number_of_reviewers` | `guest_rating[0].number_of_reviewers` |
| `price` | `base_price` |
| `link` | `url` |
| `ios_url` | `applink.ios_url` |
| `ios_app_store_id` | `applink.ios_app_store_id` |
| `ios_app_name` | `applink.ios_app_name` |
| `android_url` | `applink.android_url` |
| `android_package` | `applink.android_package` |
| `android_app_name` | `applink.android_app_name` |
| `internal_label[0]` | `product_tags[0]`<br>`internal_label ` |
| `internal_label[1]` | `product_tags[1]` |

航班商品库的别名字段

下表列出了航班商品库中可用的别名字段和对应已有字段。例如，如果指定了 image[0].url，该字段将会自动映射为 image_link。

| 现有字段 {30%} | 对应别名字段 {60%} |
|---|---|
| `image_link` | `image[0].url` |
| `video_link` | `video[0].url` |
| `link` | `url` |
| `ios_url` | `applink.ios_url` |
| `ios_app_store_id` | `applink.ios_app_store_id` |
| `ios_app_name` | `applink.ios_app_name` |
| `android_url` | `applink.android_url` |
| `android_package` | `applink.android_package` |
| `android_app_name` | `applink.android_app_name` |
| `internal_label[0]` | `product_tags[0]` |
| `internal_label[1]` | `product_tags[1]` |

示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/' \
--data '{
    "app_id" : "{{app_id}}",
    "auth_code" : "{{auth_code}}",
    "secret" : "{{secret}}"
}'
(/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|返回数据。|
#|feed_log_id|string|商品处理日志ID。|

示例

(code Success-Response http) 
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "feed_log_id": "{{feed_log_id}}"
    },
    "request_id": "{{request_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 每日平台更新简报 →