Sàn Cam APIs

📦 Sàn Cam Product Data API

Lấy thông tin sản phẩm Sàn Cam kèm chi tiết hoa hồng. Dữ liệu sản phẩm được cache trong database khoảng 3 giờ trước khi làm mới.

Tham số

Tham số	Bắt buộc	Mô tả
item_id	1 trong 2	ID sản phẩm Sàn Cam (khuyên dùng — nhanh nhất).
url	1 trong 2	URL sản phẩm Sàn Cam: link đầy đủ https://shopee.vn/product/<shop_id>/<item_id>, dạng -i.<shop_id>.<item_id>, hoặc link rút gọn s.shopee.vn / vn.shp.ee. 🐢 Link rút gọn chậm hơn (tốn thêm 1 lượt resolve redirect, giới hạn ~30 req/phút) — ưu tiên item_id, hoặc tự resolve rồi truyền item_id.

Ví dụ request

# Khuyến nghị — nhanh nhất
GET https://data.addlivetag.com/product-data/product-data.php?item_id=1589295236

# Khai tier tài khoản của bạn (tuỳ chọn)
GET https://data.addlivetag.com/product-data/product-data.php?item_id=1589295236&base_rate=8&cap=20000

# Hoặc bằng URL / link rút gọn — CHẬM HƠN, nên tự lấy item_id rồi truyền vào
GET https://data.addlivetag.com/product-data/product-data.php?url=https://s.shopee.vn/2VqAMxdjHo

Ví dụ response

{
  "status": "success",
  "productInfo": {
    "itemId": "1589295236",
    "catId": 100892,
    "catIds": [100630, 100664, 100892],
    "catName": "Nước cân bằng da",
    "catPath": ["Sắc Đẹp", "Nước cân bằng da"],
    "productName": "Tên sản phẩm...",
    "price": 175000,
    "sales": 12345,
    "rating": 4.9,
    "commission": 8750,
    "sellerComFinal": 5250,
    "shopeeComFinal": 3500,
    "isXtra": true,
    "hasSellerCommission": true,
    "hasShopeeCommission": true,
    "isCapped": false,
    "priceStatistics": { ... },
    "dataSource": "api"   // "api" | "db" | "fallback"
  }
}

Hoa hồng được tính thế nào?

• Seller commission: không giới hạn trần, đã áp dụng user rate và thuế.
• Sàn Cam commission: giá trị thô cap tại 40.000 VNĐ, tối đa 8% giá sản phẩm. Tài khoản có cap khác (vd 20.000₫) thì khai bằng tham số cap.

Giới hạn tốc độ

Nguồn dữ liệu	Giới hạn / IP	Khi vượt
API nguồn (Sàn Cam)	~300 request/phút	HTTP 429 — Rate limit exceeded
Cache (database)	~2.000 request/phút
Resolve link rút gọn	~30 request/phút

Chiến lược cache & fallback

• Cache còn hạn → trả từ database (nhanh, giới hạn cao).
• Cache hết hạn → gọi Sàn Cam API và cập nhật cache.
• API lỗi nhưng có dữ liệu cũ → trả bản cache kèm cảnh báo.
• Cả hai nguồn lỗi → response fallback với dữ liệu tối thiểu.

🧺 Sàn Cam Product Data Batch API

Lấy thông tin + hoa hồng của nhiều sản phẩm trong một request. Cùng bộ quy tắc cache, hoa hồng và danh mục với Product Data API — mỗi mục trong kết quả chính là productInfo quen thuộc, nên code cũ tái sử dụng được.

Tham số

Tham số	Bắt buộc	Mô tả
item_ids	1 trong 3	Danh sách item_id. Nhận mảng JSON, item_ids[]=…, hoặc chuỗi ngăn bằng dấu phẩy / xuống dòng / khoảng trắng. Alias: itemIds, ids, item_id.
urls	1 trong 3	Danh sách URL sản phẩm (link gốc). Alias: url. Không hỗ trợ link rút gọn — mỗi link là một lượt resolve, gửi cả trăm link sẽ làm nghẽn. Tự resolve trước, hoặc gửi thẳng item_id.
items	1 trong 3	Mảng hỗn hợp: phần tử là id/url, hoặc object để khai sub_id riêng cho từng sản phẩm.
base_rate · cap	Tùy chọn	Tier tài khoản của bạn, ý nghĩa y như endpoint đơn. Áp cho cả lô.
affid · sub_id · sub1…sub5	Tùy chọn	Dựng affLink. Khai ở cấp request thì áp cho cả lô; khai trong từng phần tử của items thì phần khai riêng thắng.
cache_only	Tùy chọn	1 = tuyệt đối không gọi nguồn, chỉ trả những gì cache có. Không bao giờ chạm quota nguồn. Alias: db_only.
max_api	Tùy chọn	Trần số sản phẩm được gọi nguồn trong request này. Mặc định 20, tối đa 50, 0 = như cache_only.
clear_cache	Tùy chọn	1 = bỏ qua cache, buộc gọi nguồn (vẫn bị chặn bởi max_api).

