Skip to content

Tài liệu kỹ thuật

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

API quản lý khoá

Máy chủ cửa hàng của bạn tạo khoá khi có đơn, thu hồi, gia hạn, đổi máy và tra cứu khoá bằng API key lrs_ với scope license:read và license:write.

EndpointPOSThttps://api.lrsvn.com/v1/license/apps/{id}/keys

Gốc là https://api.lrsvn.com/v1/license/…, xác thực bằng Authorization: Bearer lrs_… như mọi API của tổ chức — xem Xác thực & API key. Chỉ gọi từ máy chủ của bạn; API key không bao giờ nằm trong phần mềm giao cho khách.

Quyền

Cách gọiĐọcGhi
API keyscope license:readscope license:write
Phiên đăng nhập (dashboard)Owner, Admin, MemberOwner, Admin
  • Xuất CSV mọi khoá đầy đủ: Owner/Admin, hoặc API key có license:write.
  • Chỉ phiên đăng nhập, API key nhận 403 user_session_required: bật dịch vụ, xoay khoá ký, ngừng khoá ký cũ, xoá ứng dụng.
  • Tổ chức chưa bật LR License: 403 license_not_enabled. Tài khoản bị LRS tạm khoá: vẫn đọc được, mọi thao tác ghi trả 423 license_suspended.

Mọi yêu cầu ghi (POST, PATCH, DELETE) cần header Idempotency-Key dài 8–128 ký tự — dùng mã đơn hàng để gửi lại không tạo khoá trùng. Xem Giới hạn tần suất.

Yêu cầu

Tạo khoá cho một đơn hàng:

cURL
curl -X POST https://api.lrsvn.com/v1/license/apps/lapp_8kq2m7x4c1/keys \
  -H "Authorization: Bearer $LRS_API_KEY" \
  -H "Idempotency-Key: order-1042-keys" \
  -H "Content-Type: application/json" \
  -d '{ "count": 1, "level": 2, "duration": { "value": 30, "unit": "day" }, "max_devices": 1, "note": "Đơn #1042" }'

Tham số

Tham sốKiểuMô tả
countnumber1–100 khoá mỗi lần, mặc định 1.
levelnumberGói quyền có trong ứng dụng, mặc định gói đầu tiên.
durationobjectThời hạn { "value", "unit" }, unit là minute, hour hoặc day: 1 phút – 36.500 ngày, tính từ lần kích hoạt đầu (khoá chưa dùng không bị trừ thời gian).
duration_secondsnumberCùng thời hạn tính bằng giây, 60 – 3.153.600.000.
duration_daysnumberCũ (vẫn nhận): 1–36.500 ngày. Nên dùng duration.
expires_atstringNgày hết hạn cố định (RFC 3339, ở tương lai). Chỉ gửi một trong duration, duration_seconds, duration_days, expires_at; bỏ cả bốn là khoá vĩnh viễn.
max_devicesnumber1–100 thiết bị, mặc định 1 (chỉ có tác dụng khi ràng buộc hwid).
bindingstringGhi đè cách ràng buộc của ứng dụng: hwid, none, hoặc null/bỏ trống = theo ứng dụng.
max_concurrent_sessionsnumberGhi đè số phiên cùng lúc: 0 (không giới hạn) – 1.000, hoặc null/bỏ trống = theo ứng dụng.
notestringGhi chú tối đa 200 ký tự (ví dụ mã đơn) — tìm lại được bằng ?q=.
keystringKhoá tự đặt, chỉ khi count = 1: tối đa 64 ký tự [A-Za-z0-9_-], ít nhất 12 chữ hoặc số. Bỏ trống thì LRS sinh khoá dạng TIỀNTỐ-XXXX-XXXX-XXXX-XXXX.
filesstring[]Id tệp (lfil_…, tối đa 100) gắn với mọi khoá tạo lần này — khoá tải được các tệp phạm vi "Chỉ khoá được gắn" này. Id không thuộc ứng dụng hoặc đã xoá → 422 fields.files. Xem Tệp tải về.

Phản hồi

HTTP
HTTP/1.1 201 Created

