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.

LR Bot — API tích hợp

Gọi LR Bot từ hệ thống của bạn bằng API key: cấp role, báo nhịp theo dõi trạng thái, chạy quy trình qua webhook có chữ ký, liên kết người chơi từ game server.

Các API này chạy trên máy chủ của bạn, không bao giờ trong game client hay trình duyệt. {guildID} là ID server Discord (chuỗi số). Server phải đã thêm LR Bot, và tính năng liên quan phải đang bật (nếu không: 409 bot_module_disabled).

Xác thực

Tạo API key ở /app/settings › API của tổ chức sở hữu server trên LRS, với scope bot:read (đọc) và/hoặc bot:write (ghi), gửi qua Authorization: Bearer lrs_… — xem Xác thực & API key. Khoá của tổ chức khác nhận 404 bot_guild_not_found. Lệnh ghi cần Idempotency-Key (trừ hai lệnh báo nhịp). Phiên đăng nhập web gọi các lệnh này nhận 403 api_key_required.

ViệcLệnhScope
Cấp hoặc gia hạn rolePOST /bot/guilds/{guildID}/role-grantsbot:write
Thu hồi roleDELETE /bot/guilds/{guildID}/role-grantsbot:write
Xem role đã cấpGET /bot/guilds/{guildID}/role-grantsbot:read
Báo nhịp (API key)POST /bot/guilds/{guildID}/monitors/{monitorID}/heartbeatbot:write
Báo nhịp (URL bí mật)POST /bot/heartbeat/{token}—
Chạy quy trìnhPOST /bot/hooks/workflows/{workflowID}chữ ký
Xác nhận mã liên kết của người chơiPOST /bot/guilds/{guildID}/accounts/claimbot:write
Gửi thuộc tính người chơiPOST /bot/guilds/{guildID}/accounts/attributesbot:write

Cấp role từ hệ thống của bạn

Ví dụ: người chơi mua gói VIP trên website của bạn, bạn cấp role VIP 30 ngày. source_ref là mã của bạn cho lần cấp này (1–128 ký tự A-Z a-z 0-9 . _ : - /). Gửi lại cùng source_ref cho cùng người thì gia hạn (200, hạn mới) thay vì tạo bản mới (201).

cURL
curl -s https://api.lrsvn.com/v1/bot/guilds/300000000000000001/role-grants \
  -H "Authorization: Bearer lrs_…" \
  -H "Idempotency-Key: vip-order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "discord_user_id": "200000000000000002",
    "role_id": "400000000000000009",
    "source_ref": "order:1042",
    "expires_at": "2026-12-06T00:00:00Z",
    "reason": "Gói VIP 30 ngày"
  }'
  • Không có expires_at thì role không hết hạn (tối đa 10 năm nếu có).
  • Role được giữ khi còn ít nhất một lần cấp đang hiệu lực (từ bạn, từ người quản lý, từ quy trình…). Hết hạn hay thu hồi lần cấp của bạn không gỡ role nếu nguồn khác vẫn giữ nó; role người đó đã có từ trước khi LR Bot cấp thì bot không bao giờ gỡ.
  • Thu hồi: DELETE /bot/guilds/{guildID}/role-grants?source_ref=order:1042 (thêm &discord_user_id=…&role_id=… để thu hẹp).
  • Hạn mức: external_grants_per_day (429 bot_limit_reached), role_grants đang hiệu lực mỗi server (422). Role nằm trên bot: 422 bot_role_above_bot.

Báo nhịp cho theo dõi trạng thái

Tạo một mục theo dõi kiểu heartbeat trong tính năng theo dõi trạng thái, đặt chu kỳ và thời gian ân hạn. Máy của bạn báo nhịp định kỳ; quá chu kỳ + ân hạn không có nhịp thì tính một lần lỗi, ba lần lỗi liên tiếp thì báo sự cố trong kênh trạng thái, hai lần ổn liên tiếp thì báo đã khôi phục.

Cách 1, URL bí mật (tạo ở mục theo dõi, chỉ hiện một lần; không cần API key):

cURL
curl -s -X POST https://api.lrsvn.com/v1/bot/heartbeat/hb_xxxxxxxxxxxxxxxx

Cách 2, API key bot:write:

