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.

Tạo khoá tự động

Tạo khoá LR License từ cửa hàng, bot Discord hay webhook Tebex ngay khi có đơn: POST với API key license:write, thử lại an toàn bằng Idempotency-Key.

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

Khi khách mua phần mềm của bạn, máy chủ cửa hàng (hoặc bot, webhook) gọi endpoint này để tạo khoá rồi gửi cho khách — không cần mở bảng điều khiển. Toàn bộ API quản lý khoá (thu hồi, gia hạn, đổi máy…) ở API quản lý khoá. Endpoint dùng API key có scope license:write: tạo trong Cài đặt → API (nút Tạo khoá API (license:write) ở tab Tổng quan của ứng dụng LR License mở sẵn hộp tạo với quyền này). {id} là mã ứng dụng (app_id, dạng lapp_…).

Yêu cầu

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

Tham số

Thời hạn gửi tối đa một trong duration, duration_seconds, duration_days hoặc expires_at; bỏ trống cả bốn là khoá vĩnh viễn.

Tham sốKiểuMô tả
countnumberSố khoá, 1–100 mỗi lần (mặc định 1).
levelnumberGói quyền của ứng dụng (mặc định gói đầu tiên).
durationobject{ "value", "unit" } với unit là minute, hour hoặc day — tính từ lần kích hoạt đầu, 1 phút – 36.500 ngày. 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ách cũ (số ngày) — vẫn nhận, nên dùng duration.
expires_atstringNgày hết hạn cố định (RFC 3339, ở tương lai) thay cho thời hạn.
max_devicesnumberSố máy dùng chung một khoá, 1–100 (mặc định 1).
notestringGhi chú, tối đa 200 ký tự — nên ghi mã đơn để tra lại.
keystringKhoá tự đặt (chỉ khi count = 1): ít nhất 12 chữ hoặc số, tối đa 64 ký tự.
bindingstringhwid, none hoặc null (theo ứng dụng).
max_concurrent_sessionsnumber0 (không giới hạn) – 1.000, hoặc null (theo ứng dụng).
filesstring[]Id tệp gắn với mọi khoá tạo lần này (bản build riêng cho đơn) — xem Tệp tải về.

Phản hồi

HTTP
HTTP/1.1 201 Created

{
  "data": [
    {
      "id": "lkey_6tq0m3ra8w",
      "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,
      "status": "unused",
      "note": "Tebex #58213",
      "created_by": { "type": "api_key", "name": "Cửa hàng Tebex" }
    }
  ]
}

Khoá đầy đủ (key) chỉ có trong phản hồi này — gửi cho khách ngay. Danh sách và chi tiết khoá về sau chỉ trả key_last4. duration là thời hạn theo đơn vị lớn nhất chia hết (7200 giây → { "value": 2, "unit": "hour" }); duration_days chỉ có khi thời hạn là số ngày tròn.

Thử lại an toàn với Idempotency-Key

Mạng chập chờn, webhook bị gửi lại hay bot khởi động lại đều có thể khiến cùng một đơn được xử lý hai lần. Đặt Idempotency-Key là mã của đơn và giữ nguyên khi thử lại: lần gửi sau nhận lại đúng phản hồi (và đúng khoá) của lần đầu, không tạo khoá thứ hai.

NguồnIdempotency-Key nên dùng
Cửa hàng webMã đơn hàng, ví dụ order-1182.
Bot DiscordMã giao dịch hoặc mã tương tác của lệnh mua, ví dụ discord-1290345.
Webhook TebexMã giao dịch Tebex, ví dụ tebex-58213.

Cùng khoá nhưng thân khác (ví dụ đổi count) trả 409 idempotency_conflict. Quy tắc chung: Giới hạn tần suất.

Ví dụ Node.js

JavaScript
// Máy chủ cửa hàng (Node 18+): tạo một khoá 30 ngày cho đơn vừa thanh toán.
async function createLicenseKey(order) {
  const res = await fetch("https://api.lrsvn.com/v1/license/apps/lapp_8kq2m7x4c1/keys", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.LRS_API_KEY,
      "Idempotency-Key": "order-" + order.id,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      count: 1,
      level: 2,
      duration: { value: 30, unit: "day" },
      note: "Đơn #" + order.id,
    }),
  });
  if (!res.ok) throw new Error("LRS " + res.status + ": " + (await res.text()));
  const { data } = await res.json();
  return data[0].key; // "LRK-…" — gửi cho khách
}

Ví dụ Python

Python
# Bot Discord / webhook Tebex (Python 3, thư viện requests).
import os
import requests

def create_license_key(transaction_id):
    res = requests.post(
        "https://api.lrsvn.com/v1/license/apps/lapp_8kq2m7x4c1/keys",
        headers={
            "Authorization": "Bearer " + os.environ["LRS_API_KEY"],
            "Idempotency-Key": "tebex-" + transaction_id,
        },
        json={"count": 1, "level": 2, "duration": {"value": 2, "unit": "hour"}, "note": "Tebex " + transaction_id},
        timeout=10,
    )
    res.raise_for_status()
    return res.json()["data"][0]["key"]  # "LRK-…"

Giới hạn và hạn mức

  • Mỗi yêu cầu tạo tối đa 100 khoá; yêu cầu qua cổng API chịu giới hạn tần suất chung theo API key và IP — gặp 429 thì chờ theo Retry-After rồi gửi lại cùng Idempotency-Key.
  • Tổng số khoá của tổ chức có hạn mức (xem trang LR License trong bảng điều khiển); vượt hạn mức trả 409 license_limit_keys.

Bảo mật

  • Không nhúng khoá lrs_ vào phần mềm phát hành (script FiveM, tệp .exe, mã phía trình duyệt): ai có khoá đều tạo được khoá bản quyền. Phần mềm của khách chỉ cần app_id và khoá công khai — xem tab Tổng quan của ứng dụng.
  • Chỉ cấp license:write cho khoá dùng để tạo khoá; mỗi cửa hàng hoặc bot một API key riêng để thu hồi độc lập.
  • Lộ khoá: xoay vòng hoặc xoá ngay ở Cài đặt → API. Khoá bản quyền đã tạo vẫn dùng được; thu hồi từng khoá ở tab Khoá nếu cần.

Mã lỗi

HTTPMãKhi nào
400invalid_jsonJSON hỏng, có trường lạ hoặc sai kiểu dữ liệu.
401unauthorizedThiếu, sai, đã thu hồi hoặc hết hạn API key.
403scope_deniedAPI key không có license:write.
403license_not_enabledTổ chức chưa bật LR License.
404license_app_not_foundKhông có ứng dụng này trong tổ chức.
409license_limit_keysVượt hạn mức số khoá của tổ chức.
409license_key_existsKhoá tự đặt đã có trong ứng dụng.
409idempotency_conflictCùng Idempotency-Key nhưng thân yêu cầu khác.
422validation_errorSai dữ liệu nhập, ví dụ fields.duration "Thời hạn từ 1 phút đến 36.500 ngày.".
423license_suspendedLR License của tổ chức đang bị LRS tạm khoá.
429rate_limitedVượt giới hạn tần suất; xem Retry-After.