Tối đa 100 sản phẩm mỗi request. Gửi dư thì phần vượt bị cắt — đối chiếu requested trong response để biết.

Ví dụ request

# Đơn giản nhất
GET https://data.addlivetag.com/product-data/product-data-batch.php?item_ids=1589295236,45703342049

# Chỉ đọc cache — không bao giờ chạm quota nguồn
GET https://data.addlivetag.com/product-data/product-data-batch.php?item_ids=1589295236,45703342049&cache_only=1

# Kèm tier tài khoản + link affiliate
GET https://data.addlivetag.com/product-data/product-data-batch.php?item_ids=1589295236,45703342049&base_rate=8&cap=20000&affid=12345678901&sub1=appX

# POST JSON — nên dùng khi gửi lô lớn
POST https://data.addlivetag.com/product-data/product-data-batch.php
Content-Type: application/json

{"item_ids": [1589295236, 45703342049], "base_rate": 8, "cap": 20000, "max_api": 20}

# sub_id riêng từng sản phẩm (cùng 1 sản phẩm, gửi cho nhiều user)
{"affid": "12345678901", "items": [
  {"item_id": 1589295236, "sub1": "userA", "sub2": "noti_giam_gia"},
  {"item_id": 1589295236, "sub1": "userB", "sub2": "noti_giam_gia"}
]}

Ví dụ response

{
  "status": "success",
  "requested": 3,
  "returned": 3,
  "summary": { "fromCache": 1, "fromApi": 1, "stale": 0, "skipped": 0, "notFound": 1, "invalid": 0 },
  "limits": {
    "maxItems": 100, "maxApiPerRequest": 20, "apiFetched": 1,
    "apiRemaining": 299, "dbRemaining": 1995,
    "sourceRateLimited": false, "sourceCooldownSeconds": 0
  },
  "products": [
    {
      "input": "1589295236",
      "itemId": 1589295236,
      "status": "success",
      "dataSource": "db",
      "productInfo": { ...giống hệt productInfo của endpoint đơn... }
    }
  ]
}

Sáu ô của summary cộng lại đúng bằng requested — mỗi sản phẩm rơi vào đúng một ô, đối soát không cần duyệt cả mảng. Mảng products giữ đúng thứ tự bạn gửi, gửi trùng id vẫn nhận đủ số dòng nhưng chỉ tốn một lượt tra.

Ý nghĩa status của từng sản phẩm

status	Nghĩa	Nên làm gì
success	Dữ liệu dùng được — dataSource là db (cache còn hạn) hoặc api (vừa lấy mới).	Dùng bình thường.
stale	Có dữ liệu nhưng là bản cũ, lượt này chưa làm tươi được.	Dùng tạm, gửi lại id đó ở lượt sau.
skipped	Chưa có cache và cũng chưa kịp gọi nguồn.	Gửi lại ở lượt sau.
not_found	Cache không có, nguồn cũng không trả (hết hàng / không có hoa hồng).	Ngừng hỏi lại liên tục.
error	Đầu vào hỏng — xem reason và message.	Sửa đầu vào phía bạn.

Mỗi mục không phải success đều kèm reason máy đọc được: cache_only, api_budget_exhausted, source_cooldown, source_rate_limited, time_budget_exhausted, api_fetch_failed, db_write_failed, not_cached, cache_expired, commission_unverified, invalid_item_id_or_url, short_link_unsupported.

Giới hạn tốc độ — đếm theo sản phẩm

Nguồn dữ liệu	Giới hạn / IP	Cách tính
Cache (database)	~2.000 sản phẩm/phút	Mỗi sản phẩm trong request = 1 lượt.
API nguồn (Sàn Cam)	~300 sản phẩm/phút	Chỉ sản phẩm thực sự phải gọi nguồn mới bị tính.

Hết quota nguồn giữa chừng không trả HTTP 429 cho cả lô — phần lấy được từ cache vẫn trả bình thường. Chỉ vượt quota cache mới trả 429.

Cập nhật vài nghìn sản phẩm thì làm thế nào