{
  "data": [
    {
      "id": "lkey_9d2m4q7x1c",
      "key": "LRK-7F3K-9QXA-M2D8-T5WN",
      "key_last4": "T5WN",
      "level": 2,
      "level_name": "VIP",
      "duration_seconds": 2592000,
      "duration": { "value": 30, "unit": "day" },
      "duration_days": 30,
      "expires_at": null,
      "max_devices": 1,
      "devices": 0,
      "binding": "hwid",
      "binding_override": null,
      "max_concurrent_sessions": 1,
      "max_sessions_override": null,
      "sessions": 0,
      "status": "unused",
      "revoked_reason": null,
      "note": "Đơn #1042",
      "first_activated_at": null,
      "last_seen_at": null,
      "last_reset_at": null,
      "created_by": { "type": "api_key", "name": "Cửa hàng" },
      "created_at": "2026-10-24T03:15:00Z",
      "updated_at": "2026-10-24T03:15:00Z",
      "files": []
    }
  ]
}

duration_seconds là thời hạn tính từ lần kích hoạt đầu (null cùng expires_at: null = vĩnh viễn); duration là thời hạn đó theo đơn vị lớn nhất chia hết (7.200 giây → { "value": 2, "unit": "hour" }); duration_days (cũ) chỉ có khi thời hạn là số ngày tròn, còn lại null. Lần kích hoạt đầu đặt expires_at = lúc đó + thời hạn.

binding và max_concurrent_sessions là giá trị đang áp (đã tính ghi đè); binding_override, max_sessions_override là ghi đè của khoá (null = theo ứng dụng); sessions là số phiên đang sống; files là các tệp gắn với khoá [{ id, name, scope }] (danh sách, chi tiết và phản hồi tạo đều có).

key đầy đủ chỉ có trong phản hồi tạo khoá. Danh sách và chi tiết luôn trả key: null kèm key_last4; cần xem lại thì gọi …/reveal. status là unused, active, expired hoặc revoked.

Các endpoint khác

EndpointViệc
GET /license/appsScope license:read. Danh sách ứng dụng của tổ chức ({ data }).
PATCH /license/apps/{id}Scope license:write. Sửa ứng dụng, gồm binding (hwid / none), max_concurrent_sessions (0 = không giới hạn), session_overflow (reject / kick_oldest), heartbeat_timeout_seconds (30–600), update_file_id (tệp mà update_required dẫn tới, null = không dùng); gửi kèm expected_updated_at (409 license_app_changed nếu người khác vừa sửa).
GET /license/apps/{id}/filesScope license:read. Tệp tải về và dung lượng của tổ chức — tải bản lên, đổi bản hiện hành, lượt tải: xem Tệp tải về.
GET /license/apps/{id}/keysScope license:read. Danh sách khoá, phân trang { data, meta: { total, page, limit } }. Lọc status, level, q (ghi chú hoặc 4 ký tự cuối), file_id (khoá gắn với tệp đó), page, limit ≤ 100.
GET /license/apps/{id}/keys?key=LRK-…Scope license:read. Tra đúng một khoá theo giá trị đầy đủ (không phân biệt hoa thường, bỏ qua dấu gạch).
GET /license/apps/{id}/keys/{keyId}Scope license:read. Chi tiết khoá kèm device_list, live_sessions (phiên đang sống: id, device_id, hwid, ip, version, created_at, last_seen_at, expires_at) và api_reset_available_at.
GET /license/apps/{id}/keys/{keyId}/revealScope license:read. { id, key } — khoá đầy đủ, Cache-Control: no-store, ghi nhật ký kiểm toán kèm IP, tối đa 30 lần/phút mỗi người hoặc API key.
PATCH /license/apps/{id}/keys/{keyId}Scope license:write. Sửa level, max_devices, note, expires_at (null = bỏ ngày hết hạn), binding, max_concurrent_sessions (null = theo ứng dụng), files (thay cả tập tệp gắn: [] gỡ hết, bỏ trống = giữ nguyên).
POST /license/apps/{id}/keys/{keyId}/revokeScope license:write. Thu hồi, { "reason": "…" } tối đa 200 ký tự; mọi phiên của khoá kết thúc ngay.
POST /license/apps/{id}/keys/{keyId}/restoreScope license:write. Khôi phục khoá đã thu hồi.
POST /license/apps/{id}/keys/{keyId}/extendScope license:write. Gia hạn { "value": 2, "unit": "hour" }, { "seconds": 7200 } hoặc { "days": 30 } (cũ) — 1 phút – 36.500 ngày, tính từ lúc muộn hơn giữa bây giờ và ngày hết hạn hiện tại; khoá chưa kích hoạt thì thời hạn dài thêm (tối đa 36.500 ngày).
POST /license/apps/{id}/keys/{keyId}/reset-devicesScope license:write. Đổi máy: gỡ mọi thiết bị và đóng phiên. Qua API key phải chờ reset_cooldown_hours của ứng dụng giữa hai lần.
DELETE /license/apps/{id}/keys/{keyId}/devices/{deviceId}Scope license:write. Gỡ một thiết bị. Qua API key cũng tính là một lần đổi máy (cùng thời gian chờ).
DELETE /license/apps/{id}/keys/{keyId}Scope license:write. Xoá khoá (204).
DELETE /license/apps/{id}/sessions/{sessionId}Scope license:write. Kết thúc một phiên (204, ghi nhật ký kiểm toán); phần mềm nhận session_revoked ở lần heartbeat/check kế tiếp.
GET /license/apps/{id}/keys/exportScope license:write. CSV mọi khoá đầy đủ khớp bộ lọc (tối đa 50.000 dòng; cột key, level, status, duration_seconds, duration, expires_at, max_devices, devices, note, created_at — duration dạng 2 hour), ghi nhật ký kiểm toán.

