REST & WebSocket API

Базовый URL: https://api.bluestudz.ru. Разверните раздел, чтобы увидеть заголовки, тело запроса и пример ответа.

Авторизация

Обмен launch-токена лаунчера на игровую сессию и подтверждение владения игрой.

POST/auth/game/launch▾

Выдаёт короткоживущий (5 мин) одноразовый launchToken для запускаемой игры. Вызывается лаунчером — использует его собственную сессию (cookie), не SDK.

Тело запроса

json

{ "gameId": "<game-uuid>" }

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/auth/game/launch \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<launcher-cookie>" \
  -d '{"gameId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

Ответ

json

{ "launchToken": "<jwt, 5 min>" }

Возможные HTTP статусы

200 OK—Токен успешно сгенерирован.

401 Unauthorized—Лаунчер не авторизован.

403 Forbidden—У пользователя нет лицензии на игру.

POST/auth/game/verify▾

Обменивает launchToken на игровой userToken (game_session JWT, 30 мин). Вызывается SDK при старте игры.

Тело запроса

json

{ "launchToken": "<jwt from BLUESTUDZ_LAUNCH_TOKEN>" }

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/auth/game/verify \
  -H "Content-Type: application/json" \
  -d '{"launchToken": "eyJhbGciOi..."}'

Ответ

json

{
  "gameToken": "<jwt, 30 min>",
  "user": { "id": "usr_12345", "nickname": "Alex", "displayName": "Alexander", "role": "User" }
}

Возможные HTTP статусы

200 OK—Обмен успешен, сессия игры открыта.

400 Bad Request—Некорректный или отсутствующий launchToken.

401 Unauthorized—LaunchToken просрочен (старше 5 минут).

POST/sdk/auth/verify▾

Подтверждает владение игрой и валидность игровой сессии. Регистрирует активность игрока (sdkGameActivity).

Тело запроса

json

{
  "gameId": "<game-uuid>",
  "secretToken": "<developer secret>",
  "userId": "<from /auth/game/verify>",
  "userToken": "<gameToken from /auth/game/verify>"
}

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/sdk/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"gameId":"uuid","secretToken":"sec_token","userId":"usr_123","userToken":"eyJhbGciOi..."}'

Ответ

json

{ "success": true }

Возможные HTTP статусы

200 OK—Сессия подтверждена разработчиком.

401 Unauthorized—Невалидный secretToken или userToken.

Друзья и Presence

Список друзей и Rich Presence статус игрока.

GET/sdk/friends▾

Список друзей игрока, доступных для внутриигровых приглашений.

Заголовки

Authorization: Bearer <userToken>
x-bs-gameid: <gameId>

Пример вызова cURL

bash

curl -X GET https://api.bluestudz.ru/sdk/friends \
  -H "Authorization: Bearer <userToken>" \
  -H "x-bs-gameid: <gameId>"

Ответ

json

{ "friends": [{ "id": "usr_99", "nickname": "Friend1", "online": true }] }

Возможные HTTP статусы

200 OK—Список друзей успешно получен.

401 Unauthorized—Истекший токен сессии.

POST/sdk/presence/status▾

Steamworks SetRichPresence-эквивалент. Помечает игрока как активного в игре (виден друзьям как «Играет в <игра>»).

Заголовки

Authorization: Bearer <userToken>
x-bs-gameid: <gameId>

Тело запроса

json

{ "active": true }

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/sdk/presence/status \
  -H "Authorization: Bearer <userToken>" \
  -H "x-bs-gameid: <gameId>" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'

Ответ

json

{ "success": true }

Возможные HTTP статусы

200 OK—Статус успешно обновлен.

Ачивки

Разблокировка достижений, подтверждённая секретным токеном разработчика.

POST/sdk/achievements/unlock▾

Разблокирует ачивку для игрока. Требует secretToken разработчика — игрок не может подделать чужую разблокировку.

Заголовки

Authorization: Bearer <userToken>
x-bs-gameid: <gameId>
x-bs-secrettoken: <developer secret>

Тело запроса

json

{ "achievementId": "first_blood" }

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/sdk/achievements/unlock \
  -H "Authorization: Bearer <userToken>" \
  -H "x-bs-gameid: <gameId>" \
  -H "x-bs-secrettoken: <secretToken>" \
  -H "Content-Type: application/json" \
  -d '{"achievementId": "first_blood"}'

Ответ

json

{ "success": true }

Возможные HTTP статусы

200 OK—Достижение разблокировано.

401 Unauthorized—Неверный secretToken разработчика.

404 Not Found—Идентификатор ачивки не найден в игре.

Облачные сохранения

Регистрация и статус синхронизированных сохранений между устройствами.

POST/sdk/cloudsaves/sync▾

Регистрирует загруженный архив сохранения (сначала загрузите файл через presigned URL из POST /storage/presign). Обнаруживает конфликты между устройствами по baseVersion.

Заголовки

Authorization: Bearer <userToken>
x-bs-gameid: <gameId>

Тело запроса

json

