Asomiru APIv1

Статистика сервера и награды за голоса.

Первый запрос OpenAPI

GET/server

Онлайн и карта

POST/players/resolve

Игровые аккаунты

POST/rewards/claim

Награды за голоса

POST/votes/check

Проверка голоса

Начни с одного запроса

Открой свою страницу сервера на Asomiru → Asomiru API → Включить API и создать ключ. Владение сервером должно быть подтверждено. Сохрани ключ: он понадобится каждому запросу.

В терминале задай свой ключ вместо примера:

bash

export ASOMIRU_API_KEY='asmr_42_ТВОЙ_КЛЮЧ'

Теперь запроси онлайн:

bash

curl 'https://api.asomiru.com/v1/server' \
  -H "Authorization: Bearer $ASOMIRU_API_KEY"

json

{
  "id": 42,
  "name": "NEVA · Classic Public",
  "game": "cs2",
  "status": "online",
  "address": "play.example.com:27015",
  "players": 18,
  "maxPlayers": 32,
  "map": "de_mirage",
  "version": null,
  "mode": "defuse",
  "activeVotes": 126,
  "checkedAt": "2026-10-11T10:00:00.000Z",
  "pageUrl": "https://asomiru.com/ru/servers/42"
}

players — игроков сейчас, maxPlayers — слотов, activeVotes — действующих голосов. checkedAt показывает, когда мониторинг проверял сервер. У недоступного сервера status будет offline. Для Minecraft вместо карты приходит версия, например 1.21.1. Неизвестное значение — null.

Адрес API: https://api.asomiru.com/v1. Ключ сам определяет сервер — указывать его ID в запросах не нужно. Отправляй запросы с backend, бота или игрового плагина. В публичный JavaScript ключ не вставляй.

Получи статистику за неделю

bash

curl 'https://api.asomiru.com/v1/server/stats?period=week' \
  -H "Authorization: Bearer $ASOMIRU_API_KEY"

json

{
  "serverId": 42,
  "period": "week",
  "since": "2026-10-04T10:00:00.000Z",
  "until": "2026-10-11T10:00:00.000Z",
  "connectClicks": {"total": 245, "uniqueBrowsers": 173},
  "votes": {"received": 64},
  "reportedJoins": 312,
  "players": {"average": 17.42, "peak": 32},
  "monitoring": {"samples": 2016, "onlineSamples": 2008, "availabilityPercent": 99.6},
  "generatedAt": "2026-10-11T10:00:00.000Z"
}

Что можно вывести на своей панели:

connectClicks.total — нажатия «Подключиться» на Asomiru. Это переходы из мониторинга, а не подтверждённые входы в игру. Повторные клики из одного браузера в течение 30 секунд считаются одним.
connectClicks.uniqueBrowsers — оценка числа уникальных переходов за период.
votes.received — голоса, полученные за период.
reportedJoins — входы в игру, которые отправил твой плагин. Без отправки данных значение равно нулю.
players.average и players.peak — средний и максимальный онлайн по успешным проверкам.
monitoring.availabilityPercent — доля проверок, в которых сервер отвечал. Если проверок ещё не было, значение — null.

Периоды: day — последние 24 часа, week — 7 дней, month — 30 дней. Если period не указан, используется week. Статистика кэшируется на 30 секунд. Все даты в ответах — UTC.

Построй график

bash

curl 'https://api.asomiru.com/v1/server/history?period=week' \
  -H "Authorization: Bearer $ASOMIRU_API_KEY"

json

{
  "serverId": 42,
  "period": "week",
  "bucket": "day",
  "since": "2026-10-04T10:00:00.000Z",
  "until": "2026-10-11T10:00:00.000Z",
  "points": [
    {"at": "2026-10-04T00:00:00.000Z", "connectClicks": 21, "votes": 4, "reportedJoins": 38, "averagePlayers": 12.5, "peakPlayers": 24, "samples": 168, "onlineSamples": 168},
    {"at": "2026-10-05T00:00:00.000Z", "connectClicks": 36, "votes": 8, "reportedJoins": 52, "averagePlayers": 18.7, "peakPlayers": 32, "samples": 288, "onlineSamples": 286}
  ],
  "generatedAt": "2026-10-11T10:00:00.000Z"
}

Ответ выше сокращён до двух точек. Для day точки идут по часам, для week и month — по дням. at — начало часа или дня; первая и последняя точки могут охватывать только часть этого интервала. Дни без событий тоже приходят. Если онлайн не измерялся, averagePlayers и peakPlayers равны null, а не нулю.

Как плагин узнаёт игрока

Asomiru ID — постоянный ID аккаунта на сайте, например ASM-1-0000-0042-20. Он есть в личном профиле и не меняется при смене ника, email или Steam. Передавай ID целиком, вместе с дефисами. Последние две цифры помогают обнаружить опечатку. Ранее выданные ID также принимаются API.

