Tệp tải về
Đăng bản build cho khách có khoá: tải lên nhiều phần, LRS kiểm SHA-256; tệp cho mọi khoá hoặc gắn riêng từng khoá, tải ở /dl hoặc qua SDK.
https://api.lrsvn.com/v1/license/client/downloadMỗi ứng dụng có tối đa 100 tệp (ví dụ "Bản cài đặt", "Bản đồ MLO"); mỗi tệp có nhiều bản và một bản hiện hành — bản khách luôn nhận. Ai có khoá dùng được (chưa thu hồi, chưa hết hạn; chưa kích hoạt cũng được) tải bản hiện hành của các tệp khoá đó được dùng (xem mục Phạm vi và gắn với khoá bên dưới) theo hai đường:
- Trang tải cho khách
https://lrsvn.com/dl/<app_id>: nhập khoá (có reCAPTCHA) → danh sách tệp của khoá, SHA-256, nút Tải về (link riêng 10 phút). Tệp gắn riêng với khoá có nhãn "Riêng cho khoá này". - Phần mềm nhận danh sách
filesngay trong câu trả lời activate và check, gọidownloadđể lấy link có ký 2 phút, và tự kiểm SHA-256 trước khi dùng tệp.
Mọi lượt tải được ghi (kênh client hoặc web, 4 ký tự cuối của khoá, IP rút gọn) và xem ở tab Tệp › Lượt tải của ứng dụng.
Phạm vi và gắn với khoá
Mỗi tệp có một phạm vi (scope):
| Phạm vi | Ai tải được |
|---|---|
all_keys — Mọi khoá (mặc định) | Mọi khoá dùng được của ứng dụng. |
attached — Chỉ khoá được gắn | Chỉ các khoá trong danh sách gắn của tệp. Khoá khác không thấy tệp (cả trên trang tải lẫn trong files), gọi download với id của nó nhận file_not_found. |
Gắn khoá với tệp theo ba cách:
- Khi tạo khoá:
files: ["lfil_…"]trong POST /license/apps/{id}/keys — áp cho mọi khoá của lô (kể cả khoá tạo bằng API keylrs_). Trong dashboard: trường Tệp đính kèm của hộp Tạo khoá. - Khi sửa khoá:
PATCH /license/apps/{id}/keys/{keyId}vớifilesthay cả tập ([]gỡ hết, bỏ trống = giữ). Trong dashboard: mục Tệp đính kèm của ngăn chi tiết khoá. - Từ tệp:
POST /license/apps/{id}/files/{fileId}/keys{ "key_ids": [...] }(1–100 khoá) vàDELETE …/files/{fileId}/keys/{keyId}(404license_file_key_not_attachednếu chưa gắn). Trong dashboard: mục Khoá được gắn của ngăn tệp.
Bản hiện hành thuộc về tệp: tải bản mới lên là mọi khoá được phép nhận bản đó. Đổi phạm vi giữ nguyên danh sách gắn (có tác dụng lại khi về attached). Gỡ khoá khỏi tệp có hiệu lực ngay, kể cả link tải đã cấp (410). Xoá tệp đang gắn khoá trả 409 license_file_attached kèm attached_keys — gửi lại với ?confirm=true để xoá cùng danh sách gắn. Đầu trang tải công khai (GET /license/public/apps/{appId}) chỉ đếm tệp all_keys.
Ví dụ: bán một bản build riêng cho từng khoá
Khách ABC đặt bản dựng riêng (logo, cấu hình của họ). Máy chủ build dùng API key license:write:
# 1. Tạo tệp chỉ khoá được gắn mới tải được.
curl -X POST https://api.lrsvn.com/v1/license/apps/lapp_8kq2m7x4c1/files \
-H "Authorization: Bearer $LRS_API_KEY" \
-H "Idempotency-Key: build-abc-file" \
-H "Content-Type: application/json" \
-d '{ "name": "Bản build riêng — khách ABC", "scope": "attached" }'
# → { "id": "lfil_9ab3c7k2xd", "scope": "attached", "attached_keys": 0, … }
# 2. Tải bản build lên như mục "Tải bản lên" bên dưới (versions → PUT từng phần → complete).
# 3. Tạo khoá cho đơn của khách, gắn luôn tệp.
curl -X POST https://api.lrsvn.com/v1/license/apps/lapp_8kq2m7x4c1/keys \
-H "Authorization: Bearer $LRS_API_KEY" \
-H "Idempotency-Key: order-abc-1" \
-H "Content-Type: application/json" \
-d '{ "count": 1, "level": 2, "note": "Khách ABC", "files": ["lfil_9ab3c7k2xd"] }'
# → { "data": [{ "key": "LRK-…", "files": [{ "id": "lfil_9ab3c7k2xd", "name": "Bản build riêng — khách ABC", "scope": "attached" }], … }] }Phần mềm của khách đọc files sau khi kích hoạt rồi tải và kiểm SHA-256 (SDK Node; Python download_file, C# DownloadFileAsync, C++ download_file):
const res = await lic.activate(key);
if (!res.ok) throw new Error(res.code);
for (const file of res.files ?? []) {
// Chỉ tệp khoá này được tải: tệp "Mọi khoá" + bản build riêng của ABC.
const got = await lic.downloadFile(file.id, "./downloads");
if (!got.ok) console.error(file.name, got.code); // sha256_mismatch, file_not_found…
}Bản build mới cho ABC: tải bản mới lên cùng tệp — lần check kế tiếp files có version_id mới, phần mềm tải lại.
Dung lượng
Mọi bản đang giữ của cả tổ chức đều tính dung lượng, kể cả bản đang tải lên; bản lỗi và bản đã xoá không tính. Mặc định 2 GB mỗi tổ chức và 500 MB mỗi tệp (LRS nâng riêng khi cần) — giá trị hiện hành ở storage của GET /license/apps/{id}/files. Bản tải lên dở quá 24 giờ tự huỷ.
Yêu cầu
Phần mềm lấy danh sách tệp khoá được dùng (chỉ bản hiện hành đã sẵn sàng; cùng dữ liệu với files của activate/check):
curl -X POST https://api.lrsvn.com/v1/license/client/files \
-H "Content-Type: application/json" \
-d '{ "app_id": "lapp_8kq2m7x4c1", "session": "lss_Xr2…", "nonce": "Fl3w8Zq1Kp6tYc0mRb4nVd7s" }'rồi xin link tải một tệp:
curl -X POST https://api.lrsvn.com/v1/license/client/download \
-H "Content-Type: application/json" \
-d '{ "app_id": "lapp_8kq2m7x4c1", "session": "lss_Xr2…", "nonce": "Dl9q2Lx4Wm7tPz1cRv5nYs8k", "file_id": "lfil_3vn8q1k0ze" }'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. Mới cho mỗi lần gọi. |
| session | string | session nhận từ activate. |
| file_id | string | Chỉ download: id của tệp trong files. |
Phản hồi
files:
HTTP/1.1 200 OK
X-LR-Signature: lsk_4h7q2x9m=…
{
"app_id": "lapp_8kq2m7x4c1",
"code": "ok",
"files": [
{
"description": "Bản đầy đủ cho máy chủ FiveM",
"id": "lfil_3vn8q1k0ze",
"name": "PH Garage Script",
"version": {
"created_at": "2026-10-23T03:10:00Z",
"filename": "ph-garage-1.4.2.zip",
"id": "lfv_4h2m8q1x7c",
"label": "1.4.2",
"sha256": "9f2c41d7a0b3e6c58d21f4a97c0e3b51d8a4f2c67e19b05d3c4a8e2f6d5e0b7f",
"size": 192937984
}
}
],
"message": "Khoá hợp lệ.",
"nonce": "Fl3w8Zq1Kp6tYc0mRb4nVd7s",
"ok": true,
"server_time": "2026-10-24T03:15:00Z"
}download:
{
"app_id": "lapp_8kq2m7x4c1",
"code": "ok",
"expires_at": "2026-10-24T03:17:00Z",
"file": { "id": "lfil_3vn8q1k0ze", "name": "PH Garage Script" },
"message": "Khoá hợp lệ.",
"nonce": "Dl9q2Lx4Wm7tPz1cRv5nYs8k",
"ok": true,
"server_time": "2026-10-24T03:15:00Z",
"url": "https://lrsvn.com/lrs-private/license/…?X-Amz-Signature=…",
"version": {
"created_at": "2026-10-23T03:10:00Z",
"filename": "ph-garage-1.4.2.zip",
"id": "lfv_4h2m8q1x7c",
"label": "1.4.2",
"sha256": "9f2c41d7a0b3e6c58d21f4a97c0e3b51d8a4f2c67e19b05d3c4a8e2f6d5e0b7f",
"size": 192937984
}
}urllà GET có ký, hết hạn sau 2 phút: gọidownloadngay trước khi tải, đừng lưu lại hay chia sẻ. Tối đa 30 lần mỗi phút cho một phiên.- Băm SHA-256 những byte tải về và so với
version.sha256(nằm trong câu trả lời đã ký). Lệch thì xoá tệp, không chạy. - SDK chính thức làm sẵn:
filescủaactivate/check,listFiles(),download(fileId),downloadTo(fileId, path)vàdownloadFile(fileId, dir)(lưu theo tên tệp; Node; Pythondownload_to/download_file, C#DownloadToAsync/DownloadFileAsync, C++download_to/download_file) — ghi vào<path>.part, chỉ đổi tên khi kích thước và SHA-256 khớp, lệch trảsha256_mismatch.
Tải bản lên
Từ tab Tệp của ứng dụng trong /app/license (trình duyệt tự băm SHA-256 và gửi từng phần), hoặc từ máy chủ build bằng API key scope license:write:
| Bước | Endpoint | Việc |
|---|---|---|
| 1 | POST /license/apps/{id}/files | { "name": "Bản cài đặt", "description": "…", "scope": "all_keys" } (scope tuỳ chọn: all_keys mặc định hoặc attached) → tệp mới (lfil_…). 409 license_limit_files khi đủ 100 tệp. |
| 2 | POST /license/apps/{id}/files/{fileId}/versions | { filename, size, sha256, label?, content_type?, make_current? } → { version, upload: { part_size, parts: [{ number, size, url }], expires_at } }. size (byte) và sha256 (hex) của cả tệp. Mỗi tệp chỉ một bản đang tải lên: gửi lại cùng sha256 + size → 200 resumed: true, chính bản đó với link mới (gửi tiếp phần còn thiếu); tệp khác → 409 license_upload_in_progress kèm version đang dở (xoá bản đó để huỷ). 422 quá giới hạn mỗi tệp, 409 license_limit_storage quá dung lượng. |
| 3 | (link trong parts) | PUT đúng size byte của từng phần (thường 16 MB, phần cuối nhỏ hơn — đọc size, đừng tự chia) vào url của nó trong 6 giờ, giữ header ETag của câu trả lời; gửi vài phần song song được. Không gửi Authorization. |
| 4 | POST /license/apps/{id}/files/{fileId}/versions/{versionId}/complete | { "parts": [{ "number": 1, "etag": "ETag của phần 1" }, …] } đủ phần, theo thứ tự → bản verifying; LRS băm lại tệp rồi chuyển ready (thành bản hiện hành nếu make_current, mặc định true, hoặc tệp chưa có bản nào) hoặc failed (SHA-256 lệch — tệp bị xoá). 409 license_file_upload_incomplete khi thiếu phần/ETag sai. |
# 2. Khai báo bản mới (sha256sum tính trên máy build).
curl -X POST https://api.lrsvn.com/v1/license/apps/lapp_8kq2m7x4c1/files/lfil_3vn8q1k0ze/versions \
-H "Authorization: Bearer lrs_…" \
-H "Idempotency-Key: build-1.4.3" \
-H "Content-Type: application/json" \
-d '{ "filename": "ph-garage-1.4.3.zip", "size": 195035136, "sha256": "3d91e0c4…", "label": "1.4.3" }'Các thao tác khác:
| Endpoint | Việc |
|---|---|
| GET /license/apps/{id}/files | Scope license:read. { data: [{ id, name, description, scope, attached_keys, current_version, version_count, size }], storage: { used, limit, file_limit } } (byte). attached_keys là số khoá đang gắn. |
| GET /license/apps/{id}/files/{fileId} | Scope license:read. Tệp kèm versions (mới nhất trước; status uploading · verifying · ready · failed, error). Đọc lại tới khi bản rời verifying. |
| PATCH /license/apps/{id}/files/{fileId} | Scope license:write. { name?, description?, scope?, current_version_id? } — chỉ bản ready làm hiện hành được; đổi scope giữ danh sách gắn. |
| POST /license/apps/{id}/files/{fileId}/keys | Scope license:write. { "key_ids": ["lkey_…"] } (1–100 khoá của ứng dụng) → tệp. Khoá đã gắn giữ nguyên. |
| DELETE /license/apps/{id}/files/{fileId}/keys/{keyId} | Scope license:write. Gỡ một khoá → tệp; 404 license_file_key_not_attached. |
| GET /license/apps/{id}/keys?file_id=lfil_… | Scope license:read. Các khoá đang gắn với tệp. |
| DELETE /license/apps/{id}/files/{fileId}/versions/{versionId} | Scope license:write. Xoá một bản (giải phóng dung lượng ngay; cũng là huỷ bản đang tải lên). 409 license_file_version_current với bản hiện hành. |
| DELETE /license/apps/{id}/files/{fileId} | Scope license:write. Xoá tệp cùng mọi bản; ứng dụng đang trỏ update_file_id vào tệp này thôi trỏ. Tệp đang gắn khoá → 409 license_file_attached { attached_keys } trừ khi ?confirm=true. |
| GET /license/apps/{id}/downloads | Scope license:read. Lượt tải, phân trang, lọc file_id, channel (client · web). |
Cập nhật bắt buộc
Chọn Tệp cập nhật trong Cài đặt của ứng dụng (update_file_id của PATCH /license/apps/{id}). Khi phần mềm cũ hơn min_version, init/activate trả update_required kèm update_file_id và download_url — là Link tải bản mới nếu bạn có đặt, còn không thì trang tải https://lrsvn.com/dl/<app_id>. Bản quá cũ không activate được nên không tự download được: hãy mở download_url cho người dùng.
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. |
| file_not_found | 200 · có ký | download: tệp không có, đã xoá, hoặc chưa có bản sẵn sàng làm bản hiện hành. Xử lý: Gọi lại files để lấy danh sách mới; không thử lại cùng file_id. |
| session_invalid | 200 · có ký | Mã phiên không có, hoặc phiên đã đóng bằng end. Xử lý: Gọi lại activate với khoá đã lưu; nếu vẫn từ chối thì dừng. |
| session_expired | 200 · có ký | Quá session_expires_at mà không có check, hoặc — khi khoá có giới hạn phiên — im lặng (không heartbeat/check) quá heartbeat_timeout_seconds. Xử lý: Gọi lại activate (có thể gặp session_limit nếu chỗ đã bị máy khác lấy). Giữ đúng nhịp heartbeat. |
| session_replaced | 200 · có ký | Phiên bị thay: cùng máy kích hoạt lại, hoặc máy khác kích hoạt khi ứng dụng chọn kick_oldest. Xử lý: Dừng vòng heartbeat/check và báo người dùng khoá đang chạy nơi khác. Không tự kích hoạt lại liên tục (hai máy sẽ đẩy nhau). |
| session_revoked | 200 · có ký | Người bán kết thúc phiên, thu hồi hoặc xoá khoá, reset hay gỡ thiết bị, hoặc chặn HWID. Xử lý: Dừng tính năng đang chạy. Chỉ kích hoạt lại khi người dùng chủ động. |
| 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. |
| 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. |
Trang tải cho khách trả 403 license_key_refused cho khoá sai, đã thu hồi, đã hết hạn hoặc IP bị chặn (không nói lý do, chống dò khoá), 429 rate_limited khi một mạng thử quá nhiều lần mỗi phút; link 10 phút hết hạn trả 410 license_download_expired — nhập lại khoá để lấy link mới.
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.