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.

heartbeat — giữ phiên

Tín hiệu nhẹ giữ phiên sống giữa các lần check. Khi có giới hạn phiên, phiên im lặng quá thời gian chờ sẽ hết hạn và nhường chỗ. Không tính vào hạn mức ngày.

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

Heartbeat chỉ cập nhật "lần cuối thấy" của phiên và kiểm tra khoá còn hiệu lực (chưa thu hồi, chưa hết hạn — so tới giây, nên khoá hết hạn giữa phiên trả key_expired — chưa bị xoá). Nó không đọc lại thiết bị hay danh sách chặn như check, và không tính vào hạn mức ngày của tổ chức (được đếm riêng).

Yêu cầu

cURL
curl -X POST https://api.lrsvn.com/v1/license/client/heartbeat \
  -H "Content-Type: application/json" \
  -d '{ "app_id": "lapp_8kq2m7x4c1", "session": "lss_Xr2…", "nonce": "Hb7q2Lx9Wm4tPz0cRv6nYs3k" }'
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.

Phản hồi

HTTP
HTTP/1.1 200 OK
X-LR-Signature: lsk_4h7q2x9m=…

{
  "app_id": "lapp_8kq2m7x4c1",
  "code": "ok",
  "message": "Khoá hợp lệ.",
  "next_heartbeat_in": 20,
  "nonce": "Hb7q2Lx9Wm4tPz0cRv6nYs3k",
  "ok": true,
  "server_time": "2026-10-24T03:15:20Z",
  "session_expires_at": "2026-10-24T04:15:00Z"
}

Heartbeat không dời session_expires_at — chỉ check làm việc đó. Phải xác minh chữ ký như mọi câu trả lời khác.

Lịch gửi

  • Gửi lần đầu sau next_heartbeat_in giây kể từ activate, rồi lặp lại theo next_heartbeat_in của câu trả lời mới nhất (≈ ⅓ heartbeat_timeout_seconds, mặc định 20 giây). Lỡ một hai lần vì mạng chậm vẫn chưa mất phiên.
  • check cũng tính như một heartbeat; vòng heartbeat và vòng check chạy song song.
  • Lỗi mạng (network_error): thử lại sớm sau Retry-After. Phiên chỉ mất khi im lặng quá timeout (và chỉ khi khoá có giới hạn phiên).
  • Tối đa 20 heartbeat mỗi phút cho một phiên; vượt thì nhận 429 rate_limited có ký.
  • SDK chính thức có sẵn vòng lặp này (ví dụ startHeartbeat trong SDK Node) và tự dừng khi phiên đã mất.

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.
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.

Bốn mã session_* nghĩa là phiên đã mất: dừng vòng heartbeat và check, rồi xử lý như bảng trên. Chỉ session_expired và session_invalid nên tự activate lại; session_replaced và session_revoked để người dùng quyết định.

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.