Игровой ID относится к аккаунту в игре. Плагин получает его у самого сервера после авторизации игрока. Asomiru ID и игровой ID связываются один раз. После этого игрок голосует на сайте, а плагин находит его голоса по игровому ID — копировать Asomiru ID при каждом входе не нужно.

Есть два способа привязки.

Steam. Игрок привязывает Steam в настройках Asomiru и на странице выбранного сервера нажимает Включить награды через Steam. Для CS, Team Fortress 2, Rust и Left 4 Dead плагин использует SteamID64 авторизованного игрока. Передавай его строкой: JavaScript округляет такие большие числа. В ARK и Valheim Steam тоже можно использовать; для аккаунтов других платформ подходит привязка по коду.

Код из игры. Для Minecraft плагин берёт UUID вошедшего игрока и запрашивает код:

bash

curl -X POST 'https://api.asomiru.com/v1/rewards/link' \
  -H "Authorization: Bearer $ASOMIRU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"playerId":"00000000-0000-4000-8000-000000000042"}'

json

{"code":"aBcD1234_xYz","expiresAt":"2026-10-11T10:10:00.000Z"}

Покажи код только этому игроку. На странице твоего сервера он вводит код и нажимает Привязать и включить награды. Код действует 10 минут и используется один раз. Новый код можно запросить через минуту. Если ответ потерялся, подожди минуту и запроси ещё раз.

В AsomiruBridge для Minecraft это делает команда /asomiru link. Плагин работает на Paper/Spigot 1.21.1+ с Java 21 и online-mode=true. Для сервера за прокси или с отдельной авторизацией интеграция должна проверять эту авторизацию перед привязкой. Нельзя принимать UUID, SteamID или ник, который игрок просто прислал в чат: такой текст не подтверждает аккаунт.

В собственной интеграции для другой платформы используй её постоянный ID: 3–64 символа, латинские буквы, цифры, _, :, -. Передавай один и тот же формат во всех запросах. Никнейм для этого не подходит.

Найди привязанного игрока

Запрос принимает до 50 игроков и отвечает в том же порядке. Это удобно при входе игроков или периодической проверке сервера.

bash

curl -X POST 'https://api.asomiru.com/v1/players/resolve' \
  -H "Authorization: Bearer $ASOMIRU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"players":[{"kind":"steam","id":"76561198000000001"}]}'

json

{
  "players": [
    {"asomiruId":"ASM-1-0000-0042-20","rewards":true}
  ]
}

rewards: true — привязка работает. Если игрок не привязан или отключил привязку, на его месте приходит null.

Во всех запросах с полем player доступны такие варианты:

kind	Что передать в id
`game`	UUID Minecraft или постоянный ID аккаунта другой платформы. В играх с авторизацией Steam также принимается SteamID64.
`steam`	SteamID64 для игры, поддерживающей Steam. Он должен совпадать с привязанным аккаунтом.
`asomiru`	Asomiru ID уже привязанного игрока. Удобно, если сохранил его в своей системе.

Asomiru ID не является паролем и сам по себе не открывает доступ. Ключ видит только привязки своего сервера. Старая привязка может вернуть asomiruId: null: игроку нужно обновить её на странице сервера. Проверка наград по прежнему игровому ID продолжит работать.

Проверь голоса

Чтобы показать игроку, голосовал ли он и сколько наград ожидает получения:

bash

curl -X POST 'https://api.asomiru.com/v1/votes/check' \
  -H "Authorization: Bearer $ASOMIRU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"player":{"kind":"steam","id":"76561198000000001"}}'

json

{"voted":true,"activeVotes":3,"pendingRewards":1,"lastVotedAt":"2026-10-11T10:00:00.000Z"}

activeVotes — действующие голоса за этот сервер; каждый действует 30 дней. pendingRewards — новые голоса, получение которых плагин ещё не подтвердил. В их число входят и события, временно занятые другой доставкой. Этот запрос ничего не забирает и не меняет.

Для выдачи наград используй следующий раздел. Нельзя выдавать награду каждый раз, когда voted равно true: один голос тогда будет засчитываться многократно.

Выдай награду за голос

Сначала привяжи аккаунт, затем попроси игрока проголосовать. Награды создаются по голосам после привязки; ранее сделанный голос можно увидеть через votes/check, но события награды для него нет.

1. Получи события. Создай UUID requestId и сохрани его в своём плагине до отправки запроса.

bash

curl -X POST 'https://api.asomiru.com/v1/rewards/claim' \
  -H "Authorization: Bearer $ASOMIRU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"player":{"kind":"steam","id":"76561198000000001"},"requestId":"11111111-1111-4111-8111-111111111111"}'

json

{
  "delivery":{"id":"22222222-2222-4222-8222-222222222222","leaseUntil":"2026-10-11T10:02:00.000Z"},
  "events":[
    {"id":"33333333-3333-4333-8333-333333333333","type":"server.vote","votedAt":"2026-10-11T10:00:00.000Z","expiresAt":"2026-11-10T10:00:00.000Z"}
  ]
}

