VI | EN
Message us on Messenger
Developer resources

Recommend Category — TikTok Shop API

tiktok.product.202309.categories.recommend · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

tiktok.product.202309.categories.recommend

POST/product/202309/categories/recommendVia 360: POST https://partner.quantri360.com/v1/tiktok/product/202309/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

Gợi ý ngành hàng từ tiêu đề, mô tả và ảnh sản phẩm. Nội dung phải dùng ngôn ngữ của thị trường đích.

  • Gọi qua /v1/tiktok/product/202309/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 sản phẩm để tạo gợi ý ngành hàng.
  • HTTP 200 vẫn có thể có lỗi nghiệp vụ; kiểm code trước khi dùng kết quả.

Request

Endpoint

POST https://partner.quantri360.com/v1/tiktok/product/202309/categories/recommend

Authentication & shop

NameInTypeSampleDescription
AuthorizationheaderheaderBearer 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_idquerystring100001Gian 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

NameInTypeRequiredSampleDescription
category_versionbodystringNov2Phiê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, EU, SEA.
descriptionbodystringNo<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.
imagesbodyobject[]No[{"uri": "anh-minh-hoa"}]Danh sách ảnh.
images[].uribodystringNoanh-minh-hoaURI ảnh đã tải lên.
include_prohibited_categoriesbodyboolNofalseBao gồm ngành hàng cấm đăng.
listing_platformbodystringNoTIKTOK_SHOPNền tảng đăng sản phẩm; giá trị liên quan: TIKTOK_SHOP, TOKOPEDIA.
localebodystringNovi-VNMã ngôn ngữ hiển thị; mặc định theo gian hàng; giá trị liên quan: BCP, CZ, AT, BE, DE, GR, GB, IE, US, ES, MX, FR, HU, IT, JP, MY, NL, PL, BR, PT, TH, VN, CN.
origin_platform_product_typebodystringNoMinh họaLoại sản phẩm trên nền tảng nguồn.
origin_platform_vendorbodystringNoThương hiệu minh họaNhà cung cấp hoặc thương hiệu trên nền tảng nguồn.
origin_platform_tagsbodystring[]No["Minh họa"]Các nhãn trên nền tảng nguồn.
origin_platform_categorybodyobjectNo{"id": "900000000000000001", "name": "Minh họa", "full_name": "Minh họa", "is_leaf": false, "is_root": false}Ngành hàng trên nền tảng nguồn.
origin_platform_category.idbodystringNo900000000000000001Mã định danh.
origin_platform_category.namebodystringNoMinh họaTên.
origin_platform_category.full_namebodystringNoMinh họaTên đầy đủ hoặc đường dẫn ngành hàng.
origin_platform_category.is_leafbodyboolNofalseCó phải ngành hàng lá hay không.
origin_platform_category.is_rootbodyboolNofalseCó phải ngành hàng gốc hay không.
origin_platform_product_meta_databodyobjectNo{"attribute_value_list": [{"name": "Minh họa", "values": ["Minh họa"]}]}Thông tin bổ sung từ nền tảng nguồn.
origin_platform_product_meta_data.attribute_value_listbodyobject[]No[{"name": "Minh họa", "values": ["Minh họa"]}]Danh sách thuộc tính và giá trị.
origin_platform_product_meta_data.attribute_value_list[].namebodystringNoMinh họaTên.
origin_platform_product_meta_data.attribute_value_list[].valuesbodystring[]No["Minh họa"]Các giá trị.
product_titlebodystringYesÁo thun cotton cổ tròn minh họaTiêu đề sản phẩm; DE, ES, FR, IE, IT, JP, UK, US dài 1–255 ký tự; BR, MX dài 1–300; khu vực khác 25–255 ký tự.
is_live_quickbodyboolNofalseSản phẩm LIVE_QUICK; chỉ người bán có quyền tương ứng mới được tạo; giá trị liên quan: LIVE_QUICK.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok/product/202309/categories/recommend" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_version":"v2","description":"<p>Sản phẩm minh họa.</p>","images":[{"uri":"anh-minh-hoa"}],"include_prohibited_categories":false,"listing_platform":"TIKTOK_SHOP","locale":"vi-VN","origin_platform_product_type":"Minh họa","origin_platform_vendor":"Thương hiệu minh họa","origin_platform_tags":["Minh họa"],"origin_platform_category":{"id":"900000000000000001","name":"Minh họa","full_name":"Minh họa","is_leaf":false,"is_root":false},"origin_platform_product_meta_data":{"attribute_value_list":[{"name":"Minh họa","values":["Minh họa"]}]},"product_title":"Áo thun cotton cổ tròn minh họa","is_live_quick":false}'
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok/product/202309/categories/recommend",
    params={},
    json={
        "category_version": "v2",
        "description": "<p>Sản phẩm minh họa.</p>",
        "images": [
            {
                "uri": "anh-minh-hoa"
            }
        ],
        "include_prohibited_categories": False,
        "listing_platform": "TIKTOK_SHOP",
        "locale": "vi-VN",
        "origin_platform_product_type": "Minh họa",
        "origin_platform_vendor": "Thương hiệu minh họa",
        "origin_platform_tags": [
            "Minh họa"
        ],
        "origin_platform_category": {
            "id": "900000000000000001",
            "name": "Minh họa",
            "full_name": "Minh họa",
            "is_leaf": False,
            "is_root": False
        },
        "origin_platform_product_meta_data": {
            "attribute_value_list": [
                {
                    "name": "Minh họa",
                    "values": [
                        "Minh họa"
                    ]
                }
            ]
        },
        "product_title": "Áo thun cotton cổ tròn minh họa",
        "is_live_quick": False
    },
    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/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({"category_version":"v2","description":"<p>Sản phẩm minh họa.</p>","images":[{"uri":"anh-minh-hoa"}],"include_prohibited_categories":false,"listing_platform":"TIKTOK_SHOP","locale":"vi-VN","origin_platform_product_type":"Minh họa","origin_platform_vendor":"Thương hiệu minh họa","origin_platform_tags":["Minh họa"],"origin_platform_category":{"id":"900000000000000001","name":"Minh họa","full_name":"Minh họa","is_leaf":false,"is_root":false},"origin_platform_product_meta_data":{"attribute_value_list":[{"name":"Minh họa","values":["Minh họa"]}]},"product_title":"Áo thun cotton cổ tròn minh họa","is_live_quick":false}),
});
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/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, '{"category_version":"v2","description":"<p>Sản phẩm minh họa.</p>","images":[{"uri":"anh-minh-hoa"}],"include_prohibited_categories":false,"listing_platform":"TIKTOK_SHOP","locale":"vi-VN","origin_platform_product_type":"Minh họa","origin_platform_vendor":"Thương hiệu minh họa","origin_platform_tags":["Minh họa"],"origin_platform_category":{"id":"900000000000000001","name":"Minh họa","full_name":"Minh họa","is_leaf":false,"is_root":false},"origin_platform_product_meta_data":{"attribute_value_list":[{"name":"Minh họa","values":["Minh họa"]}]},"product_title":"Áo thun cotton cổ tròn minh họa","is_live_quick":false}');
$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)

