Skip to content

Tài liệu kỹ thuật

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

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.

EndpointPOSThttps://api.lrsvn.com/v1/license/client/download

Mỗ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 files ngay trong câu trả lời activate và check, gọi download để 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 viAi 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ắnChỉ 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 key lrs_). 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ới files thay 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} (404 license_file_key_not_attached nế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:

Shell
# 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):

JavaScript
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
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
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" }'
HeaderGiá trị
Content-Typeapplication/json
AuthorizationKhô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-KeyKhô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ểuMô tả
app_idstringBắt buộc. lapp_… của ứng dụng.
noncestringBắt buộc. Mới cho mỗi lần gọi.
sessionstringsession nhận từ activate.
file_idstringChỉ download: id của tệp trong files.

Phản hồi

files:

HTTP
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:

JSON
{
  "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
  }
}
  • url là GET có ký, hết hạn sau 2 phút: gọi download ngay 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: files của activate/check, listFiles(), download(fileId), downloadTo(fileId, path) và downloadFile(fileId, dir) (lưu theo tên tệp; Node; Python download_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ướcEndpointViệc
1POST /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.
2POST /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.
4POST /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.
Shell
# 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:

EndpointViệc
GET /license/apps/{id}/filesScope 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}/keysScope 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}/downloadsScope 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_found200 · 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_paused200 · 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_suspended200 · 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_found200 · 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_invalid200 · 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_expired200 · 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_replaced200 · 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_revoked200 · 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_invalid200 · 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_revoked200 · 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_expired200 · có kýKhoá đã quá expires_at. Xử lý: Từ chối, mời gia hạn với người bán.
invalid_request422 · 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_limited429 · tuỳ trường hợpTheo 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_busy503 · 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: true chỉ có ở loại này.
  • Không có header X-LR-Signature và HTTP khác 200 (429 theo mạng, 503 license_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. Đọc Retry-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.