Справочник сервера

The API вашего приложения обращается к собственному серверу с помощью его секретного ключа. Проверьте сессии, перечислите продукты, подтвердите, доставьте и верните платежи, оплатите вознаграждения из вашего пула, отправьте уведомления, проверьте объявления и перечислите общедоступные таблицы.

#Основы

Вызывайте его только с вашего сервера. Ваш ключ — это секрет: никогда не помещайте его на страницу.

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

Маленький помощник, используемый в примерах ниже:

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;
}

#Ключи и режимы

Ключ видит только свое приложение и только свой режим: тестовый ключ видит тестовые сессии, платежи, игроков и рекламу; живой ключ видит живые. Что-то из другого режима — not_found (или valid: false. См. Тест и живой.

#Ошибки

Ошибки отвечают кодом 4xx статуса и телом с error код, иногда с большем количеством полей:

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

Каждый конечный пункт имеет свой. Каждый код находится в Коды ошибок.

#Сессии

#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"
}'

Проверяет сеансовый токен от Lia.init() или Lia.session(), и говорит вам, чьим оно является.

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

{ "session": "lias_eyJhcHAiOi…" }

Ответы 200 по любому пути:

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

{ "valid": false }

Токен действителен, когда Lia его подписал, он'для вашего приложения и вашего ключа'режим, и у него не'не завершено (15 минут после его создания).

#Продукты

#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"

Что ваше приложение продает, по ценам в Lia'ваша запись. Только активные продукты, самые дешевые первыми.

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

#Начисления

Платеж — это один платеж на Lia'ваша зарплата. См. Платежи.

Объект сбора средств:

#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"

Это реальный платеж, оплаченный и чей? Всегда проверяйте здесь перед доставкой: никогда не принимайте страницу'или вебхук'слово для этого.

{
  "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'

Отмечает доставку платежа, один раз, когда вы'вы дали человеку то, что он купил. Безопасно повторять: доставка доставленной оплаты ничего не меняет и отвечает тем же. Нет тела.

{ "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'

Возвращает $LIA человеку, когда вы можете'не доставлять его. Работает с оплаченной или доставленной оплатой. Безопасно повторять: возврат возвращенной оплаты отвечает с ним и ничего не платит дополнительно. Нет тела.

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

Полная цена возвращается человеку'баланс, в режиме реального времени, из Lia'часть и ваша доля. А charge.refunded вебхук отправляется.

#Награды

Смотреть Пулы наград.

#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"
}'

Платит игроку из вашего приложения'ваша наградная копилка, один раз на ключ.

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"
}

Оплачено:

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

Тот же ключ снова ничего не платит и отвечает тем, что платил первый:

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

pool это'осталось в вашем пуле после этого. В тестовом режиме вознаграждение фиктивное: в пуле не осталось'не использован и дневной лимит не't применяется.

A reward.paid вебхук отправляется за каждую выплату (не за дубликаты).

#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"

Что'осталось в вашем пуле вознаграждений, и максимальная сумма, которую один игрок может получить в день.

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

dailyCapPerPlayer это 0 когда'нет дневного лимита. balance является живым пулом, также когда вы спрашиваете с помощью тестового ключа.

#Уведомления

Смотреть Уведомления.

#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"
}'

Отправляет уведомление игроку, который разрешил их. Оно появляется под вашим приложением'имя и открывает ваше приложение с вашим 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" }

Отправлено:

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

pushed это false когда это достигло Lia'колокольчик, но не телефон (человек имеет Lia'ваше отключение).

#Реклама

Смотреть Реклама.

#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"
}'

Была ли эта реклама действительно просмотрена, и кем? Проверьте, прежде чем что-либо давать за вознаграждённое видео.

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 }

Спросите с ключом режима, в котором показывалась реклама: реклама тестового режима (всегда одна из Google'тестовые объявления, никогда не учитываются в доходах) это not_found к живому ключу.

Lia не может'не отметить рекламу как использованную, когда вы ее проверяете, поэтому платите за каждую adId когда вы сами (используйте ad:<adId> как ключ вознаграждения).

#Лобби

Публичные таблицы, которые любой на Lia может найти. Lia сохраняет только список: ваш сервер запускает таблицу. См. Публичные таблицы.

Объект таблицы:

#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
}'

Размещает стол, который'ожидает игроков, или обновляет список (он сохраняет свое место в списке). Повторно добавьте его, когда количество мест изменится.

{ "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 }

Когда taken достигает seats, таблица удаляется из списка, а ответ { "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"

Ваше приложение'открытые таблицы в вашем ключе'режим, новый сначала, до 200: каждый хост's, с блоками, отложенными в сторону (что'для каждого игрока'свой вид).

{ "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"
}'

Сажает игрока за указаный стол, до того как ваш сервер его пустит. Lia отказывает людям, которых заблокировал ведущий, или которые заблокировали ведущего. Когда последнее место занято, стол исчезает из списка.

{ "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'

Извлекает таблицу из списка, когда её игра начинается или закрывается. Безопасно повторять.

{ "removed": true }

removed это false когда это не было'не указано.

#Повторная попытка

Отправить Idempotency-Key заголовок с каждым POST, и тот же самый на каждом повторе этого запроса. Повтор никогда не делает ничего дважды, и отвечает так, как первый запрос.

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

• Любой ключ, который вы хотите, 1 до 128 букв, цифр, _, -, . и :. UUID на операцию это правильно.
• Первый запрос запускается. Если успешно (2xx), его ответ сохраняется на 24 часов, и повторный запрос с тем же ключом и тем же телом получает тот же ответ, с заголовком Idempotent-Replayed: true.
• Отказ ничего не сохраняет (от 4xx или 5xx), поэтому вы можете исправить причину и повторить попытку с тем же ключом.
• Тот же ключ с другим телом это 422 idempotency_key_reused.
• Тот же ключ, пока первый всё ещё работает это 409 idempotency_key_in_use с Retry-After: 1. Повторите, и вы получите первый's ответ.
• Ключи — это ваше приложение'свое, и живые и тестовые ключи держат их отдельно. Один и тот же ключ на другом конце — это другой ключ.

Без заголовка, большинство эндпоинтов всё ещё безопасно повторять: чтение ничего не меняет, доставка и возврат безопасны для повторения, и вознаграждения выплачиваются один раз на key. Уведомления — исключение: без заголовка повторная попытка отправит уведомление снова.

Автоматически переведено. Английский — источник истины. Читать на английском