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

Lấy dữ liệu bài đăng của tài khoản TikTok — API TikTok Business

Get post data of a TikTok account · 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.

Get post data of a TikTok account

GET/business/video/list/Gọi qua 360: GET https://partner.quantri360.com/v1/tiktok_business/business/video/list/
Mô tả API

Danh sách bài đăng công khai (video, ảnh, văn bản) của tài khoản TikTok Business kèm số liệu tiếp cận và tương tác: lượt xem, thích, bình luận, chia sẻ, tiếp cận, thời gian xem, nguồn lượt xem, khán giả theo giới tính / quốc gia / thành phố. Gồm cả video "Chỉ hiển thị trong quảng cáo" (không nằm trên trang cá nhân nhưng xem công khai được qua quảng cáo).

  • Số tương tác tính trọn đời video (không giới hạn 60 ngày như số liệu cấp tài khoản); bài đăng quá 365 ngày ngừng cập nhật số liệu.
  • Số liệu chỉ có khi TikTok Analytics của tài khoản có (chủ tài khoản phải đăng ít nhất 1 video và bật Analytics trong app).
  • reach, full_video_watched_rate, total_time_watched, average_time_watched, impression_sources, audience_countries trống thường do video không có tương tác quá 7 ngày — chờ 24–48 giờ sau khi video có lượt xem / tương tác lại.
  • Bài vi phạm (vd bản quyền nhạc) bị TikTok lọc khỏi kết quả.
  • Thiếu quyền của một trường → TikTok báo lỗi; bỏ trường đó khỏi fields hoặc ủy quyền lại tài khoản với quyền tương ứng.

Request

Địa chỉ

GET https://partner.quantri360.com/v1/tiktok_business/business/video/list/

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_idquerystring7000000000000000001Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản.

Tham số request

TênVị tríKiểuBắt buộcMẫuMô tả
fieldsquerystring[]Không["item_id","create_time","caption","share_url","likes","comments","shares","video_views","reach"]Mảng JSON các trường cần lấy, PHẢI có "item_id". Không gửi = chỉ trả item_id. Mỗi trường cần một quyền (scope) của tài khoản: video.list — item_id, media_type, is_ad, thumbnail_url, share_url, embed_url, caption, video_duration, likes, comments, shares, favorites, create_time, reach, video_views; video.insights — total_time_watched, average_time_watched, full_video_watched_rate, new_followers, profile_views, website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks, address_clicks, video_view_retention, impression_sources, audience_genders, audience_countries, audience_cities, audience_types, engagement_likes.
filtersqueryobjectKhông{"video_ids":["7563000000000000001"]}Lọc theo bài, gửi dạng chuỗi JSON: video_ids (mảng id bài) và ad_post_only (true = chỉ bài đã cấp quyền tạo Spark Ads; chỉ có tác dụng khi có video_ids, mặc định false).
cursorqueryintKhôngCon trỏ trang = mốc thời gian Unix mili giây (UTC). Mặc định = hiện tại. Trang kế: truyền data.cursor của trang trước. Tự đặt mốc để lấy các bài đăng TRƯỚC thời điểm đó.
max_countqueryintKhông20Số bài mỗi trang. Mặc định 10, tối đa 20. TikTok có thể trả ít hơn dù has_more = true (bài bị lọc theo chính sách an toàn).

Phân trang

Lặp khi data.has_more = true, truyền cursor = data.cursor cho lần gọi kế; dừng khi has_more = false.

Ví dụ request

curl -s "https://partner.quantri360.com/v1/tiktok_business/business/video/list/?platform_shop_id=-000AbCdEfGhIjKlMnOpQrStUvWxYz012345&fields=%5B%22item_id%22%2C%22create_time%22%2C%22caption%22%2C%22share_url%22%2C%22likes%22%2C%22comments%22%2C%22shares%22%2C%22video_views%22%2C%22reach%22%5D&max_count=20" \
  -H "Authorization: Bearer $KEY"
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.get(
    "https://partner.quantri360.com/v1/tiktok_business/business/video/list/",
    params={
        "platform_shop_id": "-000AbCdEfGhIjKlMnOpQrStUvWxYz012345",
        "fields": [
            "item_id",
            "create_time",
            "caption",
            "share_url",
            "likes",
            "comments",
            "shares",
            "video_views",
            "reach"
        ],
        "max_count": 20
    },
    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_business/business/video/list/');
for (const [k, v] of Object.entries({"platform_shop_id":"-000AbCdEfGhIjKlMnOpQrStUvWxYz012345","fields":["item_id","create_time","caption","share_url","likes","comments","shares","video_views","reach"],"max_count":20})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'GET',
  headers: { Authorization: `Bearer ${KEY}` },
});
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_business/business/video/list/' . '?' . http_build_query(['platform_shop_id' => '-000AbCdEfGhIjKlMnOpQrStUvWxYz012345', 'fields' => '["item_id","create_time","caption","share_url","likes","comments","shares","video_views","reach"]', 'max_count' => 20]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

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