Các thao tác trên một khoá trả lại chi tiết khoá sau khi đổi. Danh sách phiên, danh sách chặn, nhật ký và thống kê cũng có endpoint dưới /license/apps/{id}/… (sessions, blocks, events, stats).

Ví dụ nút "Đổi máy" trong trang tài khoản của cửa hàng:

cURL
curl -X POST https://api.lrsvn.com/v1/license/apps/lapp_8kq2m7x4c1/keys/lkey_9d2m4q7x1c/reset-devices \
  -H "Authorization: Bearer $LRS_API_KEY" \
  -H "Idempotency-Key: reset-lkey_9d2m4q7x1c-2026-10-24"

Mã lỗi

HTTPMãKhi nào
400invalid_jsonJSON hỏng, có trường lạ hoặc sai kiểu.
403license_not_enabledTổ chức chưa bật LR License.
403scope_deniedAPI key thiếu license:read / license:write.
403user_session_requiredThao tác chỉ làm được trong dashboard (bật dịch vụ, khoá ký, xoá ứng dụng).
403forbiddenVai trò không đủ (ví dụ Member xuất CSV).
404license_app_not_foundỨng dụng không có hoặc thuộc tổ chức khác.
404license_key_not_foundKhoá không có trong ứng dụng.
404license_device_not_foundThiết bị không thuộc khoá hoặc đã được gỡ.
409license_limit_keysVượt số khoá tối đa của tổ chức.
409license_limit_appsVượt số ứng dụng tối đa của tổ chức.
409license_key_existsKhoá tự đặt đã có trong ứng dụng.
409license_key_revokedThu hồi khoá đã bị thu hồi.
409license_key_not_revokedKhôi phục khoá chưa bị thu hồi.
409license_key_lifetimeGia hạn khoá vĩnh viễn.
409idempotency_conflictCùng Idempotency-Key nhưng nội dung khác.
422validation_errorSai dữ liệu; fields nêu trường lỗi (kể cả thiếu Idempotency-Key).
423license_suspendedTài khoản LR License đang bị LRS tạm khoá.
429license_reset_cooldownĐổi máy qua API key trước khi hết thời gian chờ; xem Retry-After.
429rate_limitedVượt giới hạn (cổng API, hoặc 30 lần xem khoá mỗi phút).
JSON
{
  "code": "validation_error",
  "message": "Vui lòng kiểm tra thông tin đã nhập.",
  "fields": { "count": "Số lượng từ 1 đến 100 khoá mỗi lần." },
  "request_id": "req_4f9c2a7e"
}