Discover TTO creators
GET/tto/tcm/creator/discover/Gọi qua 360: GET https://partner.quantri360.com/v1/tiktok_business/tto/tcm/creator/discover/
Mô tả API
Tìm creator trên TikTok One Creator Marketplace theo quốc gia, nhãn, số người theo dõi, lượt xem, tỉ lệ tương tác, giá khởi điểm, chân dung người theo dõi, từ khóa… — bước đầu khi chọn KOC / creator để hợp tác.
- Gọi bằng TÀI KHOẢN QUẢNG CÁO đã nối (
platform_shop_id= id tài khoản quảng cáo), không phải tài khoản TikTok. Chưa biếttto_tcm_account_idcủa bạn → liên hệ 360. - Kết quả chỉ có thông tin cơ bản — xem chân dung khán giả, giá khởi điểm, nhãn ở /tto/tcm/creator/public/ theo
handle_name.
Request
Địa chỉ
GET https://partner.quantri360.com/v1/tiktok_business/tto/tcm/creator/discover/
Xác thực & gian hàng
| Tên | Vị trí | Kiểu | Mẫu | Mô tả |
|---|---|---|---|---|
| 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 | 7000000000000000001 | Tà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ên | Vị trí | Kiểu | Bắt buộc | Mẫu | Mô tả |
|---|---|---|---|---|---|
| tto_tcm_account_id | query | string | Có | 7300000000000000001 | Id tài khoản TikTok One Creator Marketplace mà tài khoản quảng cáo đã nối được quyền truy cập. Chưa biết id của bạn → liên hệ 360. |
| country_codes | query | string[] | Có | ["VN"] | Mảng JSON mã quốc gia 2 chữ cái của creator (vd ["VN"]). Gửi nhiều mã thì các mã phải cùng một nhóm: US riêng · châu Âu (DE, ES, FR, GB, IT) · nhóm còn lại (AE, AR, AU, BR, CA, CO, EG, ID, IL, JP, KR, MX, MY, PH, SA, SG, TH, TR, TW, VN). |
| state_provinces | query | string[] | Không | Chỉ khi country_codes = ["US"]: lọc theo bang của Mỹ. | |
| keyword_search | query | string | Không | thời trang | Từ khóa tìm creator, khớp gần đúng, tối đa 100 ký tự. |
| content_label_ids | query | string[] | Không | Mảng JSON id nhãn NỘI DUNG (tối đa 100) — lấy ở /tto/tcm/category/label/ với label_type = SEARCH, mục content_labels. | |
| industry_label_ids | query | string[] | Không | Mảng JSON id nhãn NGÀNH (tối đa 100) — lấy ở /tto/tcm/category/label/ với label_type = SEARCH, mục industry_labels. | |
| min_followers | query | int | Không | 10000 | Người theo dõi tối thiểu, mặc định 0. |
| max_followers | query | int | Không | Người theo dõi tối đa. | |
| min_avg_views | query | int | Không | Lượt xem trung bình tối thiểu, mặc định 0. | |
| max_avg_views | query | int | Không | Lượt xem trung bình tối đa. | |
| min_median_views | query | int | Không | Lượt xem trung vị tối thiểu (lượt xem "điển hình" của các video gần đây), mặc định 0. | |
| max_median_views | query | int | Không | Lượt xem trung vị tối đa. | |
| min_engagement_rate | query | float | Không | 0.02 | Tỉ lệ tương tác tối thiểu (0–1; = (bình luận + thích + chia sẻ) / lượt xem), mặc định 0. |
| max_engagement_rate | query | float | Không | Tỉ lệ tương tác tối đa (0–1). | |
| min_creator_price | query | float | Không | Giá khởi điểm tối thiểu, mặc định 0. | |
| max_creator_price | query | float | Không | Giá khởi điểm tối đa. | |
| creator_price_currency | query | string | Không | USD | Tiền tệ của hai bộ lọc giá — hiện chỉ USD (mặc định). |
| languages | query | string[] | Không | ["vi"] | Mảng JSON ngôn ngữ: ar · de · en · es · fr · id · it · ja · ko · ms · pt · th · tl · tr · vi. Không gửi = mọi ngôn ngữ. |
| follower_country_codes | query | string[] | Không | ["VN"] | Mảng JSON quốc gia của người theo dõi: AE · AU · BR · CA · DE · EG · ES · FR · GB · ID · IL · IT · JP · KR · MY · PH · RU · SA · SG · TH · TR · TW · US · VN. |
| follower_gender_ratio | query | string | Không | FEMALE_60 | Tỉ lệ giới tính người theo dõi: FEMALE_50 / FEMALE_60 / FEMALE_70 (nữ trên 50 / 60 / 70%) · MALE_50 / MALE_60 / MALE_70. |
| follower_age | query | string | Không | 25-34 | Nhóm tuổi chiếm đa số trong người theo dõi: 18-24 · 25-34 · 35-44 · 45-54 · 55+. |
| highly_responsive | query | bool | Không | true = chỉ creator thường trả lời lời mời nhanh. | |
| highly_active | query | bool | Không | true = chỉ creator hay vào TikTok One gần đây. | |
| high_potential_to_drive_sales | query | bool | Không | true = chỉ creator mạnh về ra đơn. | |
| high_quality_content_creator | query | bool | Không | true = chỉ creator nội dung chất lượng cao (không áp dụng ở châu Âu). | |
| sort_field | query | string | Không | FOLLOWERS | RELEVANCE (mặc định) · FOLLOWERS · MEDIAN_VIEWS · ENGAGEMENT_RATE. |
| sort_order | query | string | Không | DESC | DESC (mặc định) · ASC. |
| page | query | int | Không | 1 | Trang, từ 1. |
| page_size | query | int | Không | 50 | Số creator mỗi trang: 1–200, mặc định 24. |
Phân trang
Lặp page = 1, 2, … tới khi page ≥ data.page_info.total_page.
Ví dụ request
curl -s "https://partner.quantri360.com/v1/tiktok_business/tto/tcm/creator/discover/?platform_shop_id=7000000000000000001&tto_tcm_account_id=7300000000000000001&country_codes=%5B%22VN%22%5D&min_followers=10000&sort_field=FOLLOWERS&page_size=50" \ -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/tto/tcm/creator/discover/",
params={
"platform_shop_id": "7000000000000000001",
"tto_tcm_account_id": "7300000000000000001",
"country_codes": [
"VN"
],
"min_followers": 10000,
"sort_field": "FOLLOWERS",
"page_size": 50
},
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/tto/tcm/creator/discover/');
for (const [k, v] of Object.entries({"platform_shop_id":"7000000000000000001","tto_tcm_account_id":"7300000000000000001","country_codes":["VN"],"min_followers":10000,"sort_field":"FOLLOWERS","page_size":50})) 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/tto/tcm/creator/discover/' . '?' . http_build_query(['platform_shop_id' => '7000000000000000001', 'tto_tcm_account_id' => '7300000000000000001', 'country_codes' => '["VN"]', 'min_followers' => 10000, 'sort_field' => 'FOLLOWERS', 'page_size' => 50]); $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ên | Kiểu | Mẫu | Mô tả |
|---|---|---|---|
| code | int | 0 | 0 = thành công; khác 0 xem `message` (TikTok trả HTTP 200 kèm code lỗi; vd 40002 = tham số sai, message liệt kê giá trị hợp lệ). |
| message | string | OK | Thông điệp của TikTok. |
| request_id | string | 2021080307532501024502410704A7306F | Mã request TikTok — ghi lại khi cần tra lỗi. |
| data | object | Dữ liệu. | |
| creators | object[] | Creator tìm được. | |
| handle_name | string | creator_mau | Tên người dùng (không có @) — dùng cho /tto/tcm/creator/public/. |
| display_name | string | Creator mẫu | Tên hiển thị. |
| profile_image | string | Ảnh đại diện — link TẠM (hạn khoảng 7 ngày, mốc hết hạn ở `x-expires`); hết hạn thì gọi lại để lấy link mới. | |
| followers_count | int | 125000 | Người theo dõi. |
| following_count | int | 300 | Đang theo dõi. |
| likes_count | int | 2500000 | Tổng lượt thích. |
| videos_count | int | 420 | Số video công khai. |
| page_info | object | Phân trang. | |
| page | int | 1 | Trang hiện tại. |
| page_size | int | 100 | Số dòng mỗi trang. |
| total_number | int | 35 | Tổng số dòng. |
| total_page | int | 1 | Tổng số trang. |
Bắt đầu dùng
- Đăng ký tài khoản Partner
- Mở loại dữ liệu thuộc nhóm Tài khoản TikTok (Organic API) ở trang nền tảng
- Tạo API key (tick kênh TikTok Business)
- Gọi theo ví dụ ở trên