• Nạp lần đầu (kho còn trống): phần lớn sản phẩm chưa có cache nên bị chặn bởi quota nguồn. Chạy rải — mỗi phút vài request, max_api 10–20. Đừng nhồi một lượt.
• Chu kỳ thường xuyên (kho đã đầy): gửi thẳng lô 100 id. Cache 3 giờ nên đa số trả từ db; 5.000 sản phẩm ≈ 50 request, xong trong khoảng 3 phút.
• Chỉ cần đọc, không cần tươi: thêm cache_only=1 — không chạm quota nguồn, không bao giờ bị nghỉ.
• Xử lý kết quả: gom id có status là stale / skipped rồi gửi lại vòng sau, thay vì quét lại từ đầu.

// Vòng quét mẫu
const retry = [];
for (const lo of chunk(allIds, 100)) {
  const r = await fetch('/product-data/product-data-batch.php', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ item_ids: lo, base_rate: 8, cap: 20000, max_api: 20 })
  }).then(r => r.json());

  for (const p of r.products) {
    if (p.status === 'success') save(p.productInfo);
    else if (p.status === 'stale' || p.status === 'skipped') retry.push(p.itemId);
  }
  if (r.limits.sourceCooldownSeconds > 0) await sleep(r.limits.sourceCooldownSeconds * 1000);
}

🔍 Sàn Cam Market Search API

Gõ tên sản phẩm, nhận về toàn cảnh thị trường của từ khoá đó: tổng số sản phẩm, tổng lượt bán, tổng doanh thu, số shop, mức độ cạnh tranh, kèm danh sách sản phẩm sắp theo doanh thu. Tất cả trong một request.

Tham số

Tham số	Bắt buộc	Mô tả
q	Bắt buộc	Từ khoá tìm kiếm. Gõ có dấu hay không dấu đều ra cùng kết quả — "áo mưa" và "ao mua" là một. Tối đa 200 ký tự. Alias: keyword.
limit	Tùy chọn	Số sản phẩm trả về. Mặc định 100, tối đa 200.
offset	Tùy chọn	Bỏ qua bao nhiêu dòng đầu, để phân trang.
sort	Tùy chọn	Cột sắp xếp giảm dần. Nhận revenue_all (mặc định), revenue_30d, sales, sold_30d, price, comm_rate, growth, rating_star. Giá trị lạ thì rơi về mặc định.
price_min · price_max	Tùy chọn	Lọc khoảng giá (VNĐ).
commission_min	Tùy chọn	Lọc hoa hồng tối thiểu, dạng thập phân (0.1 = 10%).
sales_min	Tùy chọn	Lọc lượt bán luỹ kế tối thiểu.
cat_id	Tùy chọn	Lọc theo danh mục cấp 1.
include_gifts	Tùy chọn	1 = tính cả quà tặng không bán riêng vào kết quả. Mặc định loại bỏ vì chúng thổi phồng số tổng quan — xem mục dưới.
no_cache	Tùy chọn	1 = bỏ qua cache, tính lại từ đầu.

Gõ có dấu hay không dấu — hai chế độ khác nhau

Bỏ dấu giúp gõ "ao mua" vẫn ra "áo mưa", nhưng cái giá là "váy" đụng "vây", "vẩy", "vay". Nên API index cả hai dạng và chọn theo cách bạn gõ:

Bạn gõ	query.accentMode	Kết quả
váy (có dấu)	exact_first	Danh sách ưu tiên sản phẩm có đúng chữ "váy" — top không còn dính "vẩy sơn", "vây cá". Số tổng vẫn tính trên mọi biến thể dấu.
vay (không dấu)	loose	Không phân biệt dấu ở đâu cả — váy, vây, vẩy, vay.

Quà tặng không bán riêng — mặc định bị loại

Các mặt hàng gắn nhãn [Quà tặng không bán] vẫn được sàn ghi nhận lượt bán và có giá niêm yết, nên chúng thổi phồng số tổng quan. Đo thật: thị trường "nước tẩy trang" tổng 166,0 tỷ thì 25,4 tỷ (15,3%) đến từ 23 sản phẩm quà tặng trên tổng 3.230 — tức 0,7% số sản phẩm chiếm 15% doanh thu.

API loại chúng khỏi số tổng theo mặc định, và luôn báo lại phần đã loại trong khối giftsExcluded — không im lặng sửa số. Cần lấy lại thì truyền include_gifts=1.

Cách khớp từ khoá

