Bỏ qua đến nội dung

Tài liệu kỹ thuật

Tích hợp LRS trong một buổi chiều.

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.

EndpointPOSThttps://api.lrsvn.com/v1/link/runs

Gố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ệnhThânViệc
POST /link/runscampaign_id, nonce, external_user (tuỳ chọn)Mở lượt mới.
POST /link/runs/{run_id}campaign_id, nonceLượt lúc này (poll). GET với query ?campaign_id=&nonce= cũng được.
POST /link/runs/{run_id}/cancelcampaign_id, nonceHuỷ 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
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

JSON
{
  "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:

JSON
{
  "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
okcóThành công; đọc status.
campaign_not_foundkhôngSai mã chiến dịch — không có khoá để ký; SDK báo invalid_signature.
campaign_draft / campaign_paused / campaign_suspendedcóChiến dịch chưa chạy, đang dừng, hoặc bị LRS tạm khoá.
blockedcóMạng của người gọi bị bạn chặn (tab Chặn).
quota_exceededcóTổ chức đã dùng hết lượt hôm nay (giờ Việt Nam).
user_limitcóexternal_user đã đạt số lượt hoàn thành hôm nay.
domain_unavailablecóTạm thời chưa có tên miền link sẵn sàng; thử lại sau.
run_not_foundcóLượt không có hoặc thuộc chiến dịch khác.
invalid_requestcó (422)Sai trường; fields giải thích.
rate_limitedkhông (429)Vượt giới hạn theo mạng; chờ Retry-After.
link_busykhô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.