Tham chiếu máy chủ

Cái API ứng dụng của bạn gọi máy chủ riêng của nó với khóa bí mật. Xác minh phiên, liệt kê sản phẩm, xác nhận, giao hàng và hoàn tiền, thanh toán phần thưởng từ quỹ của bạn, gửi thông báo, kiểm tra quảng cáo và liệt kê bảng công khai.

#Các nguyên tắc cơ bản

Gọi nó từ máy chủ của bạn chỉ. Khóa của bạn là bí mật: đừng bao giờ đặt nó trong trang của bạn.

curl https://api.lialabs.org/api/apps/v1/pool \
  -H "Authorization: Bearer $LIA_KEY"

Một trợ lý nhỏ được sử dụng trong các ví dụ dưới đây:

const LIA = "https://api.lialabs.org/api/apps/v1";

export async function lia(method, path, body) {
  const res = await fetch(LIA + path, {
    method,
    headers: { Authorization: `Bearer ${process.env.LIA_KEY}`, "Content-Type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const data = await res.json();
  if (!res.ok) throw Object.assign(new Error(data.error), { status: res.status, data });
  return data;
}

#Khóa và chế độ

Một khóa chỉ bao giờ nhìn thấy ứng dụng riêng của nó, và chỉ chế độ riêng của nó: khóa thử nghiệm nhìn thấy các phiên thử nghiệm, thanh toán, người chơi và quảng cáo; khóa live nhìn thấy các phiên live. Một thứ từ chế độ khác là not_found (hoặc valid: false). Xem Kiểm tra và trực tiếp.

#Lỗi

Lỗi trả lời với mã trạng thái 4xx và một nội dung có một error mã, đôi khi với nhiều trường hơn:

{ "error": "pool_empty", "pool": 3.5 }

Mỗi điểm cuối đều liệt kê riêng của nó. Mỗi mã đều ở trong Mã lỗi.

#Phiên

#POST/session/verify

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/session/verify' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "session": "lias_example_session"
}'

Kiểm tra một token phiên đăng nhập từ Lia.init() hoặc Lia.session(), và cho bạn biết ai sở hữu nó.

POST /api/apps/v1/session/verify
Authorization: Bearer lia_live_…
Content-Type: application/json

{ "session": "lias_eyJhcHAiOi…" }

Trả lời 200 bất kể cách nào:

{ "valid": true, "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "mode": "live", "exp": 1761998400000 }

{ "valid": false }

Một mã thông báo hợp lệ khi Lia ký nó, nó'cho ứng dụng của bạn và khóa của bạn'chế độ, và nó không'đã kết thúc (15 phút sau khi được tạo).

#Sản phẩm

#GET/products

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/products' \
  --header "Authorization: Bearer $LIA_KEY"

Điều mà ứng dụng của bạn bán, với giá trong Lia'các bản ghi. Chỉ các sản phẩm đang hoạt động, giá rẻ nhất trước.

{
  "products": [
    { "id": "extra-lives", "name": "3 extra lives", "price": 5, "active": true },
    { "id": "gold-pack", "name": "Gold pack", "price": 25, "active": true }
  ]
}

#Phí

Một khoản thanh toán trên Lia'bảng thanh toán của bạn. Xem Thanh toán.

Đối tượng phí:

#GET/charges/:id

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/charges/id_example' \
  --header "Authorization: Bearer $LIA_KEY"

Khoản phí này có thực sự được thanh toán và thuộc về ai không? Luôn kiểm tra ở đây trước khi giao hàng: đừng bao giờ lấy trang'hoặc một webhook'mà từ để chỉ nó.

{
  "charge": {
    "id": "ch_9b1f4c2e7a0d5b8f3e6a1c4d",
    "playerId": "p_3f9c0a6d1b2e4f5a6b7c",
    "productId": "extra-lives",
    "amount": 5,
    "status": "paid",
    "mode": "live",
    "createdAt": 1761998400000,
    "deliveredAt": null,
    "refundedAt": null
  }
}

#POST/charges/:id/deliver

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/charges/id_example/deliver' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Idempotency-Key: example-request-1'

Ghi nhận một khoản phí đã được giao, một khi bạn'đã trao cho người đó những gì họ đã mua. An toàn để lặp lại: việc giao hàng một khoản phí đã giao không thay đổi gì và trả lời như nhau. Không có cơ thể.

{ "charge": { "id": "ch_9b1f…", "status": "delivered", "deliveredAt": 1761998405000, "…": "…" } }

#POST/charges/:id/refund

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/charges/id_example/refund' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Idempotency-Key: example-request-1'

Trả lại $LIA cho người đó, khi bạn có thể'để giao nó. Làm việc với phí được trả hoặc phí đã giao. An toàn để lặp lại: hoàn tiền cho phí đã hoàn tiền sẽ trả lại và không trả thêm gì nữa. Không có cơ thể.

{ "charge": { "id": "ch_9b1f…", "status": "refunded", "refundedAt": 1761998410000, "…": "…" } }

Giá đầy đủ được hoàn lại cho người'số dư, trong chế độ trực tiếp, ngoài Lia'phần của bạn và phần của bạn. Một charge.refunded webhook được gửi.

#Thưởng

Xem Ngân sách thưởng.

#POST/rewards

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/rewards' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "playerId": "player_example",
  "amount": 1,
  "key": "reward-example-1",
  "reason": "Level completed"
}'

Trả tiền cho người chơi từ ứng dụng của bạn'ngân sách thưởng, một lần mỗi khóa.

POST /api/apps/v1/rewards
Authorization: Bearer lia_live_…
Content-Type: application/json

{
  "playerId": "p_3f9c0a6d1b2e4f5a6b7c",
  "amount": 25,
  "key": "tournament-2026-11-01:p_3f9c0a6d1b2e4f5a6b7c",
  "reason": "Weekly tournament, 1st place"
}

Thanh toán:

{ "status": "paid", "amount": 25, "pool": 975 }

Cùng một khóa lần nữa không trả gì và trả lời bằng những gì khóa đầu tiên đã trả:

{ "status": "duplicate", "amount": 25, "pool": 975 }

pool là gì'bên trái trong quỹ của bạn sau đó. Trong chế độ thử nghiệm, phần thưởng là giả: quỹ'đã sử dụng và giới hạn hàng ngày không't áp dụng.

A reward.paid webhook được gửi cho mỗi phần thưởng được trả (không phải cho các bản sao).

#GET/pool

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/pool' \
  --header "Authorization: Bearer $LIA_KEY"

Cái gì'còn lại trong ví phần thưởng của bạn, và người chơi nhiều nhất có thể nhận được mỗi ngày.

{ "balance": 975, "dailyCapPerPlayer": 50, "mode": "live" }

dailyCapPerPlayer là 0 khi có'không có giới hạn hàng ngày. balance là quỹ đang hoạt động, cũng khi bạn yêu cầu bằng khóa kiểm tra của mình.

#Thông báo

Xem Thông báo.

#POST/notifications

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/notifications' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "playerId": "player_example",
  "text": "Ready for another round?",
  "startParam": "round_2"
}'

Gửi thông báo đến người chơi đã cho phép. Nó hiển thị dưới ứng dụng của bạn'tên và mở ứng dụng của bạn với startParam.

POST /api/apps/v1/notifications
Authorization: Bearer lia_live_…
Content-Type: application/json

{ "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "text": "It's your move against @amara.", "startParam": "match-8k2d" }

Đã gửi:

{ "sent": true, "pushed": true }

pushed là false khi nó đạt đến Lia'chuông nhưng không phải điện thoại (người đó có Lia'tắt thông báo).

#Quảng cáo

Xem Quảng cáo.

#POST/ads/verify

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/ads/verify' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "adId": "ad_example"
}'

