Sàn Đen Shop Affiliate API

Cách hoạt động

Các endpoint chính

Base URL https://riohub.vn/api/v1 · 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).

1) Tạo link affiliate (có sub_id)

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.

curl -X POST "https://riohub.vn/api/v1/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ô)

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

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

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

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.

• commission.rate là giá trị raw ÷ 100 = % (vd 600 = 6%); commission.amount có thể là khoảng "min – max".
• sales_price có thể rỗng → dùng original_price. units_sold là lũy kế.

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

Mẹo tích hợp

• Đọc API key từ biến môi trường (.env), không commit key vào git, không trả key ra client.
• Gặp 429: tôn trọng Retry-After, thêm retry có giới hạn số lần.
• Đặt sub_id theo cấu trúc 4 vị trí ngay từ đầu (vd nguồn-chiến_dịch-vị_trí-biến_thể) để sau này lọc đơn theo sub1..sub4 mà không phải đổi tag.
• Sync đơn tăng dần bằng update_time_start/end thay vì quét lại toàn bộ theo ngày tạo.
• Nhận postback thì hold ~5 phút rồi gom một loạt order_id gọi 1 request verify (endpoint orders nhận tối đa 200 mã/lần).