cURL
curl -s -X POST https://api.lrsvn.com/v1/bot/guilds/300000000000000001/monitors/{monitorID}/heartbeat \
  -H "Authorization: Bearer lrs_…"

Trả lời { "counted": true, "state": "up" }. Hai nhịp cách nhau dưới 10 giây vẫn được trả lời nhưng chỉ tính một. Tối đa 30 lần mỗi phút cho mỗi mục theo dõi. Hai lệnh này không cần Idempotency-Key.

Chạy quy trình bằng webhook

Tạo quy trình với trình kích hoạt webhook. Bảng điều khiển cho bạn URL và khoá bí mật whsec_… (chỉ hiện một lần, tạo lại được). Thân yêu cầu là một object JSON tối đa 16 KiB; các bước đọc nó bằng {{event.body.<trường>}}.

Chữ ký: X-LRBot-Signature: v1=<hex HMAC-SHA256(khoá, "<timestamp>.<thân yêu cầu>")> với X-LRBot-Timestamp là giây Unix (lệch tối đa 5 phút). Ký đúng từng byte của thân gửi đi.

Shell
body='{"player":"Lan","order":"1042"}'
ts=$(date +%s)
sig=$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$WHSEC" -hex | sed 's/^.* //')
curl -s https://api.lrsvn.com/v1/bot/hooks/workflows/{workflowID} \
  -H "Content-Type: application/json" \
  -H "X-LRBot-Timestamp: $ts" \
  -H "X-LRBot-Signature: v1=$sig" \
  -d "$body"

Trả lời 202 { "run_id": "…", "status": "queued" }; quy trình bị chặn bởi hạn mức hay chống vòng lặp thì status là skipped kèm lý do. Mỗi chữ ký chỉ dùng được một lần (409 bot_webhook_replayed); sai chữ ký hoặc quá 5 phút: 401 bot_webhook_signature. Tối đa 60 lần mỗi phút cho mỗi quy trình.

Liên kết người chơi từ game server

Dùng khi server Discord có nhà cung cấp tài khoản kiểu ứng dụng LR OAuth của tổ chức. Thành viên gõ /connect trong Discord và nhận mã ABCD-EFGH (10 phút, một lần, chỉ server đó), rồi gõ mã trong game. Game server xác nhận:

cURL
curl -s https://api.lrsvn.com/v1/bot/guilds/300000000000000001/accounts/claim \
  -H "Authorization: Bearer lrs_…" \
  -H "Idempotency-Key: claim-7f3a" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ABCD-EFGH",
    "external_id": "<định danh người chơi trong ứng dụng>",
    "display_name": "Lan",
    "attributes": { "vip": true, "faction": "police" }
  }'

external_id phải là người chơi của ứng dụng (đã liên kết tài khoản với ứng dụng hoặc đã đăng nhập bằng LR ID cho tổ chức). Khi thuộc tính đổi (lên VIP, đổi phe), gửi bộ mới; các luật của nhà cung cấp tự cấp hoặc gỡ role:

cURL
curl -s https://api.lrsvn.com/v1/bot/guilds/300000000000000001/accounts/attributes \
  -H "Authorization: Bearer lrs_…" \
  -H "Idempotency-Key: attrs-7f3a-2" \
  -H "Content-Type: application/json" \
  -d '{ "provider_id": "<id nhà cung cấp>", "external_id": "<định danh người chơi>", "attributes": { "vip": false } }'

Tối đa 20 thuộc tính, tên [a-z0-9_], giá trị là chuỗi, số hoặc true/false; bộ mới thay bộ cũ.

Mã lỗi

HTTPcodeKhi nào
403api_key_requiredGọi bằng phiên đăng nhập thay vì API key.
404bot_guild_not_foundServer chưa có LR Bot hoặc thuộc tổ chức khác.
409bot_module_disabledTính năng đang tắt trên server.
410bot_connect_expiredMã liên kết hết hạn hoặc đã dùng.
409bot_account_takenTài khoản game đã liên kết với thành viên khác.
422bot_role_above_botRole nằm trên role của bot.
429bot_limit_reachedVượt hạn mức trong ngày.
401bot_webhook_signatureSai chữ ký hoặc timestamp quá 5 phút.
409bot_webhook_replayedChữ ký đã được dùng.