activate — kích hoạt khoá
Gửi khoá bản quyền và mã thiết bị (HWID) để nhận một phiên. Lần kích hoạt đầu tiên bắt đầu thời hạn của khoá theo số ngày; mỗi máy mới chiếm một chỗ thiết bị.
https://api.lrsvn.com/v1/license/client/activateThứ tự kiểm tra: ứng dụng → phiên bản và hash → danh sách chặn → HWID → khoá → hạn mức ngày → chỗ thiết bị (ràng buộc hwid) → số phiên cùng lúc. Máy đã kích hoạt trước đó (cùng HWID) không chiếm thêm chỗ thiết bị và thay phiên cũ của chính nó. Xem Ràng buộc, phiên đồng thời và heartbeat.
Yêu cầu
curl -X POST https://api.lrsvn.com/v1/license/client/activate \
-H "Content-Type: application/json" \
-d '{ "app_id": "lapp_8kq2m7x4c1", "key": "LRK-7F3K-9QXA-M2D8-T5WN", "hwid": "5ec6c161bd363271f7b09facdd5fe8b1a18fc04a0c89daea81fe0a6a44d12dc1", "version": "1.4.2", "nonce": "fJ3k9Lw2xQ7pZr1tVb6nYs0c" }'Header
| Header | Giá trị |
|---|---|
| Content-Type | application/json |
| Authorization | Không gửi. Client API là công khai; gửi kèm một giá trị không phải Bearer lrs_… sẽ bị cổng API từ chối 401. |
| Idempotency-Key | Không cần — gọi lại check bao nhiêu lần cũng được. |
Thân JSON tối đa 8 KB. Trường lạ được bỏ qua (SDK mới hơn có thể gửi thêm trường).
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| app_id | string | Bắt buộc. lapp_… của ứng dụng. |
| nonce | string | Bắt buộc. 16–64 ký tự [A-Za-z0-9_-], mới cho mỗi lần gọi. |
| key | string | Khoá người dùng nhập, tối đa 128 ký tự. Không phân biệt hoa thường; dấu -, _ và khoảng trắng được bỏ qua. |
| hwid | string | Mã thiết bị, tối đa 256 ký tự — xem HWID. Bắt buộc khi khoá ràng buộc hwid; với none chỉ được ghi lại theo phiên. |
| version | string | Phiên bản phần mềm (như init). |
| hash | string | SHA-256 hex của bản dựng (như init). |
Phản hồi
HTTP/1.1 200 OK
X-LR-Signature: lsk_4h7q2x9m=…
{
"app": { "latest_version": "1.4.2" },
"app_id": "lapp_8kq2m7x4c1",
"code": "ok",
"files": [
{
"filename": "ph-garage-1.4.2.zip",
"id": "lfil_3vn8q1k0ze",
"name": "PH Garage Script",
"sha256": "9f2c41d7a0b3e6c58d21f4a97c0e3b51d8a4f2c67e19b05d3c4a8e2f6d5e0b7f",
"size": 192937984,
"version": "1.4.2",
"version_id": "lfv_4h2m8q1x7c"
}
],
"license": {
"binding": "hwid",
"devices": 1,
"expires_at": "2026-11-23T03:15:00Z",
"level": 2,
"level_name": "VIP",
"max_concurrent_sessions": 1,
"max_devices": 1
},
"message": "Khoá hợp lệ.",
"next_heartbeat_in": 20,
"nonce": "fJ3k9Lw2xQ7pZr1tVb6nYs0c",
"ok": true,
"server_time": "2026-10-24T03:15:00Z",
"session": "lss_Xr2…",
"session_expires_at": "2026-10-24T04:15:00Z"
}| Trường | Mô tả |
|---|---|
| session | Mã phiên lss_…. Lưu trong bộ nhớ để gọi heartbeat, check và end; không cần lưu ra đĩa. |
| session_expires_at | Phiên hết hạn nếu không có check trước thời điểm này (thời hạn phiên do người bán đặt, 5 phút – 24 giờ). |
| next_heartbeat_in | Số giây tới lần heartbeat kế tiếp (⅓ heartbeat_timeout_seconds). |
| license.level, level_name | Gói quyền của khoá (ví dụ 1 = Basic, 2 = VIP) — dùng để bật tính năng theo gói. |
| license.expires_at | Hết hạn lúc nào (chính xác tới giây); null là vĩnh viễn. Khoá theo thời hạn (phút, giờ hoặc ngày) được đặt mốc này ở lần kích hoạt đầu: lúc kích hoạt + thời hạn. |
| license.binding | hwid hoặc none — cách ràng buộc đang áp cho khoá (đã tính ghi đè của khoá). |
| license.max_devices, devices | Số chỗ thiết bị và số máy đang giữ chỗ; null khi binding là none. |
| license.max_concurrent_sessions | Số phiên cùng lúc của cả khoá; 0 là không giới hạn. |
| files | Tệp khoá này được tải: bản hiện hành sẵn sàng của mọi tệp phạm vi "Mọi khoá" và các tệp gắn với khoá — [{ id, name, version (nhãn), version_id, filename, size, sha256 }], rỗng khi không có. Nằm trong thân đã ký; tải bằng download theo id. |
Khoá ràng buộc none — không đếm thiết bị:
{
"binding": "none",
"devices": null,
"expires_at": null,
"level": 1,
"level_name": "Cơ bản",
"max_concurrent_sessions": 3,
"max_devices": null
}Khoá đã đủ phiên và ứng dụng chọn reject (có chữ ký). retry_at là lúc phiên im lặng lâu nhất hết hạn nếu nó không gửi heartbeat nữa:
{
"active_sessions": 1,
"app_id": "lapp_8kq2m7x4c1",
"code": "session_limit",
"max_concurrent_sessions": 1,
"message": "Khoá đang chạy đủ số phiên cho phép. Thử lại sau hoặc tắt phiên khác.",
"nonce": "fJ3k9Lw2xQ7pZr1tVb6nYs0c",
"ok": false,
"retry_at": "2026-10-24T03:16:00Z",
"server_time": "2026-10-24T03:15:00Z"
}Một câu từ chối (cũng có chữ ký):
{
"app_id": "lapp_8kq2m7x4c1",
"code": "device_limit",
"message": "Khoá đã kích hoạt đủ số thiết bị cho phép.",
"nonce": "fJ3k9Lw2xQ7pZr1tVb6nYs0c",
"ok": false,
"server_time": "2026-10-24T03:15:00Z"
}Thiếu HWID khi khoá ràng buộc hwid — HTTP 422, có chữ ký:
{
"app_id": "lapp_8kq2m7x4c1",
"code": "hwid_required",
"fields": { "hwid": "Thiếu mã thiết bị." },
"message": "Thiếu mã thiết bị.",
"nonce": "fJ3k9Lw2xQ7pZr1tVb6nYs0c",
"ok": false,
"server_time": "2026-10-24T03:15:00Z"
}Mã lỗi
| Mã | HTTP · ký | Khi nào và cách xử lý |
|---|---|---|
| app_not_found | 200 · không ký | app_id không tồn tại hoặc ứng dụng đã bị xoá — server không có khoá để ký. Xử lý: Coi như chữ ký sai (invalid_signature): không mở phần mềm. Thường do nhúng nhầm app_id. |
| app_paused | 200 · có ký | Người bán đang tạm dừng ứng dụng. Xử lý: Từ chối, hiện thông báo; thử lại sau. |
| app_suspended | 200 · có ký | LRS tạm khoá ứng dụng hoặc tài khoản LR License của người bán. Xử lý: Từ chối, đề nghị người dùng liên hệ người bán. |
| update_required | 200 · có ký | version thấp hơn min_version của ứng dụng. Có latest_version, min_version, download_url (link tải bản mới của ứng dụng; chưa đặt mà có tệp cập nhật thì là trang tải https://lrsvn.com/dl/<app_id>) và update_file_id khi ứng dụng chọn tệp cập nhật. Xử lý: Từ chối, mở download_url để cập nhật — hoặc tải thẳng update_file_id bằng download sau khi có phiên (xem Tệp tải về). |
| integrity_failed | 200 · có ký | Ứng dụng có danh sách integrity_hashes mà hash gửi lên không nằm trong đó (kể cả khi không gửi hash). Xử lý: Từ chối: bản phần mềm bị sửa hoặc chưa khai báo hash bản dựng mới. |
| blocked | 200 · có ký | HWID hoặc IP nằm trong danh sách chặn của ứng dụng. Xử lý: Từ chối. |
| hwid_required | 422 · có ký | activate thiếu hwid khi khoá ràng buộc hwid. Xử lý: Lỗi tích hợp: luôn gửi HWID (xem HWID). |
| key_invalid | 200 · có ký | Khoá sai, trống, đã bị xoá, hoặc không thuộc ứng dụng. Xử lý: Mời nhập lại khoá. Không thử lại tự động (bị tính là dò khoá). |
| key_revoked | 200 · có ký | Người bán đã thu hồi khoá. Mọi phiên của khoá cũng kết thúc. Xử lý: Từ chối, dừng tính năng đang chạy. |
| key_expired | 200 · có ký | Khoá đã quá expires_at. Xử lý: Từ chối, mời gia hạn với người bán. |
| quota_exceeded | 200 · có ký | Tổ chức của người bán đã dùng hết hạn mức lượt gọi trong ngày (theo giờ Việt Nam). Xử lý: Tạm thời: nếu đã có lần check thành công gần đây thì cho chạy tiếp trong thời gian ân hạn, thử lại sau. |
| device_limit | 200 · có ký | Ràng buộc hwid: khoá đã giữ đủ max_devices thiết bị khác. Xử lý: Từ chối, hướng dẫn người dùng xin người bán đổi máy (reset thiết bị). |
| session_limit | 200 · có ký | Khoá đã chạy đủ max_concurrent_sessions phiên và ứng dụng chọn reject. Có active_sessions, max_concurrent_sessions, retry_at. Xử lý: Báo người dùng tắt phiên khác; thử lại sau retry_at (lúc phiên im lặng lâu nhất hết hạn nếu nó không còn chạy). |
| invalid_request | 422 · thường có ký | Trường sai định dạng; fields nêu trường lỗi. Không ký nếu chính app_id sai hoặc JSON hỏng. Xử lý: Lỗi tích hợp: sửa theo fields, không thử lại nguyên văn. |
| rate_limited | 429 · tuỳ trường hợp | Theo mạng (không ký), theo khoá hoặc do dò khoá (có ký) — xem mục Thử lại. Xử lý: Chờ retry_after / Retry-After giây rồi thử lại. |
| license_busy | 503 · không ký | Máy chủ đang bận, không nhận thêm lượt gọi trong 1 giây. Xử lý: Lỗi mạng tạm thời: thử lại sau Retry-After. |
Thử lại
Phân biệt hai loại câu trả lời trước khi đọc code:
- Có chữ ký hợp lệ (HTTP 200, 422, 429 theo khoá): đây là kết luận của LRS. Làm theo bảng mã lỗi;
ok: truechỉ có ở loại này. - Không có header
X-LR-Signaturevà HTTP khác 200 (429 theo mạng, 503license_busy, 502 của cổng API, mất mạng): coi lànetwork_error— không bao giờ là thành công, cũng không phải lý do khoá người dùng. ĐọcRetry-After(giây) rồi thử lại với nonce mới. - HTTP 200 không có chữ ký (
app_not_found) hoặc có header nhưng không chữ ký nào hợp lệ:invalid_signature— từ chối.
Đừng dừng phần mềm ngay khi lỗi mạng. SDK báo kết quả network_error để bạn tự quyết; ví dụ FiveM trong gói Node chỉ dừng sau 3 lần xác thực thất bại liên tiếp và quá 15 phút ân hạn, tính theo server_time đã ký của lần check thành công gần nhất.