Sàn Đen Shop × RioHub

Sàn Đen Shop Affiliate API

Với Sàn Đen Shop, chúng tôi không tự vận hành API mà khuyên dùng RioHub — nền tảng affiliate Sàn Đen Shop cho creator Việt Nam: tạo link affiliate kèm sub_id theo dõi hoa hồng, deep link mở app, tra cứu sản phẩm và đồng bộ đơn hàng qua API/webhook. Trang này mô tả cách hoạt động để bạn tích hợp thẳng với RioHub.

300request / phút
100.000request / ngày
5–30 phútđơn ghi nhận
0đmiễn phí cho creator
📢 29/09/2026 — RioHub bổ sung 2 tên miền mới cho Web & API
Ngoài riohub.vn, RioHub chạy song song riohub.riokupon.com và riohub.riokupon.me — cùng hệ thống, cùng dữ liệu. Chỉ cần thay tên miền trong base URL: đường dẫn, tham số, header, API key và định dạng phản hồi giữ nguyên.

Cập nhật 03/10/2026: sự cố làm riohub.vn gián đoạn hồi 29/09 đã khắc phục — cả ba tên miền hiện chạy bình thường. Dù vậy vẫn nên cấu hình sẵn tên miền dự phòng để lần sau không phải sửa code: xem Tên miền & dự phòng.
🤖 Dành cho AI / LLM

Copy toàn bộ hướng dẫn API dạng text rồi dán vào ChatGPT / Claude / Gemini — AI sẽ hiểu ngay cách tích hợp và viết code giúp bạn.

Cách hoạt động

Kết nối creator

Đăng ký RioHub, kết nối tài khoản creator Sàn Đen của bạn và lấy API key ở mục Developer.

Tạo link qua API

Gửi URL sản phẩm (vt.tiktok.com hoặc link trực tiếp) kèm sub_id → nhận link affiliate chính chủ.

Chia sẻ & bán hàng

Gắn link vào video, livestream, bio, quảng cáo… Người xem mua qua link của bạn.

Theo dõi hoa hồng

Đơn ghi nhận tự động trong 5–30 phút. Lọc theo từng sub_id hoặc nhận realtime qua webhook.

Tên miền & dự phòng

RioHub phục vụ Web và API trên 3 tên miền song song, dùng chung một hệ thống và một bộ dữ liệu. API key giống nhau trên cả ba.

Tên miềnBase URL của API
riohub.vnhttps://riohub.vn/api/v1 (tên miền chính)
riohub.riokupon.comhttps://riohub.riokupon.com/api/v1
riohub.riokupon.mehttps://riohub.riokupon.me/api/v1

Chuyển tên miền là chỉ đổi phần host: đường dẫn, tham số, header, API key và định dạng phản hồi giữ nguyên. Ví dụ POST https://riohub.riokupon.com/api/v1/partner/tiktok/affiliate/links.

Bài học từ sự cố 29/09/2026 — đừng chỉ bắt lỗi DNS: hôm đó riohub.vn vẫn phân giải DNS bình thường, nhưng chứng chỉ TLS nó trả về là của riohub.riokupon.com nên client báo lỗi xác minh tên miền (SSL: no alternative certificate subject name matches ... 'riohub.vn') và request chết trước khi có HTTP status. Code nào chỉ chuyển tên miền khi "không phân giải được DNS" thì ca này không chạy dự phòng. Vậy điều kiện chuyển nên tính cả lỗi TLS/chứng chỉ — với cURL là các mã 6, 7, 28, 35, 51, 60 (cùng một lỗi sai tên miền, tuỳ bản libcurl mà báo 51 hoặc 60 — phải bắt cả hai).

Đo lại ngày 03/10/2026: chứng chỉ của riohub.vn đã có SAN khớp đúng tên miền, cả ba tên miền đều trả 401 như mong đợi khi gọi không kèm API key — tức đã bình thường trở lại.

Các endpoint chính

Base URL https://riohub.vn/api/v1 (hoặc tên miền dự phòng) · xác thực bằng header X-Riohub-Api-Key trên mọi request (đọc key từ biến môi trường, không hardcode vào code).

POST https://riohub.vn/api/v1/partner/tiktok/affiliate/links

Nhận product_url (link rút gọn vt.tiktok.com hoặc link trực tiếp — hoặc product_id) và sub_id, trả về link affiliate.

