Lượt (client API)
Client API của LR Link: tạo lượt, poll và huỷ lượt; câu trả lời ký X-LR-Signature như LR License, kiểm nonce và campaign_id, bảng mã kết quả và giới hạn.
https://api.lrsvn.com/v1/link/runsGốc là https://api.lrsvn.com/v1/link. Ba lệnh, đều POST JSON, không cần API key, thân tối đa 8 KB:
| Lệnh | Thân | Việc |
|---|---|---|
POST /link/runs | campaign_id, nonce, external_user (tuỳ chọn) | Mở lượt mới. |
POST /link/runs/{run_id} | campaign_id, nonce | Lượt lúc này (poll). GET với query ?campaign_id=&nonce= cũng được. |
POST /link/runs/{run_id}/cancel | campaign_id, nonce | Huỷ lượt đang chờ. Lượt đã xong trả nguyên trạng. |
nonce gồm 16–64 ký tự [A-Za-z0-9_-], mới cho mỗi lần gọi.
Yêu cầu
curl -s https://api.lrsvn.com/v1/link/runs \
-H 'Content-Type: application/json' \
-d '{"campaign_id":"lcmp_8kq2m7x4c1","nonce":"n0nce-0123456789ab","external_user":"player-42"}'Phản hồi
{
"campaign_id": "lcmp_8kq2m7x4c1",
"code": "ok",
"completed_at": null,
"devices": ["mobile"],
"expires_at": "2026-10-24T10:30:00Z",
"links": [
{ "clicked": false, "id": "lrl_01", "label": "Trang A", "position": 1, "url": "https://go.example.net/g/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" },
{ "clicked": false, "id": "lrl_02", "label": "Trang B", "position": 2, "url": "https://go.example.net/g/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" }
],
"hub_url": "https://go.example.net/g/r/RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR",
"message": "Thành công.",
"nonce": "n0nce-0123456789ab",
"ok": true,
"poll_after": 3,
"result": null,
"run_id": "lrun_9c2v1x",
"server_time": "2026-10-24T10:00:00Z",
"status": "pending"
}Khi lượt hoàn thành, poll trả status: "completed", completed_at và result:
{
"completed": true,
"run_id": "lrun_9c2v1x",
"external_user": "player-42",
"completed_at": "2026-10-24T10:01:10Z",
"license_key": "GARA-7KQ2-M7X4-C1ZD",
"license_level": 2,
"license_key_id": "lkey_01",
"license_duration_seconds": 86400,
"code": "GIFT-0001"
}Các trường license_* và code chỉ có khi chiến dịch bật hành động tương ứng.
hub_url là trang lượt trên tên miền link: các link theo thứ tự với trạng thái, mỗi link mở trong tab mới. Hiện link này (hoặc mã QR của nó) thay cho từng link bọc nếu muốn. Lượt nào cũng có hub_url giống nhau ở mọi lần poll. Trang lượt không tính lượt mở và không bao giờ có link đích.
Chữ ký
Giống hệt LR License: X-LR-Signature: <kid>=<base64url chữ ký Ed25519 trên đúng byte thân>[, <kid2>=…], ký bằng mọi khoá chưa ngừng của chiến dịch. Ứng dụng chấp nhận câu trả lời khi một chữ ký đúng với khoá đã nhúng và nonce, campaign_id đúng như đã gửi. Mẫu Go, PHP, JavaScript ở Xác minh chữ ký dùng được nguyên, chỉ thay app_id bằng campaign_id. Vector kiểm thử: testdata/link-vectors.json trong gói SDK.
Mã lỗi
| Mã | Có ký | Khi nào |
|---|---|---|
ok | có | Thành công; đọc status. |
campaign_not_found | không | Sai mã chiến dịch — không có khoá để ký; SDK báo invalid_signature. |
campaign_draft / campaign_paused / campaign_suspended | có | Chiến dịch chưa chạy, đang dừng, hoặc bị LRS tạm khoá. |
blocked | có | Mạng của người gọi bị bạn chặn (tab Chặn). |
quota_exceeded | có | Tổ chức đã dùng hết lượt hôm nay (giờ Việt Nam). |
user_limit | có | external_user đã đạt số lượt hoàn thành hôm nay. |
domain_unavailable | có | Tạm thời chưa có tên miền link sẵn sàng; thử lại sau. |
run_not_found | có | Lượt không có hoặc thuộc chiến dịch khác. |
invalid_request | có (422) | Sai trường; fields giải thích. |
rate_limited | không (429) | Vượt giới hạn theo mạng; chờ Retry-After. |
link_busy | không (503) | Máy chủ đang bận; chờ Retry-After. |
Câu trả lời không ký và HTTP khác 200 là lỗi tạm thời (network_error), không bao giờ là thành công.
Giới hạn
Theo mỗi địa chỉ IPv4 hoặc dải IPv6 /64, cấu hình chung của LRS: 20 lượt tạo/phút, 120 lượt poll/phút, 30 lượt mở link/phút. Mỗi tổ chức mặc định 5 chiến dịch, tối đa 10 link mỗi lượt (bể đến 10 000 link mỗi chiến dịch), 2000 lượt mỗi ngày — xem hạn mức ở /app/link.