tiktok.product.202309.global_categories.recommend
POST/product/202309/global_categories/recommendVia 360: POST https://partner.quantri360.com/v1/tiktok/product/202309/global_categories/recommend
Write endpoint — changes data on TikTok Shop. The key must be created with "Allow write API calls" ticked, otherwise you get 403 write_not_allowed. Every call is logged.
Description
CHỈ NGƯỜI BÁN TOÀN CẦU: Gợi ý ngành hàng lá và cây phân cấp từ tiêu đề, mô tả, ảnh của sản phẩm toàn cầu.
- Gọi qua /v1/tiktok/product/202309/global_categories/recommend với Authorization: Bearer <key>; dùng platform_shop_id khi có nhiều shop. 360 tự gắn app_key, shop_cipher, sign và access_token.
- API GHI: thay đổi dữ liệu thật trên TikTok Shop; cần key có quyền ghi (can_write) và gói mở module products. Gửi nội dung để tạo gợi ý ngành hàng toàn cầu.
- HTTP 200 vẫn có thể có lỗi nghiệp vụ; kiểm code trước khi dùng kết quả.
- API hàng toàn cầu; gian hàng thường bị từ chối với mã 12052910 / 12052032.
Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok/product/202309/global_categories/recommend
Authentication & shop
| Name | In | Type | Sample | Description |
|---|---|---|---|---|
| Authorization | header | header | Bearer q360_live_ab12cd34_… | Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand. |
| platform_shop_id | query | string | 100001 | Gian hàng (lấy ở GET /v1/platforms → shops[].platform_shop_id). BẮT BUỘC khi brand có > 1 gian hàng trên nền tảng; 360 bỏ tham số này trước khi chuyển tiếp. |
Request parameters
| Name | In | Type | Required | Sample | Description |
|---|---|---|---|---|---|
| product_title | body | string | Yes | Áo thun cotton cổ tròn minh họa | Tiêu đề sản phẩm; DE, ES, FR, IE, IT, JP, UK, US dài 1–255 ký tự; MX dài 1–300; khu vực khác 25–255 ký tự. |
| description | body | string | No | <p>Sản phẩm minh họa.</p> | Mô tả HTML tối đa 10.000 ký tự. Tối đa 30 thẻ img, mỗi ảnh dưới 4000 px, có src, width, height; ảnh phải được tải lên trước. Một số thẻ được chuyển đổi để hiển thị, như table thành ảnh. Nên mô tả trên 300 ký tự và 3–5 điểm nổi bật, mỗi điểm dưới 250 ký tự; ảnh khuyến nghị 1600×1600 px; độ dài tối đa: 10,000. |
| images | body | object[] | No | [{"uri": "anh-minh-hoa"}] | Danh sách ảnh. |
| images[].uri | body | string | No | anh-minh-hoa | URI ảnh đã tải lên. |
| category_version | body | string | No | v2 | Phiên bản cây ngành hàng; v2 là cây 7 cấp tại Mỹ, EU, Đông Nam Á; v1 là cây 3 cấp mặc định cho khu vực khác; giá trị liên quan: US. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok/product/202309/global_categories/recommend" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"product_title":"Áo thun cotton cổ tròn minh họa","description":"<p>Sản phẩm minh họa.</p>","images":[{"uri":"anh-minh-hoa"}],"category_version":"v2"}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok/product/202309/global_categories/recommend",
params={},
json={
"product_title": "Áo thun cotton cổ tròn minh họa",
"description": "<p>Sản phẩm minh họa.</p>",
"images": [
{
"uri": "anh-minh-hoa"
}
],
"category_version": "v2"
},
headers={"Authorization": f"Bearer {KEY}"},
timeout=60,
)
print(r.status_code)
print(r.json())Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok/product/202309/global_categories/recommend');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({"product_title":"Áo thun cotton cổ tròn minh họa","description":"<p>Sản phẩm minh họa.</p>","images":[{"uri":"anh-minh-hoa"}],"category_version":"v2"}),
});
console.log(r.status, await r.json());PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok/product/202309/global_categories/recommend' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"product_title":"Áo thun cotton cổ tròn minh họa","description":"<p>Sản phẩm minh họa.</p>","images":[{"uri":"anh-minh-hoa"}],"category_version":"v2"}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;Response
Response fields (as returned by TikTok Shop)
| Name | Type | Sample | Description |
|---|---|---|---|
| code | int | 0 | Mã kết quả; 0 là thành công. |
| message | string | Success | Thông báo kết quả. |
| request_id | string | YEU_CAU_MINH_HOA | Mã yêu cầu để tra cứu lỗi. |
| data | object | Dữ liệu. | |
| leaf_category_id | string | 900000000000000001 | Mã ngành hàng lá. |
| categories | object[] | Danh sách ngành hàng. | |
| id | string | 900000000000000001 | Mã định danh. |
| name | string | Minh họa | Tên. |
| level | int | 1 | Cấp trong cây ngành hàng. |
| is_leaf | bool | false | Có phải ngành hàng lá hay không. |
Response sample
{
"code": 0,
"message": "Success",
"request_id": "YEU_CAU_MINH_HOA",
"data": {
"leaf_category_id": "900000000000000001",
"categories": [
{
"id": "900000000000000001",
"name": "Minh họa",
"level": 1,
"is_leaf": false
}
]
}
}
Get started
- Sign up for Partner
- Enable a data type of the Sản phẩm group on the platform page
- Create an API key (tick the TikTok Shop channel)
- Call it as in the examples above