Tham gia Group Facebook về kiếm tiền Affiliate TikTok Shop Kiếm tiền AFF với TikTok Shop — cộng đồng chia sẻ mẹo & chiến lược Tham gia ngay Tham gia nhóm Zalo

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: 05/08/2026

Mới (12/08/2026) — Rate hoa hồng THỰC TẾ trên API sản phẩm: GET /partner/tiktok/affiliate/products và POST /product-links bổ sung object observed_commission gồm commission_rate (rate tổng, đã gồm HH thưởng), commission_bonus_rate, shop_ads_commission_rate, scope, last_order_at. Lý do: commission.rate của TikTok chỉ là rate chuẩn — TikTok không trả HH thưởng ở endpoint sản phẩm (thưởng gắn với collaboration/campaign, chỉ có trên đơn), nên hoàn tiền dự kiến tính theo commission.rate sẽ thấp hơn thực tế. RioHub lấy rate tổng từ đơn gần nhất của chính sản phẩm đó. Các field cũ không thay đổi.

Mới (05/08/2026) — Tạo link kèm thông tin sản phẩm trong 1 request: endpoint POST /partner/tiktok/affiliate/product-links nhận body giống hệt POST /links nhưng phản hồi kèm luôn object product (tên, ảnh, giá, hoa hồng, ngành hàng) — không cần gọi thêm GET /partner/tiktok/affiliate/products, tiết kiệm 1 round-trip. Lấy thông tin sản phẩm là best-effort: nếu TikTok không trả về thì product = null và product_error ghi lý do, link vẫn được trả bình thường. Dùng chung cache 24h với GET /products. Các endpoint cũ không thay đổi. Xem chi tiết ở mục Hướng dẫn API.

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.

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

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 — TỔNG, ĐÃ GỒM thưởng + QC shop (đối ứng của `est_commission`). KHÔNG cộng thêm 2 field dưới.
`actual_bonus_commission`	string · null	`null` khi chưa đối soát	Phần HH thưởng thực nhận — thành phần bên trong `actual_commission`.
`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.
`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 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'

<?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: 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. 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): TỔNG thực nhận, ĐÃ GỒM thưởng + QC shop (null khi chưa đối soát) — KHÔNG cộng thêm `actual_bonus_commission`/`actual_shop_ads_commission`, chúng là thành phần bên trong - `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" } ], "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. ## 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,
    "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 ▾

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

Về TikTok Shop

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

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