Mặc định khớp theo cụm từ — "áo mưa" chỉ khớp sản phẩm có đúng cụm đó, không khớp "áo thun… mua 2 tặng 1". Nếu cụm từ ra quá ít kết quả, hệ thống tự nới sang "chứa tất cả các từ" rồi "chứa bất kỳ từ nào", và báo lại mức đã dùng trong query.matchMode (phrase · all_words · any_word) kèm cờ query.relaxed. Không bao giờ im lặng đổi nghĩa truy vấn của bạn.

Ví dụ request

# Đơn giản nhất
GET https://data.addlivetag.com/search/market.php?q=áo mưa

# Lọc khoảng giá + sắp theo hoa hồng
GET https://data.addlivetag.com/search/market.php?q=kem chống nắng&price_min=100000&price_max=500000&sort=comm_rate

# Chỉ hàng đã bán được, lấy 200 dòng
GET https://data.addlivetag.com/search/market.php?q=ốp lưng&sales_min=10&limit=200

Ví dụ response

{
  "query": { "raw": "áo mưa", "normalized": "ao mưa", "matchMode": "phrase", "relaxed": false,
             "accentMode": "exact_first" },
  "market": {
    "totalProducts": 12145,
    "totalShops": 2736,
    "totalSold": 170620,
    "totalRevenue": 23691337263,
    "avgPrice": 243579,
    "minPrice": 1000,
    "maxPrice": 8888888,
    "avgCommissionRate": 0.1157,
    "maxCommissionRate": 0.8,
    "productsWithSales": 1889,
    "sellThroughRate": 0.1555,
    "hhi": 0.0269,
    "blueOceanScore": 33.7
  },
  "last30Days": {
    "totalSold": 31266,
    "totalRevenue": 3527920106,
    "trackedProducts": 3065,
    "coverage": 0.2524,
    "note": "Only counts products with 8+ days of history..."
  },
  "giftsExcluded": { "applied": true, "products": 23, "revenue": 25400000000,
                     "note": "Non-sellable gifts excluded from totals..." },
  "topShops": [ { "shopId": 1218336683, "revenue": 3125815122, "products": 6 } ],
  "products": [ {
    "itemId": 25171045245,
    "productName": "Áo mưa đi xe máy đơn nam nữ trong suốt cao cấp 1 người thời trang đẹp",
    "shopName": "dhf18-HN",
    "imageUrl": "https://cf.shopee.vn/file/...",
    "productLink": "https://shopee.vn/product/1218336683/25171045245",
    "price": 146620, "sales": 13891, "sold7d": 6805, "sold30d": 10722,
    "revenueAll": 2036698420, "revenue30d": 1572059640,
    "priceMin": 146620, "priceMax": 189000, "priceCv": 0.0542,
    "growth": 2.72, "daysTracked": 26, "commissionRate": 0.16,
    "shopId": 1218336683, "catId": 100637, "rating": 4.8
  } ],
  "paging": { "limit": 100, "offset": 0, "sort": "revenue_all" },
  "status": "success", "cached": false, "tookMs": 222
}

Các chỉ số phân tích

Trường	Ý nghĩa
market.hhi	Mức độ tập trung thị trường (0–1). Gần 0 = phân tán, nhiều shop chia nhau, dễ chen chân. Gần 1 = vài shop thống trị.
market.blueOceanScore	Điểm 0–100, cao nghĩa là thị trường dễ vào. Tổ hợp: doanh thu trên mỗi sản phẩm, độ phân tán, tỷ lệ bán được, số đối thủ. Ngưỡng đang hiệu chỉnh — dùng để so sánh tương đối giữa các từ khoá, đừng coi là con số tuyệt đối.
market.sellThroughRate	Tỷ lệ sản phẩm có lượt bán > 0. Thấp nghĩa là nhiều hàng đăng lên nhưng không bán được.
products[].priceCv	Độ biến thiên giá của từng sản phẩm (độ lệch chuẩn ÷ giá trung bình). 0 = giá đứng yên. So sánh được giữa hàng rẻ và hàng đắt.
products[].growth	Nhịp bán 7 ngày quy về 30 ngày, chia cho thực tế 30 ngày. >1 = đang tăng tốc, <1 = đang chậm lại.
products[].daysTracked	Số ngày có dữ liệu lịch sử. Càng cao thì các chỉ số xu hướng càng đáng tin.

🎁 Sàn Cam Offers API

Bộ 4 API affiliate của Sàn Cam — cache database 30 phút (riêng Shop Products 10 phút), tự fallback bản cache cũ khi API nguồn lỗi.

Tham số chung cho cả 4 endpoint

