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.

POST

Tạo link + lấy thông tin sản phẩm (1 request)

Giống POST /links nhưng phản hồi kèm luôn object product (tên, ảnh, giá, hoa hồng) — không cần gọi thêm GET /products. Body giống hệt 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_url`	Có*	URL sản phẩm 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`, `channel`	Không	Như `POST /links`.

Ví dụ (cURL):

Phản hồi 200 (rút gọn):

{
  "affiliate_link": "https://vt.tiktok.com/XXXXXX/",
  "sub_id": "fb-ads-01",
  "product_id": "1729...",
  "creator_username": "your_creator",
  "product": {
    "id": "1729...",
    "title": "Bộ Cạo Râu 72 Lưỡi...",
    "main_image_url": "https://...",
    "commission": { "rate": 600, "amount": "3299.94", "currency": "VND" },
    "original_price": { "minimum_amount": "89000", "maximum_amount": "139000", "currency": "VND" }
  },
  "product_error": null
}

Lấy thông tin sản phẩm là best-effort: nếu TikTok không trả về, product = null và product_error ghi lý do — link vẫn được trả bình thường. Link tạo lỗi → cùng mã lỗi như POST /links (422 product_not_promotable / 502).

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" }
      ],
      "observed_commission": {
        "commission_rate": 2300, "commission_bonus_rate": 1500,
        "shop_ads_commission_rate": 0, "standard_commission_rate": 800,
        "scope": "creator", "source": "orders", "last_order_at": "2026-08-10 04:12:33"
      }
    }
  ],
  "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á.
`observed_commission`	object · vắng	Field riêng của RioHub (không phải TikTok) — rate thực tế đã gồm HH thưởng, xem bảng dưới. Vắng khi sản phẩm chưa có đơn nào trong dữ liệu RioHub.

commission.rate của TikTok KHÔNG gồm hoa hồng thưởng. Đó là rate chuẩn shop đặt cho public promotion. Hoa hồng thưởng (bonus) gắn với collaboration/campaign nên TikTok không trả ở bất kỳ endpoint sản phẩm nào — chỉ có trên sku của đơn hàng. Muốn hiện hoàn tiền dự kiến đúng, dùng observed_commission.commission_rate; nếu vắng thì fallback commission.rate (+ shop_ads_commission.rate).

Field trong observed_commission (RioHub tính từ đơn gần nhất của sản phẩm):

Field	Type	Mô tả
`commission_rate`	number	Rate TỔNG = chuẩn + thưởng + QC shop + reward (raw, ÷100 = %). Dùng field này để tính hoàn tiền.
`commission_bonus_rate`	number	Rate HH thưởng (raw, ÷100 = %).
`shop_ads_commission_rate`	number	Rate HH quảng cáo shop (raw, ÷100 = %).
`standard_commission_rate`	number	Phần còn lại = tổng − thưởng − QC shop (gồm cả reward rate).
`scope`	string	`creator` = lấy từ đơn của chính creator này (chính xác nhất, vì deal thưởng theo từng collaboration) · `global` = đơn của creator khác trên RioHub (chỉ tham chiếu).
`source`	string	Luôn `orders` — nguồn dữ liệu là đơn affiliate đã sync.
`last_order_at`	string	Thời điểm đơn tham chiếu (`Y-m-d H:i:s` UTC). Rate thưởng theo campaign nên có thể đã hết hạn.

Các field còn lại trong 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

Tìm sản phẩm theo từ khoá

Dùng khi chỉ biết TÊN sản phẩm, chưa có product_id/product_url — ví dụ đối chiếu sản phẩm giữa các sàn, hoặc cho user duyệt catalogue trong app của bạn. Có id rồi thì gọi POST /product-links để tạo link. RioHub cache 1 giờ theo (creator + bộ filter): gọi lặp cùng từ khoá không tốn thêm quota TikTok.

Query params:

