TikTok Shop — Developer 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.

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.

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_gmv": "199000.00",
      "est_standard_commission": "19900.00",
      "est_commission": "19900.00",
      "actual_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_gmv`	string	—	GMV dùng để tính hoa hồng (decimal chuỗi).
`est_standard_commission`	string	—	Hoa hồng chuẩn ước tính.
`est_commission`	string	—	Hoa hồng ròng ước tính của creator (gồm cả đơn pending).
`actual_commission`	string · null	`null` khi chưa đối soát	Hoa hồng thực nhận sau đối soát.
`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"}' # 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"] ?? []);

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: 11/06/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. ## 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.

API Key *

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ử.

creator_username

product_url / product_id

sub_id

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.

Callback URL (tuỳ chọn nếu đã bật Telegram)

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.

Trạng thái

Bật postback (cả URL & Telegram)

Sự kiện đăng ký

order.created — đơn mới

order.updated — đổi trạng thái/hoa hồng

order.refunded — hoàn/huỷ

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",
    "actual_commission": null,
    "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.actual_commission`	string · null	`null` khi chưa đối soát	Hoa hồng thực nhận.
`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 ▾

Chưa bật

Bot token

Token được lưu phía máy chủ, không hiển thị lại.

Chat ID

Để 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).

Developer API — TikTok Shop Affiliate

API Keys của bạn

Hướng dẫn sử dụng

1. Xác thực

Tạo link affiliate

Lấy thông tin sản phẩm affiliate

Lấy đơn hàng

Lấy danh sách link đã tạo

Code mẫu

Tích hợp bằng AI

Thử nghiệm trực tiếp

Postback qua Callback URL

Mẫu payload (body POST)

Xác minh chữ ký (PHP)

Lịch sử gửi gần đây

Thông báo qua Telegram

Tạo API key mới