NameTypeSampleDescription
codeint0Mã kết quả; 0 là thành công.
messagestringSuccessThông báo kết quả.
request_idstringYEU_CAU_MINH_HOAMã yêu cầu để tra cứu lỗi.
dataobjectDữ liệu.
categoriesobject[]Danh sách ngành hàng.
idstring900000000000000001Mã định danh.
is_leafboolfalseCó phải ngành hàng lá hay không.
levelint1Cấp trong cây ngành hàng.
namestringMinh họaTên.
permission_statusesstring[]Các trạng thái quyền đăng; giá trị liên quan: INVITE_ONLY, NON_MAIN_CATEGORY, AVAILABLE, PROHIBITED, BR, MX.
leaf_category_idstring900000000000000001Mã ngành hàng lá.

Response sample

{
  "code": 0,
  "message": "Success",
  "request_id": "YEU_CAU_MINH_HOA",
  "data": {
    "categories": [
      {
        "id": "900000000000000001",
        "is_leaf": false,
        "level": 1,
        "name": "Minh họa",
        "permission_statuses": [
          "INVITE_ONLY"
        ]
      }
    ],
    "leaf_category_id": "900000000000000001"
  }
}

Get started

  1. Sign up for Partner
  2. Enable a data type of the Sản phẩm group on the platform page
  3. Create an API key (tick the TikTok Shop channel)
  4. Call it as in the examples above