Каждый events[].id — отдельный голос. За один запрос приходит до 20 событий. Если новых голосов нет или привязка недоступна, ответ одинаковый:

json

{"delivery":null,"events":[]}

2. Сохрани события. Запиши их в постоянную очередь плагина. Сделай events[].id уникальным ключом: повторное событие не должно создавать ещё одну награду. Если ответ потерялся, повтори claim с тем же requestId. Пока доставка действует, сервер вернёт ту же партию; другая доставка эти события не заберёт.

3. Подтверди получение. После сохранения очереди отправь ack, пока не наступил leaseUntil — обычно есть две минуты:

bash

curl -X POST 'https://api.asomiru.com/v1/rewards/ack' \
  -H "Authorization: Bearer $ASOMIRU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"deliveryId":"22222222-2222-4222-8222-222222222222"}'

json

{"acknowledged":true}

ack подтверждает сохранение событий у тебя, а не выдачу предмета в игре. Из сохранённой очереди выдавай награды по своим правилам. Сохраняй ID обработанных событий до expiresAt; все обработчики одного сервера должны использовать общий журнал. Саму выдачу тоже защищай от повторения: например, записывай ID события и изменение баланса игрока в одной транзакции игровой БД. Если игровая команда этого не позволяет, неоднозначный результат после сбоя нужно проверять, а не повторять команду вслепую.

При LEASE_EXPIRED создай новый requestId и снова вызови claim. ID голосов останутся прежними — твоя очередь распознает повтор. Подтверждённая доставка повторно отвечает acknowledged: true, пока её запись хранится в API — до двух дней. Ожидающие голоса доступны до 30 дней.

Поле playerId в прежних интеграциях поддерживается. В одном запросе передавай либо playerId, либо player.

Считай все входы на сервер

Для общей статистики не нужны аккаунты игроков. Собери количество входов за минуту и отправь его одним запросом:

bash

curl -X POST 'https://api.asomiru.com/v1/server/joins' \
  -H "Authorization: Bearer $ASOMIRU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"eventId":"66666666-6666-4666-8666-666666666666","count":7,"occurredAt":"2026-10-11T10:00:00.000Z"}'

Создавай новый eventId и текущую дату для каждой партии. При сбое повтори те же данные с тем же ID. Один запрос принимает 1–1000 входов за последние 24 часа; лимит — 10 запросов в минуту. Результат появится в reportedJoins статистики сервера. Отчёты о входах поступают от твоего плагина и не участвуют в рейтинге мониторинга.

Пример на Node.js

Скачай клиент Asomiru API и распакуй папку asomiru-sdk в свой проект. Node.js 22.13+; дополнительных библиотек не нужно.

javascript

import { AsomiruClient } from './asomiru-sdk/index.mjs';

const api = new AsomiruClient(process.env.ASOMIRU_API_KEY);
const player = { kind: 'steam', id: '76561198000000001' };

const server = await api.server();
console.log(`${server.name}: ${server.players}/${server.maxPlayers}`);

const votes = await api.votes(player);
console.log(`Ожидает наград: ${votes.pendingRewards}`);

В архиве есть examples/rewards.mjs: он сохраняет requestId и голоса в SQLite, затем подтверждает получение. Его можно использовать как основу для своей очереди наград. Правила выдачи предметов остаются в игровом плагине.

Клиент повторяет безопасные запросы при разрыве связи с прежними ID. При ограничении частоты выбрасывает AsomiruError с code и retryAfter. Онлайн для сайта или бота обычно достаточно обновлять раз в минуту.

Ошибки и лимиты

json

{"code":"INVALID_API_KEY","message":"Неверный ключ API"}

Статус / code	Что сделать
400	Проверь JSON и названия полей.
401 / `INVALID_API_KEY`	Проверь ключ, включён ли API и сохранилось ли владение сервером.
403 / `SERVER_SIDE_ONLY`	Отправляй запрос из плагина, backend или бота.
409 / `LEASE_EXPIRED`	Создай новый `requestId` для `claim`.
409 / `REQUEST_ID_REUSED`	Один ID запроса нельзя использовать для другого игрока или изменённых данных.
409 / `EVENT_ID_REUSED`	Не меняй уже отправленную партию входов.
422	Проверь тип игрового ID, UUID, период и значения полей.
429	Подожди указанное в `Retry-After` число секунд.
500 / 503	Повтори позже. Для доставки голосов и отчётов сохрани прежний ID и тело запроса.

Общий лимит — 120 запросов в минуту на сервер и 300 на IP. Тело POST — до 2 КБ; для players/resolve — до 24 КБ. Статистика кэшируется на 30 секунд, личные ответы не кэшируются. Все даты — UTC.

Ключ хранится только на сервере. Замена ключа отключает прежний, а отключение API или смена владельца прекращает доступ к привязкам. Если игрок удалил привязку Steam, запросы через этот Steam перестают находить его привязанные аккаунты.

Все поля и ответы: OpenAPI. Пример настройки Minecraft: исходники AsomiruBridge. Вопросы по подключению: support@asomiru.com.