Quảng cáo này có thực sự được xem và bởi ai không? Kiểm tra trước khi đưa ra bất kỳ thứ gì cho video được thưởng.

POST /api/apps/v1/ads/verify
Authorization: Bearer lia_live_…
Content-Type: application/json

{ "adId": "ad_8e1c4b0f2a9d47c6b3e15a07" }

{ "adId": "ad_8e1c4b0f2a9d47c6b3e15a07", "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "format": "rewarded", "watched": true, "watchedAt": 1761998400000 }

Hỏi với khóa của chế độ quảng cáo được hiển thị: quảng cáo chế độ thử nghiệm (luôn là một trong Google'thử quảng cáo, không được tính vào doanh thu) là not_found đến khóa live.

Lia không thể'đánh dấu quảng cáo là đã sử dụng khi bạn xác minh nó, vì vậy trả mỗi adId một lần (sử dụng ad:<adId> như khóa phần thưởng).

#Sảnh

Bảng công khai mà bất kỳ ai trên Lia có thể tìm thấy. Lia chỉ giữ danh sách: máy chủ của bạn điều hành bảng. Xem Bảng công khai.

Đối tượng bảng:

#POST/lobby/tables

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/lobby/tables' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "tableId": "table_example",
  "hostPlayerId": "player_example",
  "seats": 2,
  "taken": 1,
  "title": "A friendly game",
  "stake": 1,
  "pot": 1,
  "expiresIn": 1800
}'

Liệt kê một bàn mà'mà đang chờ người chơi, hoặc cập nhật danh sách của nó (nó giữ vị trí của nó trong danh sách). Đăng lại bất cứ khi nào số chỗ thay đổi.

{ "tableId": "t8k2d", "hostPlayerId": "p_3f9c0a6d1b2e4f5a6b7c", "seats": 2, "taken": 1, "title": "Quick game", "stake": 5, "expiresIn": 900 }

{ "listed": true, "tableId": "t8k2d", "seats": 2, "taken": 1, "expiresAt": 1761999300000 }

Khi nào taken tiếp cận seats, bảng được lấy ra khỏi danh sách thay vào đó, và câu trả lời là { "listed": false }.

#GET/lobby/tables

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/lobby/tables' \
  --header "Authorization: Bearer $LIA_KEY"

Ứng dụng của bạn'mở bảng trong khóa của bạn'chế độ, mới nhất trước, lên đến 200: mỗi chủ sở hữu'mà, với các khối được đặt sang một bên (đó'cho mỗi người chơi'giao diện riêng của bạn).

{ "tables": [{ "id": "t8k2d", "game": "your-app", "host": { "name": "amara" }, "seats": 2, "taken": 1, "title": "Quick game", "stake": 5, "pot": 0, "createdAt": 1761998400000, "expiresAt": 1761999300000 }] }

#POST/lobby/tables/:id/sit

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/lobby/tables/id_example/sit' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "playerId": "player_example"
}'

