API giỏ Shopee Live

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.

🧭 Bốn endpoint

🤖 Dành cho AI / LLM

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.

🛒 Gợi ý giỏ — /live/cart-suggest.php

GET | 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ố

Tham sốMặc địnhÝ nghĩa
modehothot = 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_max20000 / —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.
limit1001–500.
max_per_shop3Tố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_cache01 = bỏ cache; tối đa 5 lần/phút/key, quá thì lặng lẽ dùng cache.

Ví dụ

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"}'

Kết quả

{
  "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
chunksLink chia sẵn theo nhóm ≤ 100 — dán thẳng vào giỏ live từng nhóm.
dataAsOfMố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.
coverageTỉ 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.
scoreBasissold30d = 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.
growthTỉ 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 · capHH 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 · videoSold30dSố 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 · holdersPenaltySố 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 · tiktokProductIdChỉ 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.
cachedPool ứ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.
💡 Lấy giỏ mới mỗi lần phát cho Creator — đừng giữ một giỏ cả ngày, vì thứ hạng đổi theo số người đang giữ. Bộ lọc hẹp thì count có thể nhỏ hơn limit.

Cách chấm điểm

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.

🤝 API đối tác (gửi dữ liệu về)

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:

1. Số người giữ — POST /live/cart-usage.php

curl -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 itemBắt buộcÝ nghĩa
itemIdCóitem_id Sàn Cam.
holdersCóSố Creator đang giữ, 0–100.000. 0 = vừa nhả.
untilCóGiữ tới khi nào, ≤ now + 24h. Hết hạn thì tự hết tính.
clicks · ordersTùy chọnTổ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.

2. Số bán Live/Video — POST /live/partner-sales.php

curl -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 itemBắt buộcÝ nghĩa
itemIdCóitem_id Sàn Cam.
liveQty · videoQtyCóSố lượng bán qua Live / Video trong 30 ngày.
liveOrders · videoOrders · otherOrdersTùy chọnSố đơ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.

curl -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}
FieldBắt buộcÝ nghĩa
platformCóHiện chỉ tiktok_shop_vn.
productId · title · sold7dCó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 · soldPrev7dTùy chọnSai 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).

⚠️ Mã lỗi

Lỗi trả {"status":"error","message":"…","reason":"…"} kèm HTTP status:

HTTPreasonXử lý
400invalid_requestTham 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.
403forbiddenKey không có quyền đối tác (mode live_hot/social_gap hoặc 3 endpoint POST).
405method_not_allowedSai method — 3 endpoint đối tác chỉ nhận POST.
413payload_too_largeBody quá giới hạn — chia lô nhỏ hơn.
429rate_limitedQuá 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 / 503search_unavailable · db_unavailableLỗi tạm phía máy chủ — thử lại sau 30–60 giây (có backoff).
🔐 Giữ key như mật khẩu. Số Live/Video và 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.