POST/api/public/ref/users
Gọi khi user đăng ký. Idempotent theo uuid — gọi lại trả cùng kết quả.
Ví dụ curl
curl -s -X POST "https://link.locbox.vn/api/public/ref/users" \
-H "X-Api-Key: $LOCBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"uuid": "1f0b...uuid của app chính",
"referred_by_code": "K7RMD4X",
"clipboard_token": "LOCBOX#K7RMD4X",
"install_referrer": "ref_code=K7RMD4X&utm_source=locbox",
"platform": "android"
}'Response
{
"created": true,
"uuid": "1f0b...",
"ref_code": "T9WQZ2M",
"invite_url": "https://link.locbox.vn/open/invite/T9WQZ2M",
"referred_by": "8ac2...",
"request_id": "..."
}POST/api/public/ref/users/batch
Backfill tối đa 500 user cũ. Trả về mảng kết quả + lỗi từng dòng.
Ví dụ curl
curl -s -X POST "https://link.locbox.vn/api/public/ref/users/batch" \
-H "X-Api-Key: $LOCBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"users": [
{ "uuid": "...", "referred_by_code": "K7RMD4X" },
{ "uuid": "...", "ref_code": "LEGACY7" }
]
}'Response
{ "results": [ ... ], "errors": [ ... ], "request_id": "..." }POST/api/public/ref/match
Deferred attribution sau khi cài app: ưu tiên install_referrer / clipboard, sau đó match fingerprint trong 24h.
Ví dụ curl
curl -s -X POST "https://link.locbox.vn/api/public/ref/match" \
-H "X-Api-Key: $LOCBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"uuid": "...",
"clipboard_token": "LOCBOX#K7RMD4X",
"install_referrer": "ref_code=K7RMD4X",
"screen": "390x844@3",
"timezone": "Asia/Ho_Chi_Minh",
"language": "vi-VN",
"user_agent": "..."
}'Response
{ "matched": true, "ref_code": "K7RMD4X", "confidence": 0.92, "method": "fingerprint" }POST/api/public/ref/events
Ghi nhận mua hàng / nạp tiền. Idempotent theo external_ref.
Ví dụ curl
curl -s -X POST "https://link.locbox.vn/api/public/ref/events" \
-H "X-Api-Key: $LOCBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"uuid": "...",
"event_type": "purchase",
"amount": 250000,
"currency": "VND",
"external_ref": "order_2026_00123"
}'Response
{ "recorded": true, "duplicate": false, "event_id": "...", "beneficiary_uuid": "..." }GET/api/public/ref/summary?uuid=<uuid>
Tổng quan cho 1 user: số lượt mời, số user đã mua, tổng chi tiêu downline, thưởng theo trạng thái.
Ví dụ curl
curl -s "https://link.locbox.vn/api/public/ref/summary?uuid=<uuid>" \
-H "X-Api-Key: $LOCBOX_API_KEY"
Response
{
"invited_count": 12,
"converted_count": 5,
"downline_spend": 4200000,
"reward_total": 0,
"rewards_by_status": { "pending": 0, "approved": 0, "paid": 0, "void": 0 }
}GET/api/public/ref/downline?uuid=<uuid>&page=1&limit=20
Danh sách người được mời (uuid ẩn danh, thời điểm join, tổng chi tiêu).
Ví dụ curl
curl -s "https://link.locbox.vn/api/public/ref/downline?uuid=<uuid>&page=1&limit=20" \
-H "X-Api-Key: $LOCBOX_API_KEY"
Response
{ "page": 1, "limit": 20, "total": 12, "items": [ { "uuid_masked": "1f0b2c3d****9a12", "joined_at": "...", "total_spend": 250000 } ] }GET/api/public/ref/users/<uuid>
Tra cứu ref_code và invite_url của một user.
Ví dụ curl
curl -s "https://link.locbox.vn/api/public/ref/users/<uuid>" \
-H "X-Api-Key: $LOCBOX_API_KEY"
Response
{ "uuid": "...", "ref_code": "T9WQZ2M", "invite_url": "https://link.locbox.vn/open/invite/T9WQZ2M" }