Param	Bắt buộc	Mô tả
`creator_username`	Có	Username TikTok creator (đã kết nối).
`keyword`	Không	Khớp theo tên sản phẩm. Bỏ trống = duyệt danh sách mặc định. Tối đa 200 ký tự.
`price_min` / `price_max`	Không	Khoảng giá (VND). Chỉ một đầu cũng hợp lệ.
`rate_min` / `rate_max`	Không	Khoảng hoa hồng, số thô: `800` = 8%.
`sold_min` / `sold_max`	Không	Khoảng lượt bán lũy kế.
`rating_min` / `rating_max`	Không	Khoảng điểm shop (0–5).
`category_ids`	Không	Danh mục, phân tách dấu phẩy (tối đa 20).
`sort_type`	Không	Chuyển thẳng lên TikTok. Họ chưa công bố tập giá trị hợp lệ nên RioHub không whitelist.
`page_size`	Không	1–50, mặc định 20.
`page_token`	Không	Con trỏ lấy từ `next_page_token` của phản hồi trước.

3 giới hạn phải biết trước khi tích hợp — đều là giới hạn phía TikTok, không phải phía RioHub:

Phạm vi theo creator. Không có API tìm kiếm toàn sàn ẩn danh: kết quả là tập sản phẩm creator đó được phép quảng bá, nên 2 creator có thể ra kết quả khác nhau.
Không lọc theo giá / % hoa hồng / danh mục / shop. TikTok chỉ nhận keyword ở tầng filter và cho sắp xếp theo 2 field trên. Muốn lọc giá/hoa hồng thì lấy về rồi lọc ở phía bạn.
Không có tìm theo ảnh. Không endpoint nào nhận ảnh đầu vào. Cách khớp thực dụng: chuẩn hoá tên (bỏ tên shop/emoji/mã SKU, giữ brand + dòng sản phẩm) → search → lọc band giá ±20% → so ảnh ở phía bạn bằng main_image_url.

Phản hồi 200:

{
  "creator_username": "your_creator",
  "keyword": "cạo râu",
  "page_size": 20,
  "count": 2,
  "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",
      "price": { "amount": "89000", "currency": "VND" },
      "commission": { "rate": 600 },
      "seller_name": "Nấmm Decor",
      "observed_commission": { "commission_rate": 2300, "commission_bonus_rate": 1500, "scope": "creator" }
    }
  ],
  "next_page_token": "eyJvZmZzZXQiOjIwfQ=="
}

Mã lỗi riêng của endpoint này:

HTTP	`code`	Nghĩa & việc cần làm
`422`	`validation_error`	Tham số sai (thiếu `creator_username`, khoảng lọc âm hoặc `min > max`, `keyword` > 200 ký tự, `page_token` quá dài).
`424`	`creator_token_invalid`	Không phải lỗi key của bạn. Token TikTok của creator hỏng/hết hạn — creator phải kết nối lại trên RioHub. Đừng xoay API key.
`429`	`tiktok_rate_limited`	TikTok đang chặn nhịp. Chờ theo `Retry-After`. Khác `rate_limited` (hạn mức key của bạn).
`503`	`tiktok_scope_unavailable`	Quyền phía RioHub đang không dùng được. Liên hệ support, retry không giúp.
`502`	`tiktok_shop_error`	TikTok lỗi/không tới được. Retry có giãn cách.

next_page_token rỗng = hết trang; trang sau truyền nguyên giá trị này vào page_token. Object sản phẩm passthrough từ TikTok nên tên field có thể lệch nhẹ giữa các phiên bản API — đọc phòng thủ: id || product_id, title || product_name, main_image_url || cover_url || image_url. observed_commission (ý nghĩa field xem endpoint sản phẩm ở trên) chỉ có khi sản phẩm đã phát sinh đơn — dùng field này để so hoa hồng, không dùng commission.rate (chỉ là rate chuẩn shop đặt).

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,
      "settled_at": null,
    "settled_at_iso": null,
      "time_created_iso": "2026-06-10T08:00:00Z",
      "time_delivered_iso": null,
      "settled_at_iso": 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	Tiền creator thực nhận sau đối soát. KHÔNG cộng thêm 2 field dưới — TikTok tính `actual_commission = chuẩn + thưởng + QC shop + shared_with_partner`, trong đó `shared_with_partner` là số âm (phần chia cho MCN). VD đơn `585510807483352367`: `6.080 + 45.600 + 0 − 46.512 = 5.168`. Cộng thêm thưởng là cộng ngược lại phần MCN đã giữ ⇒ trả thừa ~10 lần.
