Lấy đơn hàng, sản phẩm trong đơn, click và hoa hồng của chính các tài khoản affiliate bạn đã thêm trên addlivetag.com — để đối soát, chia hoa hồng cho cộng tác viên, hoàn tiền cho khách, hoặc đổ vào Google Sheet / hệ thống riêng. Chỉ đọc, chỉ thấy tài khoản của chủ key.
Lấy ở addlivetag.com → API Key. Gửi qua header X-API-Key (khuyên dùng) hoặc tham số api_key.
API đọc từ dữ liệu addlivetag đã đồng bộ, không gọi thẳng sàn. Sàn Cam đồng bộ ~3 lượt/ngày (sàn ghi đơn trễ 24–48h); Sàn Đen/Sàn Xanh ~2 phút/lần.
Vượt → HTTP 429 kèm Retry-After. Dùng page_size lớn (≤200) thay vì gọi nhiều trang nhỏ.
Copy toàn bộ tài liệu dạng text rồi dán vào ChatGPT / Claude / Gemini để AI viết code đồng bộ đơn giúp bạn.
GET | POST https://addlivetag.com/api/v1/conversions.php
Một endpoint cho cả 4 nguồn, chọn bằng source. Có 2 kiểu phân trang:
| source | Nguồn | Phân trang |
|---|---|---|
| shopee (mặc định) | Sàn Cam | Theo trang: page, page_size, có total |
| food | Sàn Cam giao đồ ăn | Như trên |
| tiktok | Sàn Đen | Con trỏ (keyset): after_synced, after_id — xem riêng |
| lazada | Sàn Xanh | Con trỏ (keyset) — xem riêng |
YYYY-MM-DD được hiểu theo giờ Việt Nam (from = 00:00:00, to = 23:59:59).| Tham số | Bắt buộc | Ý nghĩa |
|---|---|---|
| type | Tùy chọn | orders (mặc định, 1 dòng/checkout) · items (1 dòng/sản phẩm trong đơn) · clicks. |
| source | Tùy chọn | shopee (mặc định) hoặc food. |
| from · to | Tùy chọn | YYYY-MM-DD hoặc unix. Lọc theo thời điểm đặt (purchase_time); với click là click_time. Bỏ trống = toàn bộ lịch sử. |
| status | Tùy chọn | completed · pending · paid · unpaid · cancelled, hoặc số 1..4. Không áp cho click. Bảng trạng thái. |
| sub_id | Tùy chọn | Khớp chính xác một Sub-ID ở bất kỳ vị trí sub1…sub5. |
| order_id | Tùy chọn | Khớp chính xác mã đơn (order_sn, vd 261024G5NPXCQH) hoặc checkout_id. Chỉ chữ + số; sai định dạng → 400 invalid_order_id. |
| account_id | Tùy chọn | Chỉ lấy 1 tài khoản (id trên addlivetag). Bỏ trống = gộp mọi tài khoản Sàn Cam của bạn. |
| page · page_size | Tùy chọn | Mặc định 1 · 50; page_size tối đa 200. Sắp xếp mới nhất trước. |
| format | Tùy chọn | json (mặc định) hoặc csv (UTF-8 BOM, mở thẳng bằng Excel; chỉ chứa data của trang hiện tại). |
# Sản phẩm trong đơn từ đầu tháng 10, 200 dòng/trang curl -H "X-API-Key: YOUR_API_KEY" \ "https://addlivetag.com/api/v1/conversions.php?type=items&from=2026-10-01&page_size=200" # Tra 1 đơn theo mã curl -H "X-API-Key: YOUR_API_KEY" \ "https://addlivetag.com/api/v1/conversions.php?type=items&order_id=261024G5NPXCQH" # Đơn hoàn thành của 1 Sub-ID, xuất CSV curl -H "X-API-Key: YOUR_API_KEY" -o don.csv \ "https://addlivetag.com/api/v1/conversions.php?status=completed&sub_id=kolA&format=csv"
Khung kết quả (JSON):
{
"ok": true,
"meta": { "type": "items", "page": 1, "page_size": 200, "total": 1209 },
"summary": { … tổng của TOÀN BỘ bộ lọc, không chỉ trang này … },
"data": [ … ]
}
Duyệt hết: tăng page cho tới khi page × page_size ≥ total. Vì đơn mới liên tục được thêm vào đầu danh sách, khi đồng bộ định kỳ nên upsert theo khoá (checkout_id cho orders, order_sn + item_id cho items) thay vì chỉ insert.
{ "aff_id": 503, "checkout_id": "246555853237905",
"purchase_time": 1792856653, "complete_time": 0,
"conversion_status": 1, "status": "Đang xử lý", "status_code": "pending",
"checkout_status": "Pending", "commission_status": "Chưa chốt",
"shopee_affiliate_name": "tenaff", "utm_content": "kolA-summer26-fb-post123-note",
"order_count": 1, "item_qty": 1,
"gmv": "176000", "gross_commission": "7181",
"estimated_total_commission": "6899", "affiliate_net_commission": "6899" }
| Field | Ý nghĩa |
|---|---|
| aff_id | id tài khoản trên addlivetag (là account_id, không phải Affiliate ID của sàn). |
| checkout_id | Mã thanh toán — 1 checkout có thể gồm nhiều đơn (order_count) của nhiều shop. |
| purchase_time | Lúc đặt hàng. |
| complete_time | Lúc đơn hoàn thành; 0 = chưa có mốc. Tính hạn giữ tiền/hoàn tiền theo mốc này và coi 0 là chưa đủ điều kiện — đừng suy từ purchase_time. |
| status · status_code | Trạng thái đơn (nhãn tiếng Việt + mã). Dùng field này để biết đơn hoàn thành/huỷ. |
| commission_status · checkout_status | Trạng thái sàn trả hoa hồng (đã việt hoá / bản gốc). Đơn hoàn thành vẫn có thể là "Chưa chốt" — không dùng làm trạng thái đơn. |
| utm_content | Chuỗi Sub-ID gốc sub1-sub2-sub3-sub4-sub5. |
| gmv | Giá trị đơn tính hoa hồng (VND). |
| estimated_total_commission | Hoa hồng ước tính sau phí MCN (VND) — số bạn thực nhận trước thuế. Bằng affiliate_net_commission. |
| gross_commission | Hoa hồng gộp theo sàn báo (VND). |
type=orders trả về dạng chuỗi số ("176000"); type=items trả số. Luôn ép kiểu số trước khi cộng.{ "order_sn": "261024G5NPXCQH", "checkout_id": "246555853237905",
"purchase_time": 1792856653, "complete_time": 0, "click_time": 1792856628,
"status": "Đã thanh toán", "status_code": "paid", "commission_status": "Chưa chốt",
"affiliate": "tenaff",
"item_id": 51051836249, "shop_id": 4774761, "item_name": "Bỉm đêm cao cấp …",
"image": "https://cf.shopee.vn/file/…", "item_url": "https://addlivetag.com/product/?item_id=51051836249",
"price": 220000, "qty": 1, "order_value": 176000,
"commission": 7040, "mcn_fee": 141,
"utm": "kolA-summer26-fb-post123-note", "sub_id1": "kolA" }
| Field | Ý nghĩa |
|---|---|
| order_sn | Mã đơn hiển thị cho người mua — dùng để đối chiếu với khách. |
| click_time | Lúc khách bấm link dẫn tới đơn. |
| price · qty · order_value | Giá niêm yết, số lượng, giá trị tính hoa hồng sau giảm giá (VND). |
| commission · mcn_fee | Hoa hồng của sản phẩm trước phí MCN và phí MCN (VND). Thực nhận = commission − mcn_fee. |
| utm · sub_id1 | Chuỗi Sub-ID gốc và Sub-ID vị trí 1. |
Khi lọc order_id bằng order_sn, summary tính trên đúng đơn đó (không phải cả checkout).
{ "aff_id": 1, "click_id": "166f29a3b372f1bfbb6ced03372f1cd8", "click_time": 1792773909,
"click_region": "Viet Nam", "sub_id": "kolA-summer26-fb",
"direct_source": "Facebook", "last_external_source": "Facebook" }
Click không phân biệt Sàn Cam / giao đồ ăn — source=food&type=clicks trả cùng dữ liệu click. Lọc sub_id với click là khớp chính xác cả chuỗi sub_id.
Có trong mọi response Sàn Cam, tính trên toàn bộ bộ lọc (from/to/status/sub_id/account…), không phụ thuộc trang:
| Field | Ý nghĩa |
|---|---|
| orders · qty · gmv | Số đơn, số sản phẩm, tổng GMV — gồm cả đơn huỷ. |
| orders_cancelled · qty_cancelled · gmv_cancelled | Phần huỷ trong các số trên. Sàn không tính đơn huỷ, nên muốn khớp số của sàn thì lấy tổng trừ phần huỷ. |
| estimated_total_commission | Tổng hoa hồng ước tính sau phí MCN. |
| estimated_total_commission_with_mcn | Tổng trước phí MCN. Phí MCN = with_mcn − estimated_total_commission. |
| gross_commission | Tổng hoa hồng gộp. |
| clicks · conversion_rate | Số click trong khoảng và tỉ lệ đơn/click (%). Click chỉ đồng bộ được một phần nên tỉ lệ có thể > 100%. Cả hai là null khi tra theo order_id. |
| status_code | status | Lọc bằng | Ghi chú |
|---|---|---|---|
| pending | Đang xử lý | pending / 1 | |
| paid | Đã thanh toán | paid (= lọc như pending) | Sàn gộp chung nhóm 1, chỉ khác nhãn. |
| completed | Hoàn thành | completed / 2 | Có complete_time > 0 khi sàn đã trả mốc. |
| cancelled | Huỷ / Không hợp lệ | cancelled / 3 | Không được tính hoa hồng. |
| unpaid | Chờ thanh toán | unpaid / 4 |
source=tiktok và source=lazada trả danh sách thay đổi theo thứ tự đồng bộ (synced_at), không theo ngày đặt. Mỗi lần đơn đổi trạng thái/hoa hồng nó sẽ xuất hiện lại phía sau con trỏ — nên cách dùng chuẩn là: lưu next, lần sau gọi tiếp từ đó và upsert theo mã đơn. Không có from/to, type, status, page ở hai nguồn này.
| Tham số | Ý nghĩa |
|---|---|
| after_synced · after_id | Con trỏ, mặc định 0 (từ đầu). Lấy nguyên giá trị trong next của lần gọi trước. |
| limit | Số dòng, 1–500, mặc định 200. |
| sub2 | Khớp chính xác Sub-ID vị trí 2. |
| order_id | Khớp chính xác mã đơn (trả mọi SKU của đơn). |
| account_id | Chỉ lấy 1 tài khoản của sàn đó. |
# Lần đầu
curl -H "X-API-Key: YOUR_API_KEY" "https://addlivetag.com/api/v1/conversions.php?source=tiktok&limit=500"
# → { "ok":true, "meta":{"type":"tiktok_orders","count":500,"limit":500,"has_more":true},
# "next":{"after_synced":1792901189,"after_id":6760267}, "data":[…] }
# Lần sau: gọi tiếp từ next, lặp tới khi has_more = false; lưu next lại cho lượt đồng bộ sau
curl -H "X-API-Key: YOUR_API_KEY" \
"https://addlivetag.com/api/v1/conversions.php?source=tiktok&limit=500&after_synced=1792901189&after_id=6760267"
status chung cho cả hai: 1 chờ · 2 hoàn thành · 3 huỷ/hoàn tiền. Tiền là chuỗi thập phân (vd "34224.0000", VND).
| Field | Ý nghĩa |
|---|---|
| order_id · sku_id · product_id · product_name | Khoá upsert: order_id + sku_id. |
| sub_id · sub1…sub4 | Tag gốc và từng vị trí. |
| quantity · refunded_quantity · fully_refunded | Số lượng, số đã hoàn, cờ hoàn toàn bộ (0/1). |
| est_commission · actual_commission · currency | Hoa hồng ước tính / thực tế. actual_commission = null = chưa đối soát. |
| settlement_status | Trạng thái gốc của sàn (vd REFUNDED). |
| create_time · settled_at · synced_at | Lúc đặt · lúc đối soát (0 = chưa) · lúc addlivetag ghi nhận thay đổi. |
| Field | Ý nghĩa |
|---|---|
| order_id · sub_order_id · sku · sku_name | Khoá upsert: sub_order_id + sku. |
| sub1…sub6 | Sub-ID từng vị trí. |
| order_amt · est_payout | Giá trị đơn và hoa hồng ước tính (VND). |
| lzd_status | Trạng thái gốc: Fulfilled = mới xác minh thanh toán (vẫn là chờ), Delivered = hoàn thành, Returned/Rejected = huỷ. |
| conversion_time · fulfilled_time · delivered_time · returned_time · synced_at | Các mốc thời gian (0 = chưa có). |
| error | HTTP | Xử lý |
|---|---|---|
| invalid_api_key · unauthorized | 401 | Sai key — xem lại trang API Key. |
| invalid_order_id | 400 | order_id chứa ký tự ngoài chữ + số. |
| rate_limited | 429 | Quá 60 request/phút/key. Chờ theo Retry-After. |
| server_error | 500 | Lỗi phía addlivetag — báo lại kèm URL đã gọi (che key). |
Không có tài khoản nào của sàn đó → vẫn ok:true với data rỗng.