Tham số	Bắt buộc	Mô tả
keyword	Tùy chọn	Từ khóa tìm kiếm. Bỏ trống = lấy tất cả. (Shop Products không dùng tham số này.)
sortType	Tùy chọn	Kiểu sắp xếp theo tài liệu affiliate của Sàn Cam. Mặc định 1.
page	Tùy chọn	Trang kết quả. Mặc định 1.
limit	Tùy chọn	Số kết quả mỗi trang, tối đa 50. Mặc định 10.

Hỗ trợ GET/POST, bật CORS. Response chung: status, dataSource ("api" = dữ liệu mới, "db" = từ cache), page / limit / hasNextPage / count, và mảng dữ liệu (offers / products / shops). Khi nguồn tạm lỗi và có bản lưu, thêm stale: true + warning.

1. Sàn Cam Offer — ưu đãi/chiến dịch

GET https://data.addlivetag.com/offers/shopee-offer.php?page=1&limit=10

{
  "status": "success",
  "dataSource": "api",
  "page": 1,
  "limit": 10,
  "hasNextPage": true,
  "count": 10,
  "offers": [
    {
      "name": "Tên chiến dịch...",
      "type": 2,
      "commissionRate": 0.07,
      "image": "https://cf.shopee.vn/file/...",
      "link": "https://shopee.vn/...",
      "startTime": 1750000000,
      "endTime": 1760000000
    }
  ]
}

2. Product Offer — sản phẩm có hoa hồng

GET https://data.addlivetag.com/offers/product-offer.php?keyword=%C3%A1o%20thun&page=1&limit=10

{
  "status": "success",
  "dataSource": "api",
  "page": 1, "limit": 10, "hasNextPage": true, "count": 10,
  "products": [
    {
      "itemId": 43363310862,
      "name": "Áo thun...",
      "link": "https://shopee.vn/product/1608621545/43363310862",
      "image": "https://cf.shopee.vn/file/...",
      "catIds": [100011, 100054],
      "commissionRate": 0.1105,
      "price": 175000,
      "priceMin": 175000,
      "priceMax": 190000,
      "sales": 12345,
      "rating": 4.9,
      "shopId": 1608621545,
      "shopName": "Tên shop...",
      "startTime": 1750000000,
      "endTime": 1760000000
    }
  ]
}

3. Shop Offer — shop/brand có hoa hồng

GET https://data.addlivetag.com/offers/shop-offer.php?keyword=&page=1&limit=10

{
  "status": "success",
  "dataSource": "api",
  "page": 1, "limit": 10, "hasNextPage": true, "count": 10,
  "shops": [
    {
      "shopId": 917660685,
      "name": "Tên shop...",
      "type": [],
      "commissionRate": 0.105,
      "rating": 4.9,
      "remainingBudget": 0,
      "image": "https://cf.shopee.vn/file/...",
      "link": "https://shopee.vn/shop/917660685",
      "startTime": 1761624699,
      "endTime": 32503651199
    }
  ]
}

4. Shop Products — sản phẩm có hoa hồng của một shop

Tham số	Bắt buộc	Mô tả
shopId	Bắt buộc	ID shop cần lấy sản phẩm. Thiếu hoặc ≤ 0 → HTTP 400. Lấy shopId từ Shop Offer, Product Offer hoặc Product Data.
sortType	Tùy chọn	Kiểu sắp xếp. Mặc định 1.
page	Tùy chọn	Trang kết quả. Mặc định 1.
limit	Tùy chọn	Số kết quả mỗi trang, tối đa 50 (API nguồn trả lỗi 11001 khi vượt). Mặc định 10.

GET https://data.addlivetag.com/offers/shop-products.php?shopId=1608621545&page=1&limit=50

{
  "status": "success",
  "dataSource": "api",
  "shopId": 1608621545,
  "shopName": "Tên shop...",
  "page": 1, "limit": 50, "hasNextPage": true, "count": 50,
  "products": [
    {
      "itemId": 43363310862,
      "name": "Áo thun...",
      "link": "https://shopee.vn/product/1608621545/43363310862",
      "image": "https://cf.shopee.vn/file/...",
      "catIds": [100011, 100054],
      "commissionRate": 0.1105,
      "price": 175000,
      "priceMin": 175000,
      "priceMax": 190000,
      "sales": 12345,
      "rating": 4.9,
      "shopId": 1608621545,
      "shopName": "Tên shop...",
      "startTime": 1750000000,
      "endTime": 1760000000
    }
  ]
}

Giới hạn tốc độ (Offers)

Nguồn dữ liệu	Giới hạn / IP	Khi vượt
Cache (database)	~1.000 request/phút	HTTP 429
API nguồn (Sàn Cam)	~100 request/phút