Developer API — TikTok Shop Affiliate
Tạo & quản lý API key, gọi API tạo link affiliate và lấy đơn hàng từ hệ thống của bạn.
Tài liệu cập nhật: 12/07/2026
Mới (12/07/2026) — Hoa hồng thưởng (bonus commission):
API đơn hàng
GET /partner/tiktok/affiliate/orders và postback bổ sung các field
commission_rate (rate tổng = chuẩn + thưởng + QC shop),
commission_bonus_rate, est_bonus_commission,
actual_bonus_commission, shop_ads_commission_rate,
est_shop_ads_commission, actual_shop_ads_commission.
Lưu ý: est_commission trước giờ đã gồm thưởng — các field mới giúp tách chi tiết.
Đơn cũ đã được backfill đầy đủ. Xem bảng field ở mục Hướng dẫn API.
API Keys của bạn
Key dùng ở header X-Riohub-Api-Key. Mỗi key chỉ thao tác được trên creator TikTok mà chính tài khoản này đã kết nối.
Lưu lại ngay! Key chỉ hiển thị một lần. Sau khi đóng bạn sẽ không xem lại được.
| Tên | Prefix | Trạng thái | Dùng lần cuối | Tạo lúc | |
|---|---|---|---|---|---|
| Đang tải... | |||||
Hướng dẫn sử dụng
Base URL:
1. Xác thực
Mọi request gửi kèm header API key:
X-Riohub-Api-Key: rhk_xxxxxxxxxxxxxxxxxxxxxxxx
Lỗi xác thực trả về 401. Gọi creator không thuộc tài khoản của bạn trả về 403.
Giới hạn tần suất: mỗi key tối đa 300 request/phút và 100.000 request/ngày. Vượt giới hạn trả về 429 kèm header Retry-After.
POST
Tạo link affiliate
Tạo link tiếp thị cho một sản phẩm, gắn nhãn theo dõi (sub_id).
Body (JSON):
| Field | Bắt buộc | Mô tả |
|---|---|---|
creator_username | Có | Username TikTok creator (đã kết nối ở tài khoản của bạn). |
product_url | Có* | URL sản phẩm (link rút gọn vt.tiktok.com, link trực tiếp, hoặc product_id). *hoặc product_id. |
sub_id | Có | Nhãn theo dõi, 1–128 ký tự [A-Za-z0-9_-]. |
type | Không | Mặc định PRODUCT. |
Ví dụ (cURL):
Phản hồi 200:
{
"affiliate_link": "https://vt.tiktok.com/XXXXXX/",
"sub_id": "fb-ads-01",
"product_id": "1729...",
"creator_username": "your_creator"
}
Sản phẩm không có hoa hồng / chưa được duyệt → 422 code product_not_promotable.
POST
Tạo deep link (mở app) — theo lô
Tạo link cho nhiều sản phẩm cùng lúc (tối đa 50). Mỗi sản phẩm trả về 3 link: sharing_link (web), deep_link (mở thẳng app TikTok), one_link (AppsFlyer — tự chuyển store nếu chưa cài app).
Lưu ý attribution: link ở endpoint này KHÔNG mang
sub_id — không gắn công qua sub_id như POST /links. Dùng khi cần link mở app để chia sẻ; nếu cần theo dõi hoa hồng theo sub_id, dùng POST /links.Body (JSON):
| Field | Bắt buộc | Mô tả |
|---|---|---|
creator_username | Có | Username TikTok creator (đã kết nối ở tài khoản của bạn). |
product_ids | Có* | Mảng product_id (tối đa 50). *hoặc product_id dạng chuỗi phân tách dấu phẩy. |
campaign_id | Không | Id chiến dịch affiliate (nếu sản phẩm thuộc campaign). |
link_type | Không | Rỗng = URL TikTok Shop; TOKO = URL Tokopedia. |
Ví dụ (cURL):
Phản hồi 200:
{
"creator_username": "your_creator",
"links": [
{
"material_id": "1729...",
"sharing_link": "https://www.tiktok.com/view/product/1729...?...",
"deep_link": "snssdk1180://ec/pdp?...",
"one_link": "https://snssdk1180.onelink.me/BAuo?..."
}
],
"failed": [
{ "material_id": "1730...", "fail_reason": "Product was sold out" }
]
}
Sản phẩm lỗi (hết hàng / không đủ điều kiện) nằm trong failed[]. Không tạo được link nào → 502.
GET
Lấy thông tin sản phẩm affiliate
API tạo link không kèm thông tin sản phẩm — endpoint này trả tên/ảnh/giá/hoa hồng theo product_id (trong phạm vi quyền của creator). RioHub cache 24h: id đã có trả ngay, id mới/quá hạn mới gọi TikTok.
Query params:
| Param | Bắt buộc | Mô tả |
|---|---|---|
creator_username | Có | Username TikTok creator (đã kết nối). |
product_id | Có | 1 id hoặc danh sách phân tách dấu phẩy (tối đa 100). |
Phản hồi 200:
{
"creator_username": "your_creator",
"requested": 1,
"found": 1,
"products": [
{
"id": "1732152247872817576",
"title": "Bộ Cạo Râu 72 Lưỡi + 2 cán Dao Làm và Hộp Nhựa",
"main_image_url": "https://p16-oec-sg.ibyteimg.com/.../image",
"detail_link": "https://shop.tiktok.com/view/product/1732152247872817576?region=VN",
"sale_region": "VN",
"has_inventory": true,
"units_sold": 62030,
"commission": { "rate": 600, "amount": "3299.94 - 5099.94", "currency": "VND" },
"shop_ads_commission": { "rate": 200 },
"sales_price": { "minimum_amount": "", "maximum_amount": "", "currency": "" },
"original_price": { "minimum_amount": "89000", "maximum_amount": "139000", "currency": "VND" },
"shop": { "name": "Nấmm Decor" },
"category_chains": [
{ "id": "601450", "is_leaf": false, "local_name": "Chăm sóc sắc đẹp & cá nhân", "parent_id": "0" },
{ "id": "700791", "is_leaf": true, "local_name": "Dao cạo", "parent_id": "849288" }
]
}
],
"not_found": []
}
Giải thích field trong products[] (passthrough TikTok V202509):
| Field | Type | Mô tả |
|---|---|---|
id | string | Mã sản phẩm (int64 dạng chuỗi). |
title | string | Tên sản phẩm. |
main_image_url | string | Ảnh chính. |
detail_link | string | Link trang sản phẩm trên TikTok Shop. |
sale_region | string | Khu vực bán (vd VN). |
has_inventory | bool | true = còn hàng. |
units_sold | number | Tổng số đã bán (lũy kế). |
commission.rate | number | Tỷ lệ hoa hồng raw, ÷100 = % (vd 600 = 6%). |
commission.amount | string | Hoa hồng ước tính — có thể là 1 khoảng (vd "3299.94 - 5099.94") khi nhiều SKU giá khác nhau. |
shop_ads_commission.rate | number | Tỷ lệ HH cho đơn Shop Ads (raw, ÷100 = %). |
sales_price.{min,max}_amount | string | Giá bán hiện tại (khoảng). Có thể rỗng "" nếu TikTok không trả → dùng original_price. |
original_price.{min,max}_amount | string | Giá gốc (khoảng). |
shop.name | string | Tên shop. |
category_chains[] | array | Cây ngành hàng (gốc → lá); phần tử is_leaf:true là ngành lá. |
products[] giữ nguyên object từ TikTok. Id không lấy được (không đủ điều kiện / không tồn tại) nằm trong not_found. Dữ liệu cache 24h.
GET
Lấy đơn hàng
Truy vấn đơn affiliate đã đồng bộ theo creator và khoảng thời gian.
Query params:
| Param | Bắt buộc | Mô tả |
|---|---|---|
creator_username | Có | Creator thuộc tài khoản của bạn. |
time_start | Không | Unix giây hoặc Y-m-d H:i:s — lọc theo ngày tạo (từ). |
time_end | Không | Unix giây hoặc Y-m-d H:i:s — lọc theo ngày tạo (đến, không bao gồm). |
update_time_start | Không | Unix giây — lọc theo thời điểm đơn được cập nhật (từ). Dùng kéo đơn vừa đổi settlement/refund (sync tăng dần). |
update_time_end | Không | Unix giây — lọc theo ngày cập nhật (đến, không bao gồm). |
order_id | Không | 1 mã đơn hoặc danh sách ngăn cách dấu phẩy (tối đa 200) — verify postback / gom 1 đợt. Nên đặt page_size đủ lớn. |
product_id | Không | 1 hoặc list (tối đa 100) — lọc đơn theo sản phẩm. |
status | Không | 1 hoặc list: 1=pending · 2=settled · 3=cancelled/refunded. |
settlement_status | Không | 1 hoặc list (passthrough TikTok, vd SETTLED,AWAITING PAYMENT). |
content_type | Không | 1 hoặc list: VIDEO / LIVE / SHOWCASE / LINKSHARE (passthrough). |
fully_refunded | Không | 0 | 1 — lọc đơn hoàn toàn bộ. |
sub_id | Không | Khớp chuỗi con trên tag (vd abc khớp abc-def--). |
sub1…sub4 | Không | Khớp chính xác từng vị trí của tag (tag tách bằng -); kết hợp nhiều sub = AND. |
page / page_size | Không | Phân trang (mặc định 1 / 50, tối đa 200). |
Ví dụ (cURL):
Phản hồi 200:
{
"creator_username": "your_creator",
"page": 1,
"page_size": 50,
"total": 12,
"orders": [
{
"order_id": "579012345678901234",
"sku_id": "173098765432109876",
"product_id": "172900112233445566",
"product_name": "Áo thun cotton unisex",
"price": "199000.00",
"quantity": 1,
"refunded_quantity": 0,
"returned_quantity": 0,
"fully_refunded": 0,
"creator_username": "your_creator",
"shop_name": "Rio Official Store",
"currency": "VND",
"settlement_status": "AWAITING PAYMENT",
"status": 1,
"tt_order_status": 100,
"content_type": "LINKSHARE",
"content_id": "744011223344556677",
"sub_id": "u27765-m1780903356",
"sub1": "u27765",
"sub2": "m1780903356",
"sub3": "",
"sub4": "",
"commission_model": "Fixed commission",
"standard_commission_rate": "800",
"commission_rate": 2800,
"commission_bonus_rate": 2000,
"shop_ads_commission_rate": 0,
"commission_gmv": "199000.00",
"est_standard_commission": "15920.00",
"est_bonus_commission": "39800.00",
"est_shop_ads_commission": null,
"est_commission": "55720.00",
"actual_commission": null,
"actual_bonus_commission": null,
"actual_shop_ads_commission": null,
"create_time": 1749513600,
"update_time": 1749520800,
"time_created": "2026-06-10 08:00:00",
"time_delivered": null,
"payment_status": "AWAITING PAYMENT"
}
]
}
Chi tiết field trong orders[]:
Kiểu JSON: cột số nguyên trả về number; cột tiền/decimal & ID lớn trả về string (giữ nguyên độ chính xác).
| Field | Type | Giá trị / Enum | Mô tả |
|---|---|---|---|
order_id | string | — | Mã đơn TikTok (int64 dạng chuỗi). |
sku_id | string | — | Mã SKU. Một đơn nhiều SKU = nhiều dòng (mỗi dòng 1 SKU). |
product_id | string | — | Mã sản phẩm. |
product_name | string | — | Tên sản phẩm. |
price | string | — | Đơn giá GMV (decimal dạng chuỗi). |
quantity | number | — | Số lượng đặt. |
refunded_quantity | number | — | SL đã hoàn tiền. |
returned_quantity | number | — | SL đã trả hàng. |
fully_refunded | number | 0 · 1 | 1 = đơn đã hoàn toàn bộ số lượng. |
currency | string | VND, USD, … | Mã tiền tệ ISO-4217. |
settlement_status | string | AWAITING PAYMENT · To-SETTLE · SETTLED · REFUNDED | Trạng thái gốc từ TikTok (passthrough). TikTok có thể bổ sung trạng thái khác. |
status | number | 1 · 2 · 3 | Trạng thái chuẩn hoá: 1=chờ/pending · 2=đã đối soát/settled · 3=huỷ/hoàn. |
tt_order_status | number | 100 · 103 · 104 | Tương ứng status: 100=pending · 103=settled · 104=cancelled/refunded. |
content_type | string | VIDEO · LIVE · SHOWCASE · LINKSHARE · … | Nguồn nội dung phát sinh đơn (passthrough). LINKSHARE = từ link chia sẻ. |
content_id | string | — | ID video / live / showcase nguồn (rỗng nếu không có). |
sub_id | string | — | Nhãn theo dõi bạn gắn lúc tạo link (= tag đầy đủ). |
sub1…sub4 | string · null | — | Tag tách theo - thành 4 vị trí (vd u27765-m178... → sub1=u27765, sub2=m178...). Vị trí trống = ""; đơn không có tag = null. Dùng lọc qua param sub1…sub4. |
commission_model | string | passthrough TikTok | Mô hình hoa hồng, vd Fixed commission. Giá trị do TikTok định nghĩa. |
standard_commission_rate | number | raw, ÷100 = % | Tỷ lệ HH chuẩn dạng raw int, vd 1000 = 10%. |
commission_rate | number · null | raw, ÷100 = % | Tỷ lệ HH TỔNG (chuẩn + thưởng + QC shop), vd 2800 = 28%. null với đơn cũ chưa backfill. |
commission_bonus_rate | number · null | raw, ÷100 = % | Tỷ lệ HH thưởng (bonus), vd 2000 = 20%. |
shop_ads_commission_rate | number · null | raw, ÷100 = % | Tỷ lệ HH quảng cáo shop. |
commission_gmv | string | — | GMV dùng để tính hoa hồng (decimal chuỗi). |
est_standard_commission | string | — | Phần hoa hồng chuẩn ước tính. |
est_bonus_commission | string · null | — | Phần hoa hồng thưởng ước tính. |
est_shop_ads_commission | string · null | — | Phần hoa hồng quảng cáo shop ước tính. |
est_commission | string | — | Hoa hồng ròng ước tính của creator (gồm cả đơn pending, ĐÃ GỒM thưởng + QC shop). |
actual_commission | string · null | null khi chưa đối soát | Hoa hồng thực nhận sau đối soát. |
actual_bonus_commission | string · null | null khi chưa đối soát | Phần HH thưởng thực nhận. |
actual_shop_ads_commission | string · null | null khi chưa đối soát | Phần HH quảng cáo shop thực nhận. |
create_time | number | unix giây | Thời điểm tạo đơn. |
update_time | number | unix giây | Lần cập nhật cuối. |
time_created | string | Y-m-d H:i:s | create_time dạng ngày giờ. |
time_delivered | string · null | Y-m-d H:i:s | Thời điểm giao hàng (null nếu chưa giao). |
payment_status | string | như settlement_status | Trạng thái thanh toán gốc từ TikTok. |
GET
Lấy danh sách link đã tạo
Liệt kê các link affiliate bạn đã tạo qua API (nguồn api) cho creator, kèm số đơn & hoa hồng tổng hợp theo sub_id.
Query params:
| Param | Bắt buộc | Mô tả |
|---|---|---|
creator_username | Có | Creator thuộc tài khoản của bạn. |
sub_id | Không | Lọc theo nhãn theo dõi. |
channel | Không | Lọc theo nhãn nguồn traffic. |
time_start | Không | Unix giây hoặc Y-m-d H:i:s (lọc từ ngày tạo). |
time_end | Không | Unix giây hoặc Y-m-d H:i:s (lọc đến, không bao gồm). |
page / page_size | Không | Phân trang (mặc định 1 / 50, tối đa 200). |
Ví dụ (cURL):
Phản hồi 200:
{
"creator_username": "your_creator",
"page": 1,
"page_size": 50,
"total": 8,
"links": [
{
"id": 42,
"material_type": "PRODUCT",
"material_id": "1729...",
"affiliate_link": "https://vt.tiktok.com/XXXXXX/",
"channel": "riokupon",
"sub_id": "fb-ads-01",
"order_count": 3,
"est_commission": "37.50",
"settled_commission": "12.50",
"currency": "VND",
"created_at": "..."
}
]
}
Chi tiết field trong links[]:
| Field | Type | Giá trị / Enum | Mô tả |
|---|---|---|---|
id | number | — | ID nội bộ của link trên RioHub. |
material_type | string | PRODUCT · CAMPAIGN · SHOWCASE | Loại đối tượng được gắn link. |
material_id | string | — | ID sản phẩm/chiến dịch/showcase. |
affiliate_link | string | — | Link affiliate đã tạo. |
channel | string | mặc định riokupon | Nhãn nguồn traffic bạn gắn lúc tạo link. |
sub_id | string | — | Nhãn theo dõi (= tag). |
order_count | number | — | Số đơn tổng hợp theo sub_id. |
est_commission | string | — | Hoa hồng ước tính (gồm pending). |
settled_commission | string | — | Hoa hồng đã đối soát. |
currency | string | VND, … | Mã tiền tệ ISO-4217. |
created_at | string | Y-m-d H:i:s | Thời điểm tạo link. |
Code mẫu
Sao chép & thay YOUR_API_KEY bằng key của bạn. creator_username tự điền creator đã kết nối của bạn (nếu có).
# 1) Tạo link affiliate
curl -X POST '__BASE__/partner/tiktok/affiliate/links' \
-H 'X-Riohub-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"creator_username":"__CREATOR__","product_url":"https://vt.tiktok.com/XXXXXX/","sub_id":"fb-ads-01"}'
# 1b) Tạo deep link (mở app) theo lô — trả sharing_link + deep_link + one_link, KHÔNG có sub_id
curl -X POST '__BASE__/partner/tiktok/affiliate/general-links' \
-H 'X-Riohub-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"creator_username":"__CREATOR__","product_ids":["1729...","1730..."]}'
# 2) Lấy danh sách link đã tạo
curl '__BASE__/partner/tiktok/affiliate/links?creator_username=__CREATOR__&page=1&page_size=50' \
-H 'X-Riohub-Api-Key: YOUR_API_KEY'
# 3) Lấy đơn hàng (lọc theo order_id / settlement_status — đều tuỳ chọn)
curl '__BASE__/partner/tiktok/affiliate/orders?creator_username=__CREATOR__&order_id=579,580&settlement_status=SETTLED&page=1&page_size=50' \
-H 'X-Riohub-Api-Key: YOUR_API_KEY'
# 4) Lấy thông tin sản phẩm affiliate
curl '__BASE__/partner/tiktok/affiliate/products?creator_username=__CREATOR__&product_id=1729...,1730...' \
-H 'X-Riohub-Api-Key: YOUR_API_KEY'
<?php
$base = '__BASE__';
$key = 'YOUR_API_KEY';
// 1) Tạo link affiliate
$ch = curl_init("$base/partner/tiktok/affiliate/links");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["X-Riohub-Api-Key: $key", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode([
"creator_username" => "__CREATOR__",
"product_url" => "https://vt.tiktok.com/XXXXXX/",
"sub_id" => "fb-ads-01",
]),
]);
$link = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $link["affiliate_link"] ?? "error";
// 2) Lấy danh sách link đã tạo
$q = http_build_query(["creator_username" => "__CREATOR__", "page" => 1, "page_size" => 50]);
$ch = curl_init("$base/partner/tiktok/affiliate/links?$q");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["X-Riohub-Api-Key: $key"],
]);
$links = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($links["links"] ?? []);
// 3) Lấy đơn hàng (tất cả filter đều tuỳ chọn)
$q = http_build_query([
"creator_username" => "__CREATOR__",
"order_id" => "584428814795835227,583754926547633737", // 1 hoặc list (verify postback)
"status" => "1,2", // 1=pending 2=settled 3=cancelled
"settlement_status" => "SETTLED",
"update_time_start" => 1778000000, // chỉ đơn cập nhật sau mốc này (sync tăng dần)
"sub1" => "u27765", // khớp vị trí 1 của tag
"page" => 1, "page_size" => 200,
]);
$ch = curl_init("$base/partner/tiktok/affiliate/orders?$q");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["X-Riohub-Api-Key: $key"],
]);
$orders = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($orders["orders"] ?? []);
// 4) Lấy thông tin sản phẩm affiliate (1 hoặc nhiều product_id)
$q = http_build_query(["creator_username" => "__CREATOR__", "product_id" => "1732152247872817576"]);
$ch = curl_init("$base/partner/tiktok/affiliate/products?$q");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["X-Riohub-Api-Key: $key"],
]);
$products = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($products["products"] ?? []);
const BASE = '__BASE__';
const KEY = 'YOUR_API_KEY';
// 1) Tạo link affiliate
const link = await fetch(`${BASE}/partner/tiktok/affiliate/links`, {
method: 'POST',
headers: { 'X-Riohub-Api-Key': KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({
creator_username: '__CREATOR__',
product_url: 'https://vt.tiktok.com/XXXXXX/',
sub_id: 'fb-ads-01',
}),
}).then(r => r.json());
console.log(link.affiliate_link);
// 2) Lấy danh sách link đã tạo
const lq = new URLSearchParams({ creator_username: '__CREATOR__', page: '1', page_size: '50' });
const links = await fetch(`${BASE}/partner/tiktok/affiliate/links?${lq}`, {
headers: { 'X-Riohub-Api-Key': KEY },
}).then(r => r.json());
console.log(links.total, links.links);
// 3) Lấy đơn hàng (tất cả filter đều tuỳ chọn)
const q = new URLSearchParams({
creator_username: '__CREATOR__',
order_id: '584428814795835227,583754926547633737', // 1 hoặc list (verify postback)
status: '1,2', // 1=pending 2=settled 3=cancelled
settlement_status: 'SETTLED',
update_time_start: '1778000000', // chỉ đơn cập nhật sau mốc này (sync tăng dần)
sub1: 'u27765', // khớp vị trí 1 của tag
page: '1', page_size: '200',
});
const orders = await fetch(`${BASE}/partner/tiktok/affiliate/orders?${q}`, {
headers: { 'X-Riohub-Api-Key': KEY },
}).then(r => r.json());
console.log(orders.total, orders.orders);
// 4) Lấy thông tin sản phẩm affiliate (1 hoặc nhiều product_id)
const pq = new URLSearchParams({ creator_username: '__CREATOR__', product_id: '1732152247872817576' });
const products = await fetch(`${BASE}/partner/tiktok/affiliate/products?${pq}`, {
headers: { 'X-Riohub-Api-Key': KEY },
}).then(r => r.json());
console.log(products.found, products.products);
import requests
BASE = "__BASE__"
KEY = "YOUR_API_KEY"
H = {"X-Riohub-Api-Key": KEY}
# 1) Tạo link affiliate
link = requests.post(f"{BASE}/partner/tiktok/affiliate/links", headers=H, json={
"creator_username": "__CREATOR__",
"product_url": "https://vt.tiktok.com/XXXXXX/",
"sub_id": "fb-ads-01",
}).json()
print(link.get("affiliate_link"))
# 2) Lấy danh sách link đã tạo
links = requests.get(f"{BASE}/partner/tiktok/affiliate/links", headers=H, params={
"creator_username": "__CREATOR__", "page": 1, "page_size": 50,
}).json()
print(links.get("total"), links.get("links"))
# 3) Lấy đơn hàng (tất cả filter đều tuỳ chọn)
orders = requests.get(f"{BASE}/partner/tiktok/affiliate/orders", headers=H, params={
"creator_username": "__CREATOR__",
"order_id": "584428814795835227,583754926547633737", # 1 hoặc list (verify postback)
"status": "1,2", # 1=pending 2=settled 3=cancelled
"settlement_status": "SETTLED",
"update_time_start": 1778000000, # chỉ đơn cập nhật sau mốc này (sync tăng dần)
"sub1": "u27765", # khớp vị trí 1 của tag
"page": 1, "page_size": 200,
}).json()
print(orders.get("total"), orders.get("orders"))
# 4) Lấy thông tin sản phẩm affiliate (1 hoặc nhiều product_id)
products = requests.get(f"{BASE}/partner/tiktok/affiliate/products", headers=H, params={
"creator_username": "__CREATOR__", "product_id": "1732152247872817576",
}).json()
print(products.get("found"), products.get("products"))
Tích hợp bằng AI
Sao chép cả khối Markdown dưới đây, dán cho AI (ChatGPT/Claude/Copilot…) kèm yêu cầu của bạn — AI sẽ tự viết code tích hợp. Không chứa key thật: giữ YOUR_API_KEY và thay bằng key của bạn lúc chạy.
# RioHub × TikTok Shop Affiliate API — Spec tích hợp
> Tài liệu cập nhật: 12/07/2026
Bạn là kỹ sư tích hợp. Hãy viết code gọi các API dưới đây theo ngôn ngữ tôi chỉ định.
Đọc API key từ biến môi trường (KHÔNG hardcode, KHÔNG để lộ key); thay `YOUR_API_KEY` bằng key thật khi chạy.
## Base URL
`__BASE__`
## Xác thực
Mọi request kèm header: `X-Riohub-Api-Key: YOUR_API_KEY`
- `401` key sai/thiếu · `403` creator không thuộc tài khoản của key · `404` creator chưa kết nối
- `429` vượt giới hạn (300 req/phút, 100.000 req/ngày) — đọc header `Retry-After` rồi thử lại.
## 1) POST `/partner/tiktok/affiliate/links` — Tạo link affiliate
Body JSON:
- `creator_username` (bắt buộc): username creator đã kết nối, vd `__CREATOR__`
- `product_url` (bắt buộc*): URL sản phẩm (link rút gọn vt.tiktok.com / link trực tiếp) hoặc `product_id`. (*hoặc gửi `product_id`)
- `sub_id` (bắt buộc): nhãn theo dõi, 1–128 ký tự `[A-Za-z0-9_-]`. Có thể gói tối đa 4 sub theo vị trí, phân tách bằng `-` (vd `abc-def--` → sub1=abc, sub2=def, sub3/4=rỗng); RioHub tự tách thành `sub1..sub4` để lọc đơn theo từng vị trí. Lưu ý: giá trị mỗi sub KHÔNG được chứa `-` (đó là dấu phân tách).
- `type` (tuỳ chọn): mặc định `PRODUCT`
- `channel` (tuỳ chọn): nhãn nguồn traffic, mặc định `riokupon`. 1–64 ký tự `[A-Za-z0-9_-]`
Request:
{ "creator_username": "__CREATOR__", "product_url": "https://vt.tiktok.com/XXXXXX/", "sub_id": "fb-ads-01" }
Response 200:
{ "affiliate_link": "https://vt.tiktok.com/XXXXXX/", "sub_id": "fb-ads-01", "product_id": "1729...", "creator_username": "__CREATOR__" }
Lỗi 422 `product_not_promotable`: sản phẩm không có hoa hồng hoặc chưa được shop duyệt.
## 1b) POST `/partner/tiktok/affiliate/general-links` — Tạo deep link (mở app), theo lô
Tạo link cho nhiều sản phẩm cùng lúc (tối đa 50). Mỗi sản phẩm trả 3 link: `sharing_link` (web), `deep_link` (mở app TikTok), `one_link` (AppsFlyer, tự chuyển store nếu chưa cài app).
LƯU Ý: link này KHÔNG mang `sub_id` — không gắn công theo sub_id như `/links`. Dùng khi cần link mở app để chia sẻ; cần theo dõi hoa hồng theo sub_id thì dùng `/links`.
Body JSON:
- `creator_username` (bắt buộc): username creator đã kết nối, vd `__CREATOR__`
- `product_ids` (bắt buộc*): mảng product_id, tối đa 50. (*hoặc `product_id` dạng chuỗi phân tách dấu phẩy)
- `campaign_id` (tuỳ chọn): id chiến dịch affiliate nếu sản phẩm thuộc campaign
- `link_type` (tuỳ chọn): rỗng = URL TikTok Shop; `TOKO` = URL Tokopedia
Request:
{ "creator_username": "__CREATOR__", "product_ids": ["1729...", "1730..."] }
Response 200:
{ "creator_username": "__CREATOR__",
"links": [ { "material_id": "1729...", "sharing_link": "https://www.tiktok.com/view/product/1729...?...",
"deep_link": "snssdk1180://ec/pdp?...", "one_link": "https://snssdk1180.onelink.me/BAuo?..." } ],
"failed": [ { "material_id": "1730...", "fail_reason": "Product was sold out" } ] }
Không tạo được link nào → `502`.
## 2) GET `/partner/tiktok/affiliate/links` — Lấy danh sách link đã tạo
Liệt kê link đã tạo qua API (source=`api`) cho creator, kèm số đơn & hoa hồng theo `sub_id`.
Query params:
- `creator_username` (bắt buộc)
- `sub_id` (tuỳ chọn): khớp **chuỗi con** trên tag; `channel` (tuỳ chọn): lọc nguồn traffic
- `sub1`, `sub2`, `sub3`, `sub4` (tuỳ chọn): lọc khớp chính xác theo từng vị trí của tag
- `time_start`, `time_end` (tuỳ chọn): unix giây hoặc `Y-m-d H:i:s` (lọc theo ngày tạo, end không bao gồm)
- `page` (mặc định 1), `page_size` (mặc định 50, tối đa 200)
Response 200:
{ "creator_username": "__CREATOR__", "page": 1, "page_size": 50, "total": 8,
"links": [ { "id": 42, "material_id": "1729...", "affiliate_link": "https://vt.tiktok.com/XXXXXX/",
"channel": "riokupon", "sub_id": "fb-ads-01", "order_count": 3, "est_commission": "37.50",
"settled_commission": "12.50", "currency": "VND", "created_at": "..." } ] }
## 3) GET `/partner/tiktok/affiliate/orders` — Lấy đơn hàng
Query params:
- `creator_username` (bắt buộc)
- `time_start`, `time_end` (tuỳ chọn): unix giây hoặc `Y-m-d H:i:s` (lọc từ / đến, end không bao gồm)
- `sub_id` (tuỳ chọn): khớp **chuỗi con** trên tag đầy đủ (vd `abc` khớp `abc-def---`)
- `sub1`, `sub2`, `sub3`, `sub4` (tuỳ chọn): lọc **khớp chính xác** theo từng vị trí của tag (tag tách bằng `-`); kết hợp nhiều sub = AND
- `order_id` (tuỳ chọn): 1 mã đơn hoặc danh sách phân tách bằng dấu phẩy (tối đa 200) — dùng để verify postback hoặc gom 1 đợt (vd hold postback ~5p rồi lấy 1 loạt). Nên đặt `page_size` đủ lớn.
- `settlement_status` (tuỳ chọn): 1 giá trị hoặc danh sách phân tách bằng dấu phẩy (vd `SETTLED,AWAITING PAYMENT`)
- `status` (tuỳ chọn): trạng thái chuẩn hoá, 1 giá trị hoặc list (`1`=pending · `2`=settled · `3`=cancelled/refunded)
- `update_time_start`, `update_time_end` (tuỳ chọn): unix giây, lọc theo thời điểm đơn **được cập nhật** (end không bao gồm) — dùng để kéo đơn vừa đổi settlement/refund (sync tăng dần)
- `product_id` (tuỳ chọn): 1 hoặc list (tối đa 100) — lọc đơn theo sản phẩm
- `content_type` (tuỳ chọn): 1 hoặc list, theo nguồn nội dung (VIDEO/LIVE/SHOWCASE/LINKSHARE — passthrough)
- `fully_refunded` (tuỳ chọn): `0` | `1`
- `page` (mặc định 1), `page_size` (mặc định 50, tối đa 200)
Response 200:
{ "creator_username": "__CREATOR__", "page": 1, "page_size": 50, "total": 12,
"orders": [ { "order_id": "...", "sku_id": "...", "product_id": "...", "product_name": "...",
"sub_id": "abc-def--", "sub1": "abc", "sub2": "def", "sub3": "", "sub4": "",
"quantity": 1, "refunded_quantity": 0, "fully_refunded": 0, "est_commission": "12.50",
"actual_commission": null, "currency": "VND", "settlement_status": "AWAITING PAYMENT",
"status": 1, "tt_order_status": 100, "content_type": "VIDEO", "create_time": 1749513600 } ] }
Kiểu JSON: cột số nguyên = number, cột tiền/decimal & ID lớn = string.
Enum các field trạng thái trong orders[]:
- `status` (number): 1=pending · 2=settled · 3=cancelled/refunded
- `tt_order_status` (number): 100=pending · 103=settled · 104=cancelled/refunded
- `settlement_status` / `payment_status` (string, passthrough TikTok): AWAITING PAYMENT · To-SETTLE · SETTLED · REFUNDED
- `fully_refunded` (number): 0 | 1
- `content_type` (string, passthrough): VIDEO · LIVE · SHOWCASE · LINKSHARE · …
- `actual_commission` (string|null): null khi chưa đối soát
- `sub1`..`sub4` (string): tag tách theo `-` (vị trí trống = `""`)
## 4) GET `/partner/tiktok/affiliate/products` — Lấy thông tin sản phẩm affiliate
API tạo link không kèm thông tin sản phẩm — dùng endpoint này lấy tên/ảnh/giá/hoa hồng theo `product_id` (trong phạm vi quyền của creator). RioHub cache thông tin sản phẩm 24h: id đã có trong cache trả về ngay, id mới/quá 24h mới gọi TikTok → giảm tải, nhanh hơn.
Query params:
- `creator_username` (bắt buộc)
- `product_id` (bắt buộc): 1 id hoặc danh sách phân tách bằng dấu phẩy (tối đa 100)
Response 200 (`products[]` = object passthrough TikTok V202509, snake_case):
{ "creator_username": "__CREATOR__", "requested": 1, "found": 1,
"products": [ { "id": "1732...", "title": "...", "main_image_url": "https://...",
"detail_link": "https://shop.tiktok.com/view/product/1732...",
"sale_region": "VN", "has_inventory": true, "units_sold": 62030,
"commission": { "rate": 600, "amount": "3299.94 - 5099.94", "currency": "VND" },
"shop_ads_commission": { "rate": 200 },
"sales_price": { "minimum_amount": "", "maximum_amount": "", "currency": "" },
"original_price": { "minimum_amount": "89000", "maximum_amount": "139000", "currency": "VND" },
"shop": { "name": "..." },
"category_chains": [ { "id": "700791", "is_leaf": true, "local_name": "Dao cạo", "parent_id": "849288" } ] } ],
"not_found": [] }
Ghi chú field: `commission.rate` raw ÷100 = % (600 = 6%); `commission.amount` có thể là khoảng "min - max";
`sales_price` có thể rỗng → dùng `original_price`; `units_sold` lũy kế; `has_inventory` còn hàng; ngành lá = phần tử `is_leaf:true`.
Id không lấy được (không đủ điều kiện / không tồn tại) nằm trong `not_found`. Dữ liệu cache 24h.
## 5) Postback (webhook) — RioHub POST về URL của bạn
Event JSON: `event` ∈ { order.created, order.updated, order.refunded }; `event_id` (UUID) idempotency; `occurred_at` ISO-8601.
`data` chứa các field như orders[] (status 1/2/3, order_status_raw = settlement_status gốc). Xác minh chữ ký header `X-Riohub-Signature: t=,v1=`.
## Yêu cầu code
- Đọc key từ env; có cơ chế retry khi gặp 429 (tôn trọng `Retry-After`).
- Bắt và log rõ các lỗi 401/403/404/422.
- Hàm tạo link nhận (product_url, sub_id) và trả về `affiliate_link`.
Thử nghiệm trực tiếp
Nhập dữ liệu và gọi API thật bằng key của bạn — phản hồi hiển thị bên dưới.
Tự dùng key của tài khoản này (tạo sẵn 1 key "Playground" khi bạn bấm Gửi). Hoặc dán key khác để thử.
Trả sharing_link + deep_link (mở app) + one_link. Link KHÔNG mang sub_id.
Nếu báo chưa có quyền (deep_link/one_link trống hoặc lỗi permission): hãy ngắt kết nối tài khoản TikTok rồi kết nối lại, và nhớ chấp nhận quyền “Read affiliate Share Link” khi TikTok hỏi.
Phản hồi
Postback qua Callback URL
RioHub POST JSON có chữ ký HMAC về URL của bạn mỗi khi đơn affiliate phát sinh / cập nhật / hoàn. Theo tài khoản (1 endpoint), áp dụng mọi creator đã kết nối. Bỏ trống URL nếu chỉ dùng Telegram bên dưới.
Nếu dùng: phải HTTPS, trả về HTTP
2xx trong vòng 5s để xác nhận đã nhận. Để trống nếu chỉ dùng Telegram.Giữ bí mật. Mỗi request kèm header
X-Riohub-Signature: t=<ts>,v1=<hmac>.Mẫu payload (body POST)
{
"event_id": "f1e2...-uuid",
"event": "order.created",
"occurred_at": "2026-06-10T04:18:00+00:00",
"data": {
"order_id": "5790...",
"sku_id": "1730...",
"product_id": "1729...",
"product_name": "...",
"creator_username": "your_creator",
"currency": "VND",
"quantity": 1,
"refunded_quantity": 0,
"fully_refunded": 0,
"status": 1,
"order_status_raw": "AWAITING PAYMENT",
"prev_order_status_raw": null,
"price": "199000.00",
"gmv": "199000.00",
"actual_commission": null,
"est_commission": "12.50",
"subid": "abc-def-ghi-jkl",
"sub1": "abc",
"sub2": "def",
"sub3": "ghi",
"sub4": "jkl"
}
}
Chi tiết field:
| Field | Type | Giá trị / Enum | Mô tả |
|---|---|---|---|
event_id | string | UUID | ID sự kiện, ổn định để chống xử lý trùng (idempotency). |
event | string | order.created · order.updated · order.refunded | Loại sự kiện (trùng danh sách "Sự kiện đăng ký" ở trên). |
occurred_at | string | ISO-8601 | Thời điểm phát sinh sự kiện. |
data.order_id | string | — | Mã đơn TikTok. |
data.sku_id | string | — | Mã SKU. |
data.quantity | number | — | Số lượng đặt. |
data.refunded_quantity | number | — | SL đã hoàn. |
data.fully_refunded | number | 0 · 1 | 1 = đã hoàn toàn bộ. |
data.status | number | 1 · 2 · 3 | 1=pending · 2=settled · 3=refunded/cancelled. |
data.order_status_raw | string | AWAITING PAYMENT · To-SETTLE · SETTLED · REFUNDED | Trạng thái gốc TikTok (passthrough). |
data.prev_order_status_raw | string · null | null với order.created | Trạng thái gốc trước khi cập nhật (để hiển thị cũ → mới); chỉ có ở order.updated. |
data.price | string · null | — | Đơn giá 1 sản phẩm. |
data.gmv | string · null | — | GMV = đơn giá × số lượng. |
data.actual_commission | string · null | null khi chưa đối soát | Hoa hồng thực nhận. |
data.est_commission | string · null | — | Hoa hồng ước tính (dùng khi chưa đối soát). |
data.subid | string | vd abc-def-ghi-jkl | Sub_id đầy đủ (tag gốc) gắn vào link affiliate. |
data.sub1 … data.sub4 | string | — | subid tách theo dấu - (vị trí 1–4); rỗng nếu không có. |
Các field còn lại trong data (product_id, product_name, creator_username, currency, returned_quantity) cùng kiểu & ý nghĩa như ở API Lấy đơn hàng.
Xác minh chữ ký (PHP)
<?php
$secret = 'YOUR_SIGNING_SECRET';
$raw = file_get_contents('php://input'); // body thô, KHÔNG decode
$sig = $_SERVER['HTTP_X_RIOHUB_SIGNATURE'] ?? ''; // "t=...,v1=..."
parse_str(str_replace(',', '&', $sig), $p);
$expected = hash_hmac('sha256', ($p['t'] ?? '') . '.' . $raw, $secret);
if (!hash_equals($expected, $p['v1'] ?? '')) { http_response_code(403); exit('bad signature'); }
// (tuỳ chọn) chống replay: từ chối nếu abs(time() - $p['t']) > 300
$event = json_decode($raw, true);
// ... xử lý $event['event'] / $event['data'] ...
http_response_code(200); echo 'ok';
Retry: nếu không nhận 2xx, RioHub thử lại theo backoff 1m → 5m → 30m → 2h → 6h (tối đa 6 lần) rồi đánh dấu dead.
Lịch sử gửi gần đây
| Thời điểm | Sự kiện | Order | Postback (HTTP) | Telegram | Lần thử | Lỗi |
|---|---|---|---|---|---|---|
| — | ||||||
Thông báo qua Telegram
Gửi 1 tin nhắn tóm tắt mỗi đơn về Telegram của bạn — kênh độc lập, dùng bot riêng. Lưu riêng, không ảnh hưởng cấu hình URL ở trên. Cách lấy token & chat ID ▾
- Mở
@BotFathertrên Telegram → gửi/newbot→ nhận bot token dạng123456789:ABC-def.... - Nhắn cho bot (chat riêng), hoặc thêm bot vào group/channel.
- Lấy chat ID: mở
https://api.telegram.org/bot<token>/getUpdatessau khi nhắn bot → copychat.id. Channel công khai dùng@tenkenh.
Token được lưu phía máy chủ, không hiển thị lại.
Để trống & lưu = tắt Telegram.
Nút Gửi test bắn 1 tin ping tới mọi kênh đang bật (URL & Telegram).