API đơn hàng chuyển đổi

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.

🧰 Trước khi gọi

🔑

API Key

Lấy ở addlivetag.com → API Key. Gửi qua header X-API-Key (khuyên dùng) hoặc tham số api_key.

🔄

Dữ liệu là bản đồng bộ

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.

⏱️

60 request/phút/key

Vượt → HTTP 429 kèm Retry-After. Dùng page_size lớn (≤200) thay vì gọi nhiều trang nhỏ.

🤖 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 đồng bộ đơn giúp bạn.

📮 Endpoint

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:

sourceNguồnPhân trang
shopee (mặc định)Sàn CamTheo trang: page, page_size, có total
foodSàn Cam giao đồ ănNhư trên
tiktokSàn ĐenCon trỏ (keyset): after_synced, after_id — xem riêng
lazadaSàn XanhCon trỏ (keyset) — xem riêng
⏰ Mọi mốc thời gian trả về là unix giây. Ngày truyền vào dạng YYYY-MM-DD được hiểu theo giờ Việt Nam (from = 00:00:00, to = 23:59:59).

🛒 Sàn Cam & giao đồ ăn

Tham sốBắt buộcÝ nghĩa
typeTùy chọnorders (mặc định, 1 dòng/checkout) · items (1 dòng/sản phẩm trong đơn) · clicks.
sourceTùy chọnshopee (mặc định) hoặc food.
from · toTùy chọnYYYY-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ử.
statusTùy chọncompleted · pending · paid · unpaid · cancelled, hoặc số 1..4. Không áp cho click. Bảng trạng thái.
sub_idTùy chọnKhớp chính xác một Sub-ID ở bất kỳ vị trí sub1…sub5.
order_idTùy chọnKhớ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_idTùy chọnChỉ 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_sizeTùy chọnMặc định 1 · 50; page_size tối đa 200. Sắp xếp mới nhất trước.
formatTùy chọnjson (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.

type=orders — 1 dòng / checkout

{ "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_idid tài khoản trên addlivetag (là account_id, không phải Affiliate ID của sàn).
checkout_idMã thanh toán — 1 checkout có thể gồm nhiều đơn (order_count) của nhiều shop.
purchase_timeLúc đặt hàng.
complete_timeLú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_codeTrạ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_statusTrạ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_contentChuỗi Sub-ID gốc sub1-sub2-sub3-sub4-sub5.
gmvGiá trị đơn tính hoa hồng (VND).
estimated_total_commissionHoa 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_commissionHoa hồng gộp theo sàn báo (VND).
💡 Các field tiền của 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.

type=items — 1 dòng / sản phẩm trong đơn

{ "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_snMã đơn hiển thị cho người mua — dùng để đối chiếu với khách.
click_timeLúc khách bấm link dẫn tới đơn.
price · qty · order_valueGiá niêm yết, số lượng, giá trị tính hoa hồng sau giảm giá (VND).
commission · mcn_feeHoa 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_id1Chuỗ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).

type=clicks

{ "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.

summary

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 · gmvSố đơn, số sản phẩm, tổng GMV — gồm cả đơn huỷ.
orders_cancelled · qty_cancelled · gmv_cancelledPhầ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_commissionTổng hoa hồng ước tính sau phí MCN.
estimated_total_commission_with_mcnTổng trước phí MCN. Phí MCN = with_mcn − estimated_total_commission.
gross_commissionTổng hoa hồng gộp.
clicks · conversion_rateSố 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.

Trạng thái đơn

status_codestatusLọc bằngGhi chú
pendingĐang xử lýpending / 1
paidĐã thanh toánpaid (= lọc như pending)Sàn gộp chung nhóm 1, chỉ khác nhãn.
completedHoàn thànhcompleted / 2Có complete_time > 0 khi sàn đã trả mốc.
cancelledHuỷ / Không hợp lệcancelled / 3Không được tính hoa hồng.
unpaidChờ thanh toánunpaid / 4

🎵🧧 Sàn Đen & Sàn Xanh — phân trang con trỏ

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_idCon trỏ, mặc định 0 (từ đầu). Lấy nguyên giá trị trong next của lần gọi trước.
limitSố dòng, 1–500, mặc định 200.
sub2Khớp chính xác Sub-ID vị trí 2.
order_idKhớp chính xác mã đơn (trả mọi SKU của đơn).
account_idChỉ 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).

Sàn Đen (source=tiktok) — 1 dòng / SKU trong đơn

FieldÝ nghĩa
order_id · sku_id · product_id · product_nameKhoá upsert: order_id + sku_id.
sub_id · sub1…sub4Tag gốc và từng vị trí.
quantity · refunded_quantity · fully_refundedSố lượng, số đã hoàn, cờ hoàn toàn bộ (0/1).
est_commission · actual_commission · currencyHoa hồng ước tính / thực tế. actual_commission = null = chưa đối soát.
settlement_statusTrạng thái gốc của sàn (vd REFUNDED).
create_time · settled_at · synced_atLúc đặt · lúc đối soát (0 = chưa) · lúc addlivetag ghi nhận thay đổi.

Sàn Xanh (source=lazada) — 1 dòng / SKU trong sub-order

FieldÝ nghĩa
order_id · sub_order_id · sku · sku_nameKhoá upsert: sub_order_id + sku.
sub1…sub6Sub-ID từng vị trí.
order_amt · est_payoutGiá trị đơn và hoa hồng ước tính (VND).
lzd_statusTrạ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_atCác mốc thời gian (0 = chưa có).

⚠️ Mã lỗi

errorHTTPXử lý
invalid_api_key · unauthorized401Sai key — xem lại trang API Key.
invalid_order_id400order_id chứa ký tự ngoài chữ + số.
rate_limited429Quá 60 request/phút/key. Chờ theo Retry-After.
server_error500Lỗ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.

🔐 Giữ key như mật khẩu. Truyền key qua URL sẽ lộ trong log và lịch sử trình duyệt — ưu tiên header. Lỡ lộ thì bấm Tạo key mới ở trang API Key. Cần tạo link thay vì đọc đơn? Xem API tạo link s.shopee.vn.