Ghế một người chơi tại bàn đã liệt kê, trước khi máy chủ của bạn cho họ vào. Lia từ chối những người mà chủ bàn chặn hoặc đã chặn chủ bàn. Khi ghế cuối cùng được chiếm, bàn sẽ rời khỏi danh sách.

{ "playerId": "p_8a1e0c4d2b7f9e3a5c6d" }

{ "seated": true, "taken": 2, "seats": 2, "full": true }

#DELETE/lobby/tables/:id

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request DELETE 'https://api.lialabs.org/api/apps/v1/lobby/tables/id_example' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Idempotency-Key: example-request-1'

Lấy bảng ra khỏi danh sách khi trò chơi bắt đầu hoặc khi nó đóng. An toàn để lặp lại.

{ "removed": true }

removed là false khi nó không'được liệt kê.

#Đang thử lại

Gửi một Idempotency-Key tiêu đề với mọi POST, và cùng một khóa lại trên mỗi lần thử lại của yêu cầu đó. Một lần thử lại sau đó sẽ không bao giờ làm gì hai lần, và trả lời như yêu cầu đầu tiên.

POST /api/apps/v1/notifications
Authorization: Bearer lia_live_…
Content-Type: application/json
Idempotency-Key: 6f1c2a9e-0b7d-4c35-9e1a-2d8f4b7c3a10

{ "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "text": "It's your move." }

• Mọi khóa bạn muốn, 1 cho 128 chữ cái, chữ số, _, -, . và :. Một UUID cho mỗi thao tác là đúng.
• Yêu cầu đầu tiên chạy. Nếu nó thành công (2xx), câu trả lời của nó sẽ được giữ trong 24 giờ, và một lần thử lại với cùng khóa và cùng nội dung sẽ nhận lại câu trả lời đó, với tiêu đề Idempotent-Replayed: true.
• Một từ chối không giữ lại gì (4xx hoặc 5xx), vì vậy bạn có thể sửa nguyên nhân và thử lại với cùng một khóa.
• Cùng một khóa với nội dung khác là 422 idempotency_key_reused.
• Cùng một khóa trong khi khóa đầu tiên vẫn đang chạy là 409 idempotency_key_in_use với Retry-After: 1. Thử lại, và bạn sẽ nhận được lần đầu tiên's câu trả lời trên cùng kênh, và câu trả lời thứ hai tải có thể
• Khóa là ứng dụng của bạn'riêng của họ, và thử nghiệm giữ riêng biệt. Cùng một khóa trên endpoint khác là một khóa khác.

Không có tiêu đề, hầu hết các điểm cuối vẫn an toàn để thử lại: các phép đọc không thay đổi gì, việc giao hàng và hoàn tiền an toàn để lặp lại, và phần thưởng chỉ được trả một lần cho key. Thông báo là ngoại lệ: không có tiêu đề, một lần thử lại sẽ gửi lại thông báo.

Được dịch tự động. Tiếng Anh là nguồn tin cậy. Đọc bằng tiếng Anh