VI | EN
Nhắn Messenger
Dành cho developer

Tải ảnh sản phẩm lên TikTok Shop — API TikTok Shop

tiktok.product.202309.images.upload · gọi qua Quantri360 bằng một API key cho chính tài khoản / tài sản bạn đã kết nối và ủy quyền — 360 lo việc ký request và làm mới phiên đăng nhập bạn đã cấp.

tiktok.product.202309.images.upload

POST/product/202309/images/uploadGọi qua 360: POST https://partner.quantri360.com/v1/tiktok/product/202309/images/upload
Endpoint ghi — thay đổi dữ liệu trên TikTok Shop. Key phải được tạo với tick "Cho phép gọi API ghi", nếu không sẽ nhận 403 write_not_allowed. Mỗi lần gọi được ghi nhật ký.
Mô tả API

Tải một ảnh lên TikTok Shop để dùng làm ảnh sản phẩm, ảnh biến thể, ảnh trong mô tả, ảnh bảng size, ảnh chứng nhận — trả uri gắn vào sản phẩm và url để hiển thị.

  • Là API GHI — thay đổi dữ liệu thật trên TikTok Shop (tải tệp lên kho ảnh gian hàng); key cần quyền ghi.
  • Gửi multipart/form-data: trường tệp data + trường chữ use_case. 360 kiểm định dạng theo NỘI DUNG tệp (không theo tên / MIME) — chỉ nhận JPG / JPEG / PNG.
  • Ảnh MAIN_IMAGE và ATTRIBUTE_IMAGE có tỉ lệ ngoài khoảng 3:4 – 4:3 được sàn tự chuyển thành 1:1.
  • use_case không bắt buộc ở sàn — nên gửi rõ để sàn kiểm đúng kích thước theo mục đích ảnh.

Request

Địa chỉ

POST https://partner.quantri360.com/v1/tiktok/product/202309/images/upload

Xác thực & gian hàng

TênVị tríKiểuMẫuMô tả
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.

Tham số request

TênVị tríKiểuBắt buộcMẫuMô tả
databodyfileCóao-dam.jpgTệp ảnh JPG / JPEG / PNG (1 tệp), ≤ 10MB, 100–20.000 px; ảnh chính 300–4000 px; bảng size cạnh ngắn ≥ 1024 px.
use_casebodystringKhôngMAIN_IMAGEMAIN_IMAGE · ATTRIBUTE_IMAGE (ảnh biến thể) · DESCRIPTION_IMAGE · CERTIFICATION_IMAGE · SIZE_CHART_IMAGE · CUSTOMIZATION_IMAGE.

Ví dụ request

curl -s -X POST "https://partner.quantri360.com/v1/tiktok/product/202309/images/upload?platform_shop_id=7494000000000000000" \
  -H "Authorization: Bearer $KEY" \
  -F "use_case=MAIN_IMAGE" \
  -F "data=@ao-dam.jpg"
Python
import requests
from contextlib import ExitStack

KEY = "q360_live_..."
with ExitStack() as stack:
    files = [("data", stack.enter_context(open("ao-dam.jpg", "rb")))]
    r = requests.post("https://partner.quantri360.com/v1/tiktok/product/202309/images/upload", params={
        "platform_shop_id": "7494000000000000000"
    }, data={
        "use_case": "MAIN_IMAGE"
    }, files=files, headers={"Authorization": f"Bearer {KEY}"}, timeout=60)
    print(r.status_code, r.json())
Node.js
import { readFile } from 'node:fs/promises';
const KEY = 'q360_live_...';
const url = new URL('https://partner.quantri360.com/v1/tiktok/product/202309/images/upload?platform_shop_id=7494000000000000000');
const form = new FormData();
form.append("use_case", "MAIN_IMAGE");
form.append("data", new Blob([await readFile("ao-dam.jpg")]), "ao-dam.jpg");
const r = await fetch(url, { method: 'POST', headers: { Authorization: `Bearer ${KEY}` }, body: form });
console.log(r.status, await r.json());
PHP
<?php
$key = 'q360_live_...';
$ch = curl_init('https://partner.quantri360.com/v1/tiktok/product/202309/images/upload?platform_shop_id=7494000000000000000');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, ['use_case' => 'MAIN_IMAGE', 'data' => new CURLFile('ao-dam.jpg')]);
echo curl_exec($ch);
curl_close($ch);

Response

Tham số phản hồi (nguyên của TikTok Shop)

TênKiểuMẫuMô tả
codeint00 = thành công; khác 0 xem message (105001–105003 = token, 360 đã tự làm mới một lần).
messagestringSuccessThông điệp của TikTok.
request_idstring2025101900000000000000000000Mã request TikTok.
dataobjectDữ liệu.
uristringtos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbeGửi vào `main_images[].uri`, `sku_img.uri`, `size_chart.image.uri` khi tạo / sửa sản phẩm.
urlstringLink xem ảnh — dùng trong thẻ `<img>` của mô tả.
widthint720Sau khi sàn chỉnh tỉ lệ.
heightint720
use_casestringMAIN_IMAGE

Mẫu phản hồi

{
  "code": 0,
  "message": "Success",
  "request_id": "202203070749000101…",
  "data": {
    "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
    "url": "https://p-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
    "width": 720,
    "height": 720,
    "use_case": "MAIN_IMAGE"
  }
}

Bắt đầu dùng

  1. Đăng ký tài khoản Partner
  2. Mở loại dữ liệu thuộc nhóm Sản phẩm ở trang nền tảng
  3. Tạo API key (tick kênh TikTok Shop)
  4. Gọi theo ví dụ ở trên