{
  "sha256": "<sha256 of the save archive>",
  "sizeBytes": 204800,
  "storageKey": "<key returned by /storage/presign>",
  "baseVersion": 3
}

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/sdk/cloudsaves/sync \
  -H "Authorization: Bearer <userToken>" \
  -H "x-bs-gameid: <gameId>" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"e3b0c442...","sizeBytes":204800,"storageKey":"saves/slot1.bin","baseVersion":3}'

Ответ

json

{ "success": true, "conflict": false, "status": "active" }

Возможные HTTP статусы

200 OK—Слот сохранения синхронизирован.

409 Conflict—Обнаружена более свежая версия на другом устройстве.

GET/library/games/:id/cloudsave/status▾

Текущая версия и метаданные облачного сохранения. Доступ по обычной игровой/веб-сессии, не по SDK-заголовкам.

Заголовки

Authorization: Bearer <session token>

Пример вызова cURL

bash

curl -X GET https://api.bluestudz.ru/library/games/a1b2c3d4/cloudsave/status \
  -H "Authorization: Bearer <sessionToken>"

Ответ

json

{ "version": 3, "sha256": "...", "sizeBytes": 204800, "updatedAt": "..." }

Возможные HTTP статусы

200 OK—Метаданные сохранения получены.

404 Not Found—Облачных сохранений для игры ещё нет.

Прогресс и мэтчмейкинг

Боевой пропуск и быстрая очередь мэтчмейкинга.

POST/sdk/battlepass/sync▾

Синхронизирует прогресс боевого пропуска. Значения xp/tier применяются как максимум (GREATEST) — клиент не может откатить прогресс назад.

Заголовки

Authorization: Bearer <userToken>
x-bs-gameid: <gameId>
x-bs-secrettoken: <developer secret>

Тело запроса

json

{ "xp": 1500, "tier": 4, "hasPremium": false, "claimedTiers": [1, 2, 3] }

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/sdk/battlepass/sync \
  -H "Authorization: Bearer <userToken>" \
  -H "x-bs-gameid: <gameId>" \
  -H "x-bs-secrettoken: <secretToken>" \
  -H "Content-Type: application/json" \
  -d '{"xp":1500,"tier":4,"hasPremium":false,"claimedTiers":[1,2,3]}'

Ответ

json

{ "success": true }

Возможные HTTP статусы

200 OK—Прогресс успешно зафиксирован.

401 Unauthorized—Неверный secretToken.

POST/sdk/matchmaking/join▾

Ставит игрока в очередь мэтчмейкинга (аналог SteamMatchmaking для quick-play).

Заголовки

Authorization: Bearer <userToken>
x-bs-gameid: <gameId>

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/sdk/matchmaking/join \
  -H "Authorization: Bearer <userToken>" \
  -H "x-bs-gameid: <gameId>"

Ответ

json

{ "status": "Queued", "serverAddress": "" }

Возможные HTTP статусы

200 OK—Игрок помещен в очередь.

POST/sdk/matchmaking/leave▾

Убирает игрока из очереди мэтчмейкинга.

Заголовки

Authorization: Bearer <userToken>
x-bs-gameid: <gameId>

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/sdk/matchmaking/leave \
  -H "Authorization: Bearer <userToken>" \
  -H "x-bs-gameid: <gameId>"

Ответ

json

{ "status": "Left" }

Возможные HTTP статусы

200 OK—Игрок удален из очереди.

Лобби

Полноценные лобби (matchmaking-service) - серверный релей, без прямого P2P.

POST/lobby▾

SteamMatchmaking()->CreateLobby() эквивалент (matchmaking-service). Трафик лобби проксируется сервером — участники не обмениваются IP.

Заголовки

Authorization: Bearer <session token>

Тело запроса

json

{ "gameId": "<game-uuid>", "maxPlayers": 4, "isPrivate": false }

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/lobby \
  -H "Authorization: Bearer <sessionToken>" \
  -H "Content-Type: application/json" \
  -d '{"gameId":"uuid","maxPlayers":4,"isPrivate":false}'

Ответ

json

{ "lobbyId": "lob_991", "hostId": "usr_123" }

Возможные HTTP статусы

200 OK—Лобби успешно создано.

429 Too Many Requests—Превышен лимит создания лобби.

POST/lobby/:id/join▾

Присоединение к существующему лобби по ID.

Заголовки

Authorization: Bearer <session token>

Пример вызова cURL

bash

curl -X POST https://api.bluestudz.ru/lobby/lob_991/join \
  -H "Authorization: Bearer <sessionToken>"

Ответ

json

{ "success": true }

Возможные HTTP статусы

200 OK—Успешное присоединение.

404 Not Found—Лобби не существует или заполнено.

WebSocket

Реалтайм-события поверх Socket.IO.

WSwss://ws.bluestudz.ru (Socket.IO, matchmaking & relay namespace)▾

Реалтайм-шлюз мэтчмейкинга и Relay. SDK-игры используют безопасный серверный релей для обмена бинарными пакетами (до 128 КБ на чанк).

Ответ

json

// client -> server (Socket.IO events)
socket.emit("join_queue", { gameId })
socket.emit("leave_queue", { gameId })
socket.emit("relay_packet", { roomId, chunkIndex, data })