TênKiểuMẫuMô tả
codeint00 = thành công; khác 0 xem `message` (TikTok trả HTTP 200 kèm code lỗi).
messagestringOKThông điệp của TikTok.
request_idstring2021080307532501024502410704A7306FMã request TikTok — ghi lại khi cần tra lỗi.
dataobjectDữ liệu.
videosobject[]Bài đăng (chỉ có các trường đã yêu cầu ở `fields`).
item_idstring6995316737801538821Id bài. Quyền: video.list.
media_typestringVIDEO`VIDEO` = video · `PHOTO` = ảnh hoặc văn bản. Quyền: video.list.
is_adboolfalseBài đang được dùng trong quảng cáo (Spark Ads). Quyền: video.list.
create_timestring1628461703Thời điểm đăng, Unix giây (UTC). Quyền: video.list.
captionstringMô tả bài. Quyền: video.list.
thumbnail_urlstringẢnh thu nhỏ — link TẠM, hết hạn theo tham số `x-expires` (Unix giây). Quyền: video.list.
share_urlstringhttps://www.tiktok.com/@…/video/6994189750940863749Link chia sẻ. Quyền: video.list.
embed_urlstringhttps://www.tiktok.com/player/v1/…Link nhúng; bài để chế độ "Bạn bè" / "Chỉ mình tôi" không xem được qua link này. Quyền: video.list.
video_durationfloat20.001Độ dài video (giây). Trễ 24–48 giờ. Quyền: video.list.
likesint243Lượt thích. Trễ 24–48 giờ. Quyền: video.list.
commentsint10Lượt bình luận. Trễ 24–48 giờ. Quyền: video.list.
sharesint10Lượt chia sẻ (gồm chia sẻ ra ngoài và "Gửi cho bạn bè" trong app). Trễ 24–48 giờ. Quyền: video.list.
favoritesint10Lượt thêm vào yêu thích. Trễ 24–48 giờ. Quyền: video.list.
video_viewsint603Lượt xem — gồm cả tự nhiên lẫn trả phí. Trễ 24–48 giờ. Quyền: video.list.
reachint136Số người đã xem ít nhất một lần. Trễ 24–48 giờ. Quyền: video.list.
total_time_watchedfloat587.024Tổng thời gian xem (giây). Quyền: video.insights.
average_time_watchedfloat3.862Thời gian xem trung bình (giây). Quyền: video.insights.
full_video_watched_ratefloat0.0395Tỉ lệ xem hết video (0–1). Quyền: video.insights.
new_followersintNgười theo dõi mới từ bài. Quyền: video.insights.
profile_viewsintLượt xem trang cá nhân từ bài — chỉ tài khoản Advanced Access hoặc doanh nghiệp đã xác minh. Quyền: video.insights.
website_clicksintNhấn link website từ bài. Chỉ tài khoản doanh nghiệp đã xác minh (cùng điều kiện cho phone_number_clicks, lead_submissions, app_download_clicks, email_clicks, address_clicks). Quyền: video.insights.
impression_sourcesobject[]Nguồn lượt xem. Quyền: video.insights.
impression_sourcestringFor YouFor You · Follow · Personal Profile · Hashtag · Sound · Search…
percentagefloat0.8983Tỉ lệ (0–1).
audience_countriesobject[]Khán giả theo quốc gia (top). Quyền: video.insights.
countrystringVN
percentagefloat
audience_citiesobject[]Khán giả theo thành phố (top). Quyền: video.insights.
city_namestring
percentagefloat
audience_gendersobject[]Khán giả theo giới tính. Quyền: video.insights.
genderstringFemale
percentagefloat
audience_typesobject[]Người xem mới / quay lại, theo dõi / chưa theo dõi. Quyền: video.insights.
typestring
percentagefloat
video_view_retentionobject[]Tỉ lệ người còn xem theo giây. Quyền: video.insights.
secondstring
percentagefloat
engagement_likesobject[]Phân bố lượt thích theo giây của video. Quyền: video.insights.
secondstring
percentagefloat
cursorint1760893200000Con trỏ cho trang kế (Unix mili giây).
has_morebooltrueCòn trang kế.

Bắt đầu dùng

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