Trả một giỏ sản phẩm đã chấm điểm để lên live, chia sẵn từng nhóm 100 link (Sàn Cam nhận tối đa 100 link mỗi lần dán). Giỏ thuần dữ liệu thị trường — không có SP tài trợ, quà tặng bị loại. Đối tác có thể gửi ngược số Creator đang giữ SP để giỏ của mọi người không trùng nhau.
Lấy giỏ gợi ý. Mọi API Key đều gọi được (mode live_hot chỉ key đối tác).
Đối tác báo số Creator đang giữ từng SP ⇒ giỏ hạ hạng SP đã đông người live.
Xem → 📈Đối tác gửi số bán qua Live / Video theo SP — nguồn của mode live_hot.
Đối tác gửi top SP TikTok Shop VN — nguồn của mode social_gap.
Copy toàn bộ tài liệu dạng text rồi dán vào ChatGPT / Claude / Gemini để AI viết code gọi API giúp bạn.
/live/cart-suggest.phpGET | POST https://data.addlivetag.com/live/cart-suggest.php
Key gửi qua header X-API-Key (khuyên dùng) hoặc tham số key. Lấy key ở addlivetag.com → API Key. POST nhận form hoặc JSON — dùng POST JSON khi exclude_item_ids dài.
| Tham số | Mặc định | Ý nghĩa |
|---|---|---|
| mode | hot | hot = bán chạy 30 ngày · rising = đang tăng tốc · commission = giá × hoa hồng cao · live_hot = bán nhiều qua Live (chỉ key đối tác, số mẫu) · social_gap = đang nổ bên TikTok Shop mà Shopee Live còn ít người bán (chỉ key đối tác). |
| q | — | Từ khoá, ≤ 200 ký tự. Có dấu thì khớp đúng dấu trước, thiếu mới nới sang không dấu. |
| cat_id | — | Ngành cấp 1, nhiều giá trị cách nhau dấu phẩy. |
| price_min / price_max | 20000 / — | Khoảng giá (đ). Mặc định bỏ SP dưới 20.000đ. |
| commission_min | — | 0.1 hoặc 10 đều là 10%. |
| sales_min | — | Ngưỡng đã bán luỹ kế. Nâng ngưỡng làm tỉ lệ SP có số 30 ngày (coverage) tăng. |
| limit | 100 | 1–500. |
| max_per_shop | 3 | Tối đa số SP mỗi shop. |
| exclude_item_ids | — | item_id cách nhau dấu phẩy (≤ 1.000) — để đổi giỏ mới. |
| no_cache | 0 | 1 = bỏ cache; tối đa 5 lần/phút/key, quá thì lặng lẽ dùng cache. |
curl -H "X-API-Key: YOUR_API_KEY" \
"https://data.addlivetag.com/live/cart-suggest.php?mode=hot&q=ao+mua&limit=100"
curl -X POST https://data.addlivetag.com/live/cart-suggest.php \
-H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"mode":"rising","cat_id":"11035567","limit":200,"exclude_item_ids":"123,456"}'
{
"status": "success",
"mode": "hot",
"count": 100, "shops": 61, "poolSize": 400, "coverage": 0.83,
"channelSource": "sample",
"dataAsOf": "2026-11-17T04:22:04+07:00",
"generatedAt": "2026-11-17T09:30:00+07:00", "cached": true, "tookMs": 42,
"items": [
{
"itemId": 26607881567, "shopId": 123456, "name": "…", "image": "https://…",
"price": 159000, "commissionRate": 0.12, "estCommission": 19080, "cap": 40000,
"sold7d": 820, "sold30d": 3100, "sales": 52000, "scoreBasis": "sold30d",
"growth": 1.35, "rating": 4.9,
"liveSold30d": 140, "videoSold30d": 22,
"holders": 3, "holdersPenalty": 0.11,
"score": 0.87, "link": "https://shopee.vn/product/123456/26607881567"
}
],
"chunks": [["https://shopee.vn/product/…", "…"], ["…"]]
}
| Field | Ý nghĩa |
|---|---|
| chunks | Link chia sẵn theo nhóm ≤ 100 — dán thẳng vào giỏ live từng nhóm. |
| dataAsOf | Mốc dữ liệu thị trường được làm mới gần nhất (giờ VN). Làm mới mỗi đêm, xong khoảng 04:30 — lấy giỏ sau 05:00 là có số mới. null = chưa có mốc. |
| coverage | Tỉ lệ SP trong giỏ được chấm bằng số bán 30 ngày thật. Thấp thì nên báo người dùng. |
| scoreBasis | sold30d = chấm bằng số 30 ngày; sales = chưa đủ dữ liệu 30 ngày, chấm bằng đã bán luỹ kế (bị trừ nhẹ). Khi đó sold30d/growth = null. |
| growth | Tỉ số tăng trưởng (1 = đi ngang). Chỉ có với SP theo dõi ≥ 30 ngày và bán ≥ 10/30 ngày. |
| commissionRate · estCommission · cap | HH dạng phân số (0.12 = 12%) và ước tính = giá × HH, chưa áp trần. cap = trần HH sàn (40.000đ). Số chính xác từng SP: dùng Product Data Batch. |
| liveSold30d · videoSold30d | Số bán qua Live / Video 30 ngày từ mẫu đơn của các nguồn đối tác (channelSource: "sample"), không phải toàn sàn. null = SP không có trong mẫu (KHÔNG phải 0). Chỉ key đối tác thấy số. |
| holders · holdersPenalty | Số Creator đang giữ SP và mức phạt đã áp. Chỉ key đối tác thấy số; key khác nhận null nhưng thứ hạng vẫn đã áp phạt. |
| tiktokSold7d · tiktokProductId | Chỉ có ở mode social_gap: số bán 7 ngày và product_id của SP TikTok Shop đã ghép với SP này. |
| cached | Pool ứng viên lấy từ cache (1 giờ, tự đổi khi dataAsOf đổi). Điểm và phạt holders luôn tính lại mỗi request. |
count có thể nhỏ hơn limit.score = tổ hợp hạng phần trăm trong pool của: số bán (30 ngày + luỹ kế), tăng trưởng, giá × HH, rating — trọng số khác nhau theo mode; live_hot thêm hạng số bán Live; social_gap thêm hạng số bán TikTok 7 ngày và điểm "khoảng trống" (càng ít người bán Live trên Shopee càng cao). Sau đó nhân (1 − holdersPenalty), với holdersPenalty = min(0,5; 0,08 × ln(1 + holders)) (3 người ≈ 0,11 · 50 người ≈ 0,31), rồi mới áp max_per_shop và cắt limit — SP thay thế được kéo vào giỏ. Trọng số đang hiệu chỉnh theo dữ liệu thật và có thể đổi.
Ba endpoint dưới chỉ nhận key đã được cấp quyền đối tác — key khác nhận 403. Liên hệ addlivetag để được cấp. Chung cho cả ba:
POST body JSON. Thời điểm (asOf, until) nhận unix giây hoặc ISO 8601 có múi giờ.source trong body bị bỏ qua. Nhiều đối tác không ghi đè nhau.rejected, không làm hỏng cả lô. Trường lạ bị bỏ qua.asOf cũ hơn số đang lưu thì không đè.part/parts (tuỳ chọn, 1 ≤ part ≤ parts ≤ 1000) chỉ để bên gửi đối chiếu đủ bộ — partner-sales và tiktok-trends trả lại nguyên trong response; cart-usage nhận nhưng bỏ qua.POST /live/cart-usage.phpcurl -X POST https://data.addlivetag.com/live/cart-usage.php \
-H "X-API-Key: PARTNER_KEY" -H "Content-Type: application/json" \
-d '{"asOf":"2026-11-17T09:00:00+07:00","part":1,"parts":1,
"items":[{"itemId":26607881567,"holders":4,"until":"2026-11-17T13:00:00+07:00","clicks":10,"orders":2}]}'
→ {"status":"success","accepted":1,"rejected":0}
| Field item | Bắt buộc | Ý nghĩa |
|---|---|---|
| itemId | Có | item_id Sàn Cam. |
| holders | Có | Số Creator đang giữ, 0–100.000. 0 = vừa nhả. |
| until | Có | Giữ tới khi nào, ≤ now + 24h. Hết hạn thì tự hết tính. |
| clicks · orders | Tùy chọn | Tổng 7 ngày sau khi lên giỏ — lưu cho vòng phản hồi, chưa dùng chấm điểm. Không gửi thì giữ số cũ. |
≤ 5.000 item/request, body ≤ 1 MB, 30 request/phút. Khuyên gửi cả bộ đang giữ mỗi 5 phút.
POST /live/partner-sales.phpcurl -X POST https://data.addlivetag.com/live/partner-sales.php \
-H "X-API-Key: PARTNER_KEY" -H "Content-Type: application/json" \
-d '{"asOf":"2026-11-17T05:00:00+07:00","part":1,"parts":42,
"items":[{"itemId":26607881567,"liveQty":40,"videoQty":5,"liveOrders":31,"videoOrders":4,"otherOrders":12}]}'
→ {"status":"success","source":"…","part":1,"parts":42,"accepted":1,"rejected":0}
| Field item | Bắt buộc | Ý nghĩa |
|---|---|---|
| itemId | Có | item_id Sàn Cam. |
| liveQty · videoQty | Có | Số lượng bán qua Live / Video trong 30 ngày. |
| liveOrders · videoOrders · otherOrders | Tùy chọn | Số đơn Live / Video / kênh khác (link, social). Thiếu = 0. |
Gửi nguyên ảnh chụp 30 ngày mỗi ngày một lần, chia lô (cùng asOf cho mọi lô), ≤ 5.000 item/request, body ≤ 1 MB, 120 request/phút. asOf trong khoảng [now − 3 ngày, now + 1h]. Số chỉ có hiệu lực 36 giờ kể từ asOf — SP rớt khỏi ảnh mới tự hết tính; bộ gửi hỏng giữa chừng thì các lô chưa gửi vẫn giữ số hôm trước tới hết 36h. Số các nguồn được cộng lại.
POST /live/tiktok-trends.phpcurl -X POST https://data.addlivetag.com/live/tiktok-trends.php \
-H "X-API-Key: PARTNER_KEY" -H "Content-Type: application/json" \
-d '{"asOf":"2026-11-17T05:00:00+07:00","platform":"tiktok_shop_vn","part":1,"parts":1,
"items":[{"productId":"1729384756","title":"Son kem lì …","brand":"X","shopName":"…",
"priceMin":99000,"priceMax":129000,"image":"https://…","commissionRate":0.08,
"sold7d":1200,"sold30d":3000,"soldPrev7d":400}]}'
→ {"status":"success","source":"…","part":1,"parts":1,"accepted":1,"rejected":0}
| Field | Bắt buộc | Ý nghĩa |
|---|---|---|
| platform | Có | Hiện chỉ tiktok_shop_vn. |
| productId · title · sold7d | Có | product_id (chuỗi số), tên SP, đã bán 7 ngày. Thiếu một trong ba ⇒ dòng bị loại. |
| brand · shopName · priceMin · priceMax · image · commissionRate · sold30d · soldPrev7d | Tùy chọn | Sai kiểu thì thành null, không loại cả dòng. image chỉ nhận https://; commissionRate là tỉ lệ 0..1. |
≤ 5.000 item/request, body ≤ 4 MB, 30 request/phút. Khuyên gửi ~2.000 SP bán nhiều nhất 7 ngày, mỗi ngày một lần. Mỗi sáng (~05:40) hệ thống ghép từng SP sang SP Sàn Cam tương ứng theo tên + giá + thương hiệu; chỉ cặp khớp chắc mới vào giỏ social_gap. Ghép tự động nên vẫn có thể lệch phiên bản (vd bản trẻ em / combo).
Lỗi trả {"status":"error","message":"…","reason":"…"} kèm HTTP status:
| HTTP | reason | Xử lý |
|---|---|---|
| 400 | invalid_request | Tham số / body sai (mode lạ, asOf ngoài khoảng, quá 5.000 item, JSON hỏng…). message nói rõ lỗi. |
| 401 | — | Thiếu hoặc sai API Key. |
| 403 | forbidden | Key không có quyền đối tác (mode live_hot/social_gap hoặc 3 endpoint POST). |
| 405 | method_not_allowed | Sai method — 3 endpoint đối tác chỉ nhận POST. |
| 413 | payload_too_large | Body quá giới hạn — chia lô nhỏ hơn. |
| 429 | rate_limited | Quá hạn mức/phút (cart-suggest 60 · cart-usage 30 · partner-sales 120 · tiktok-trends 30). Chờ sang phút sau rồi gửi lại. |
| 502 / 503 | search_unavailable · db_unavailable | Lỗi tạm phía máy chủ — thử lại sau 30–60 giây (có backoff). |
holders của đối tác chỉ hiện với key đối tác; với key thường các trường này là null.