VI | EN
Message us on Messenger
Developer resources

Diagnose and Optimize Product — TikTok Shop API

tiktok.product.202411.products.diagnose_optimize · 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.202411.products.diagnose_optimize

POST/product/202411/products/diagnose_optimizeVia 360: POST https://partner.quantri360.com/v1/tiktok/product/202411/products/diagnose_optimize
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ẩn đoán và tối ưu nội dung sản phẩm, trả chất lượng đăng bán, lỗi và gợi ý cải thiện; thông tin chất lượng đăng bán chỉ có ở Mỹ.

  • Gọi qua /v1/tiktok/product/202411/products/diagnose_optimize 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 để chẩn đoán và tối ưu.
  • 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/202411/products/diagnose_optimize

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
product_idbodystringNo900000000000000001Mã sản phẩm.
category_idbodystringYes900000000000000001Mã ngành hàng lá.
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.
brand_idbodystringNo900000000000000001Mã thương hiệu.
main_imagesbodyobject[]No[{"uri": "anh-minh-hoa"}]Ảnh chính sản phẩm; dùng URI ảnh được tải lên trước.
main_images[].uribodystringNoanh-minh-hoaURI ảnh đã tải lên.
titlebodystringNoÁ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ự.
product_attributesbodyobject[]No[{"id": "900000000000000001", "values": [{"id": "900000000000000001", "name": "Minh họa"}]}]Thuộc tính sản phẩm; điền đủ thuộc tính bắt buộc của ngành hàng.
product_attributes[].idbodystringNo900000000000000001Mã định danh.
product_attributes[].valuesbodyobject[]No[{"id": "900000000000000001", "name": "Minh họa"}]Các giá trị.
product_attributes[].values[].idbodystringNo900000000000000001Mã định danh.
product_attributes[].values[].namebodystringNoMinh họaTên; độ dài tối đa: 500.
size_chartbodyobjectNo{"template": {"id": "900000000000000001"}, "image": {"uri": "anh-minh-hoa"}}Bảng kích cỡ sản phẩm; có thể bắt buộc hoặc không được hỗ trợ tùy ngành hàng. Nếu ngành không hỗ trợ thì nội dung gửi sẽ bị bỏ qua.
size_chart.templatebodyobjectNo{"id": "900000000000000001"}Mẫu.
size_chart.template.idbodystringNo900000000000000001Mã định danh.
size_chart.imagebodyobjectNo{"uri": "anh-minh-hoa"}Ảnh.
size_chart.image.uribodystringNoanh-minh-hoaURI ảnh đã tải lên.
optimization_fieldsbodystring[]No["ALL"]Các trường cần tối ưu; giá trị liên quan: TITLE, DESCRIPTION, IMAGE, ALL, NONE.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok/product/202411/products/diagnose_optimize" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"900000000000000001","category_id":"900000000000000001","description":"<p>Sản phẩm minh họa.</p>","brand_id":"900000000000000001","main_images":[{"uri":"anh-minh-hoa"}],"title":"Áo thun cotton cổ tròn minh họa","product_attributes":[{"id":"900000000000000001","values":[{"id":"900000000000000001","name":"Minh họa"}]}],"size_chart":{"template":{"id":"900000000000000001"},"image":{"uri":"anh-minh-hoa"}},"optimization_fields":["ALL"]}'
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok/product/202411/products/diagnose_optimize",
    params={},
    json={
        "product_id": "900000000000000001",
        "category_id": "900000000000000001",
        "description": "<p>Sản phẩm minh họa.</p>",
        "brand_id": "900000000000000001",
        "main_images": [
            {
                "uri": "anh-minh-hoa"
            }
        ],
        "title": "Áo thun cotton cổ tròn minh họa",
        "product_attributes": [
            {
                "id": "900000000000000001",
                "values": [
                    {
                        "id": "900000000000000001",
                        "name": "Minh họa"
                    }
                ]
            }
        ],
        "size_chart": {
            "template": {
                "id": "900000000000000001"
            },
            "image": {
                "uri": "anh-minh-hoa"
            }
        },
        "optimization_fields": [
            "ALL"
        ]
    },
    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/202411/products/diagnose_optimize');
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_id":"900000000000000001","category_id":"900000000000000001","description":"<p>Sản phẩm minh họa.</p>","brand_id":"900000000000000001","main_images":[{"uri":"anh-minh-hoa"}],"title":"Áo thun cotton cổ tròn minh họa","product_attributes":[{"id":"900000000000000001","values":[{"id":"900000000000000001","name":"Minh họa"}]}],"size_chart":{"template":{"id":"900000000000000001"},"image":{"uri":"anh-minh-hoa"}},"optimization_fields":["ALL"]}),
});
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/202411/products/diagnose_optimize' . '?' . 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_id":"900000000000000001","category_id":"900000000000000001","description":"<p>Sản phẩm minh họa.</p>","brand_id":"900000000000000001","main_images":[{"uri":"anh-minh-hoa"}],"title":"Áo thun cotton cổ tròn minh họa","product_attributes":[{"id":"900000000000000001","values":[{"id":"900000000000000001","name":"Minh họa"}]}],"size_chart":{"template":{"id":"900000000000000001"},"image":{"uri":"anh-minh-hoa"}},"optimization_fields":["ALL"]}');
$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.
listing_qualityobjectChất lượng đăng bán.
current_tierstringPOORMức hiện tại; giá trị liên quan: POOR, FAIR, GOOD, US.
remaining_recommendationsint1Các đề xuất còn lại.
diagnosesobject[]Kết quả chẩn đoán.
fieldstringTITLETrường cần xử lý; giá trị liên quan: SIZE_CHART, TITLE, DESCRIPTION, IMAGE, ATTRIBUTE.
diagnosis_resultsobject[]Các kết quả chẩn đoán.
codestring0Mã kết quả; 0 là thành công.
how_to_solvestringMinh họaCách khắc phục.
quality_tierstringFAIRMức chất lượng; giá trị liên quan: FAIR, GOOD, US.
suggestionobjectGợi ý; giá trị liên quan: NONE.
seo_wordsobject[]Từ khóa SEO.
textstringMinh họaNội dung văn bản.
smart_textsobject[]Nội dung văn bản được tối ưu.
textstringMinh họaNội dung văn bản.
imagesobject[]Danh sách ảnh.
heightint800Chiều cao.
widthint800Chiều rộng.
uristringanh-minh-hoaURI ảnh đã tải lên.
urlstringĐịa chỉ hiển thị.
optimized_uristringanh-minh-hoaURI ảnh đã tối ưu.
optimized_urlstringĐịa chỉ ảnh đã tối ưu.

Response sample

{
  "code": 0,
  "message": "Success",
  "request_id": "YEU_CAU_MINH_HOA",
  "data": {
    "listing_quality": {
      "current_tier": "POOR",
      "remaining_recommendations": 1
    },
    "diagnoses": [
      {
        "field": "TITLE",
        "diagnosis_results": [
          {
            "code": 0,
            "how_to_solve": "Minh họa",
            "quality_tier": "FAIR"
          }
        ],
        "suggestion": {
          "seo_words": [
            {
              "text": "Minh họa"
            }
          ],
          "smart_texts": [
            {
              "text": "Minh họa"
            }
          ],
          "images": [
            {
              "height": 800,
              "width": 800,
              "uri": "anh-minh-hoa",
              "url": "",
              "optimized_uri": "anh-minh-hoa",
              "optimized_url": ""
            }
          ]
        }
      }
    ]
  }
}

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