`actual_standard_commission`	string · null	`null` khi chưa đối soát	Phần HH chuẩn — gộp trước khi chia MCN, chỉ để hiện breakdown.
`actual_bonus_commission`	string · null	`null` khi chưa đối soát	Phần HH thưởng — gộp trước khi chia MCN, chỉ để hiện breakdown.
`shared_with_partner`	string · null	số ÂM; `0` nếu không chia MCN	Phần doanh thu chia cho MCN. Đa số creator = 0.
`pit`	string · null	số ÂM	Thuế TNCN TikTok khấu trừ (10% phần HH chuẩn) — áp cho cả creator thường.
`actual_creator_commission_reward_fee`	string · null	số ÂM; thường `0`	Phí reward TikTok khấu trừ.
`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 — thành phần bên trong `actual_commission`.
`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 (`last_update_time` của TikTok) — đổi mỗi lần SKU bị đụng: quyết toán, hoàn, chỉnh rate… Không phải ngày quyết toán.
`time_created`	string	`Y-m-d H:i:s` (UTC)	`create_time` dạng ngày giờ. Giờ UTC — cộng 7 tiếng ra giờ VN.
`time_delivered`	string · null	`Y-m-d H:i:s` (UTC)	Thời điểm giao hàng, giờ UTC (null nếu chưa giao).
`settled_at`	string · null	`Y-m-d H:i:s` (UTC)	Ngày quyết toán (thời điểm RioHub ghi nhận đơn chốt hoa hồng — cùng mốc làm badge “Đã chốt HH” bật lên, gồm cả đơn `To-SETTLE` đã có hoa hồng thực nhận; lệch so với TikTok tối đa bằng nhịp sync ~3h). TikTok không trả mốc này cho creator nên RioHub tự ghi. Đóng dấu khi đơn chuyển sang đã chốt; xoá về `null` nếu đơn chuyển sang huỷ/hoàn, chốt lại thì nhận mốc mới. `null` khi: chưa quyết toán · đã quyết toán trước 04/09/2026 · hoặc đơn quyết toán muộn hơn 60 ngày kể từ ngày tạo (cron không quét lại quá mốc đó).
`time_created_iso` · `time_delivered_iso` · `settled_at_iso`	string · null	ISO 8601, vd `2026-08-29T02:50:22Z`	Nên dùng bộ này. Cùng giá trị với 3 field không hậu tố, nhưng hậu tố `Z` nói rõ là UTC nên mọi thư viện ngày giờ tự parse đúng — không còn nguy cơ đọc nhầm thành giờ VN.
`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 link + lấy luôn thông tin sản phẩm trong 1 request curl -X POST '__BASE__/partner/tiktok/affiliate/product-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"}' # 1c) 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' # 5) Tìm sản phẩm theo từ khoá (chưa biết product_id) — phân trang bằng con trỏ next_page_token curl '__BASE__/partner/tiktok/affiliate/products/search?creator_username=__CREATOR__&keyword=c%E1%BA%A1o%20r%C3%A2u&price_min=30000&rate_min=800&page_size=20' \ -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"] ?? []);

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")) # 5) Tìm sản phẩm theo từ khoá — duyệt hết trang bằng con trỏ next_page_token page_token, found = "", [] while True: params = { "creator_username": "__CREATOR__", "keyword": "cạo râu", "rate_min": 800, # hoa hồng thô: 800 = 8% "page_size": 20, } if page_token: params["page_token"] = page_token page = requests.get(f"{BASE}/partner/tiktok/affiliate/products/search", headers=H, params=params).json() found += page.get("products") or [] page_token = page.get("next_page_token") or "" # rỗng = hết trang if not page_token or len(found) >= 100: break print(len(found), found[0].get("id") if found else None)

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: 05/08/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/product-links` — Tạo link + thông tin sản phẩm (1 request) Body giống hệt `/links` (`creator_username`, `product_url`|`product_id`, `sub_id`, `type?`, `channel?`). Khác biệt: response kèm object `product` (tên, ảnh, giá, hoa hồng) — không cần gọi thêm `GET /products`. Response 200: { "affiliate_link": "https://vt.tiktok.com/XXXXXX/", "sub_id": "fb-ads-01", "product_id": "1729...", "creator_username": "__CREATOR__", "product": { "id": "1729...", "title": "...", "main_image_url": "https://...", "commission": { "rate": 600, "amount": "3299.94", "currency": "VND" }, "original_price": { "minimum_amount": "89000", "maximum_amount": "139000", "currency": "VND" } }, "product_error": null } Lấy thông tin sản phẩm là best-effort: lỗi → `product` = null, `product_error` ghi lý do, link vẫn trả về. ## 1c) 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. **Múi giờ:** `create_time` / `update_time` là unix giây (không phụ thuộc múi giờ). Mọi field chuỗi ngày giờ — `time_created`, `time_delivered`, `settled_at` — đều là **UTC**, cộng 7 tiếng ra giờ Việt Nam. **Khuyến nghị:** dùng `create_time` / `update_time` (unix giây) hoặc bộ `*_iso` (`time_created_iso`, `time_delivered_iso`, `settled_at_iso`, và `created_at_iso` ở endpoint link). Hai dạng này không thể hiểu sai múi giờ. Các field chuỗi trần vẫn giữ nguyên để không phá client cũ, nhưng chúng không mang dấu hiệu múi giờ nên dễ bị đọc nhầm thành giờ VN. 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): tiền creator THỰC NHẬN (null khi chưa đối soát). Công thức TikTok: `actual_standard_commission + actual_bonus_commission + actual_shop_ads_commission + shared_with_partner + pit + actual_creator_commission_reward_fee` (3 field cuối là các khoản TRỪ, đã mang dấu ÂM: chia MCN, thuế TNCN 10%, phí reward). KHÔNG cộng thêm 6 field đó vào — chúng chỉ để hiện breakdown - `sub1`..`sub4` (string): tag tách theo `-` (vị trí trống = `""`) - `settled_at` (string|null, `Y-m-d H:i:s` UTC): ngày quyết toán — thời điểm RioHub **ghi nhận** đơn chốt hoa hồng (`status` = 2, cùng mốc badge “Đã chốt HH” — gồm cả đơn `To-SETTLE` đã có hoa hồng thực nhận; lệch so với TikTok tối đa bằng nhịp sync ~3h). Đóng dấu khi đơn chuyển sang đã chốt; **xoá về `null` nếu đơn chuyển sang huỷ/hoàn**, chốt lại thì nhận mốc mới. `update_time` KHÔNG phải mốc này — đó là `last_update_time` của TikTok, đổi mỗi lần SKU bị đụng. `null` khi: chưa quyết toán · quyết toán trước 04/09/2026 · hoặc quyết toán muộn hơn 60 ngày kể từ ngày tạo đơn (cron không quét lại quá mốc đó) ## 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" } ], "observed_commission": { "commission_rate": 2300, "commission_bonus_rate": 1500, "shop_ads_commission_rate": 0, "standard_commission_rate": 800, "scope": "creator", "source": "orders", "last_order_at": "2026-08-10 04:12:33" } } ], "not_found": [] } QUAN TRỌNG khi hiện hoàn tiền dự kiến: `commission.rate` của TikTok chỉ là rate CHUẨN, KHÔNG gồm hoa hồng thưởng (bonus gắn với collaboration/campaign, TikTok không trả ở endpoint sản phẩm). Dùng `observed_commission.commission_rate` (rate TỔNG thực tế, RioHub lấy từ đơn gần nhất của sản phẩm; `scope`=creator là đơn của chính creator, `global` là tham chiếu từ creator khác); nếu không có key `observed_commission` thì fallback `commission.rate` + `shop_ads_commission.rate`. 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. ## 4b) GET `/partner/tiktok/affiliate/products/search` — Tìm sản phẩm theo TỪ KHOÁ Dùng khi chỉ biết TÊN sản phẩm, chưa có `product_id`/`product_url` (đối chiếu sản phẩm giữa các sàn, duyệt catalogue). Có `id` rồi thì gọi `POST /product-links` để tạo link. RioHub cache 1 giờ theo (creator + bộ filter). Query params: - `creator_username` (bắt buộc) - `keyword` (tuỳ chọn): khớp theo TÊN sản phẩm, tối đa 200 ký tự. Bỏ trống = danh sách mặc định - `price_min`/`price_max` (tuỳ chọn): khoảng giá VND, một đầu cũng hợp lệ - `rate_min`/`rate_max` (tuỳ chọn): khoảng hoa hồng, số THÔ — 800 = 8% - `sold_min`/`sold_max` (tuỳ chọn): khoảng lượt bán lũy kế - `rating_min`/`rating_max` (tuỳ chọn): khoảng điểm shop 0–5 - `category_ids` (tuỳ chọn): CSV, tối đa 20 - `sort_type` (tuỳ chọn): chuyển thẳng lên TikTok, họ chưa công bố tập giá trị hợp lệ - `page_size` (tuỳ chọn): 1-50, mặc định 20 - `page_token` (tuỳ chọn): CON TRỎ lấy từ `next_page_token` của phản hồi trước — KHÔNG phải số trang Response 200: { "creator_username": "__CREATOR__", "keyword": "cạo râu", "page_size": 20, "count": 2, "products": [ { "id": "1732...", "title": "...", "main_image_url": "https://...", "price": { "amount": "89000", "currency": "VND" }, "commission": { "rate": 600 }, "seller_name": "...", "observed_commission": { "commission_rate": 2300, "commission_bonus_rate": 1500, "scope": "creator" } } ], "next_page_token": "eyJvZmZzZXQiOjIwfQ==" } Vòng lặp phân trang: trang đầu KHÔNG truyền `page_token`; trang sau truyền nguyên `next_page_token`; `next_page_token` rỗng = hết trang. 3 GIỚI HẠN (phía TikTok, không phải phía RioHub) — code phải tính tới: 1. Kết quả THEO PHẠM VI TỪNG CREATOR: không có tìm kiếm toàn sàn ẩn danh, kết quả là tập sản phẩm creator đó được phép quảng bá nên 2 creator có thể ra khác nhau. Vì vậy `creator_username` bắt buộc. 2. KHÔNG lọc được theo giá / % hoa hồng / danh mục / shop — TikTok chỉ nhận `keyword` ở tầng filter, chỉ SẮP XẾP theo 2 field trên. Muốn lọc giá/hoa hồng thì lấy về rồi lọc phía client. 3. KHÔNG có tìm theo ảnh (image search): không endpoint nào nhận ảnh đầu vào. Cách khớp chéo sàn thực dụng: chuẩn hoá tên (bỏ tên shop/emoji/mã SKU, giữ brand + dòng sản phẩm), search, lọc band giá +/-20%, rồi so ảnh phía client bằng `main_image_url`. Mã lỗi riêng: 422 `validation_error` (tham số sai — khoảng lọc âm, `min > max`, `keyword` quá 200 ký tự, `page_token` quá dài); 424 `creator_token_invalid` (token TikTok của CREATOR hỏng — KHÔNG phải key sai, đừng xoay key); 429 `tiktok_rate_limited` (chờ theo `Retry-After`); 503 `tiktok_scope_unavailable` (retry không giúp); 502 `tiktok_shop_error` (TikTok lỗi, retry có giãn cách). Object sản phẩm passthrough từ TikTok nên đọc PHÒNG THỦ: `id` hoặc `product_id`; `title` hoặc `product_name`; `main_image_url` hoặc `cover_url` hoặc `image_url`; `commission.rate` hoặc `commission_rate`. So hoa hồng thì dùng `observed_commission.commission_rate` (rate tổng thực tế), KHÔNG dùng `commission.rate` (chỉ rate chuẩn) — xem mục 4. ## 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

Kèm thông tin sản phẩm (gọi /product-links)

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",
    "prev_order_status_raw": null,
    "settled_at": null,
    "settled_at_iso": 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.settled_at_iso`	string · null	ISO 8601, vd `2026-08-29T02:50:22Z`	Nên dùng field này. Cùng giá trị với `data.settled_at` nhưng có hậu tố `Z` nên không thể đọc nhầm múi giờ.
`data.settled_at`	string · null	`Y-m-d H:i:s` (UTC)	Ngày quyết toán — gửi kèm ngay trong postback đơn chuyển sang đã chốt (`status` = 2), khỏi phải gọi lại REST. Ý nghĩa `null`: xem field cùng tên ở orders[].
`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 ▾

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

Tạo link + lấy thông tin sản phẩm (1 request)

Tạo deep link (mở app) — theo lô

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

Tìm sản phẩm theo từ khoá

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