Cấu trúc sub_id — gói tối đa 4 sub theo vị trí, phân tách bằng "-":
fb-tet2026-video1-a
sub1 = fb (nguồn)
sub2 = tet2026 (chiến dịch)
sub3 = video1 (vị trí)
sub4 = a (biến thể)

1–128 ký tự [A-Za-z0-9_-]; mỗi sub KHÔNG được chứa - (đó là dấu phân tách). Vị trí trống để rỗng, vd abc-def--.

# Base URL để ở biến để đổi tên miền được mà không sửa code gọi API
# https://riohub.vn/api/v1 · https://riohub.riokupon.com/api/v1 · https://riohub.riokupon.me/api/v1
RIOHUB_BASE="https://riohub.vn/api/v1"

curl -X POST "$RIOHUB_BASE/partner/tiktok/affiliate/links" \
  -H "X-Riohub-Api-Key: $RIOHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creator_username": "nnguynanh0",
    "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": "nnguynanh0"
}

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

POST https://riohub.vn/api/v1/partner/tiktok/affiliate/general-links

Gửi tối đa 50 product_ids một lần → nhận sharing_link (web), deep_link (mở app) và one_link cho từng sản phẩm; sản phẩm lỗi trả trong failed kèm lý do. Deep link không gắn được sub_id — cần theo dõi hoa hồng theo sub_id thì dùng endpoint số 1.

3) Danh sách link đã tạo

GET https://riohub.vn/api/v1/partner/tiktok/affiliate/links

Liệt kê link đã tạo qua API kèm số đơn và hoa hồng theo từng sub_id. Lọc theo sub_id (khớp chuỗi con), sub1..sub4 (khớp chính xác từng vị trí), channel, khoảng ngày tạo; phân trang page_size tối đa 200.

4) Danh sách đơn hàng affiliate

GET https://riohub.vn/api/v1/partner/tiktok/affiliate/orders

Kéo đơn hàng kèm hoa hồng ước tính/thực nhận. Bộ lọc mạnh: theo thời gian tạo hoặc thời điểm đơn được cập nhật (update_time_start/end — dùng để sync tăng dần khi đơn đổi trạng thái settlement/refund), theo sub_id/sub1..sub4, mã đơn (tối đa 200 — tiện verify postback), settlement_status, status chuẩn hoá (1 pending · 2 settled · 3 cancelled/refunded), product_id, nguồn nội dung (VIDEO/LIVE/SHOWCASE/LINKSHARE), fully_refunded.

5) Thông tin sản phẩm affiliate

GET https://riohub.vn/api/v1/partner/tiktok/affiliate/products

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, lượt bán theo product_id (tối đa 100 id/request). RioHub cache 24 giờ: id đã có trong cache trả về ngay, id mới/quá hạn mới gọi Sàn Đen.

6) Postback / Webhook

RioHub POST về URL của bạn khi có sự kiện order.created, order.updated, order.refunded — mỗi event có event_id (UUID) để chống trùng và chữ ký header X-Riohub-Signature để xác minh. Server của bạn cần trả HTTP 2xx trong 5 giây; thất bại sẽ được retry lùi dần tối đa 6 lần. Kết hợp với endpoint orders (lọc theo order_id) để đối chiếu.

Mã lỗi thường gặp

HTTPÝ nghĩa
401API key sai hoặc thiếu.
403Creator không thuộc tài khoản của API key.
404Creator chưa kết nối RioHub.
422product_not_promotable — sản phẩm không có hoa hồng hoặc chưa được shop duyệt.
429Vượt rate limit — đọc header Retry-After rồi thử lại.
502Không tạo được link nào (batch deep link).

Mẹo tích hợp

Trang này chỉ mang tính giới thiệu/tài liệu tham khảo — data.addlivetag.com không vận hành API Sàn Đen Shop; mọi request gọi trực tiếp tới RioHub bằng API key của bạn. Trong lúc đó bạn vẫn có thể dùng Sàn Cam Product Data API, Sàn Xanh Product Feed API và Dịch vụ giao đồ ăn (Sàn Cam) Store API tại đây.

Sẵn sàng tạo link affiliate đầu tiên?

Đăng ký RioHub, kết nối creator Sàn Đen của bạn và lấy API key — miễn phí cho creator, hoa hồng chính chủ về tài khoản của bạn.