IP-Minecraft.ru

API документация

Этот раздел описывает единственный сценарий, для которого нужен server vote API key: получение необработанных голосов и их подтверждение после выдачи награды на сервере.

Обновлено: 26.03.2026
Мониторинг серверов Майнкрафт (Minecraft) IP-Minecraft.ru: Этот раздел описывает единственный сценарий, для которого нужен server vote API key: получение необработанных голосов и их подтвер…

Что это за API

API-ключ сервера не нужен для публичного UI, голосования на сайте или работы кабинета. Он нужен только внешнему плагину наград, который забирает новые голоса и отмечает их обработанными после выдачи приза игроку.

Ключ привязан к одному серверу. При повторной генерации старый ключ немедленно перестаёт работать. Генерировать новый ключ можно из профиля сервера, маршрут: POST /api/v1/profile/servers/:serverId/votes/api-key.

  • Ключ показывается только один раз после генерации.
  • Рекомендуемый способ передачи ключа: Authorization: Bearer <apiKey>.
  • Legacy-заголовок X-API-Key поддерживается только для обратной совместимости.
  • Плагин должен работать только по HTTPS и хранить ключ в конфиге сервера, а не на клиенте.

1. Получить необработанные голоса

Плагин периодически опрашивает внешний маршрут и получает список ещё не подтверждённых голосов. Пока голос не подтверждён, он остаётся в выдаче.

Маршрутtext
GET /api/v1/external/votes/servers/:serverId/unclaimed?limit=100
Пример запросаbash
curl -X GET "https://example.com/api/v1/external/votes/servers/42/unclaimed?limit=50" \
  -H "Authorization: Bearer YOUR_SERVER_API_KEY"
Пример ответаjson
{
  "success": true,
  "data": {
    "votes": [
      {
        "id": "1dd8b2f2-0a65-4f22-90d6-1c25b1f2664b",
        "nickname": "PlayerOne",
        "votedAt": "2026-03-26T17:18:02.123Z"
      }
    ],
    "count": 1
  }
}

2. Подтвердить один голос после выдачи награды

После того как награда реально выдана игроку, плагин должен подтвердить конкретный голос. Только после этого голос исчезнет из unclaimed-выдачи.

Маршрутtext
POST /api/v1/external/votes/servers/:serverId/claim/:voteId
Пример запросаbash
curl -X POST "https://example.com/api/v1/external/votes/servers/42/claim/1dd8b2f2-0a65-4f22-90d6-1c25b1f2664b" \
  -H "Authorization: Bearer YOUR_SERVER_API_KEY"
Пример ответаjson
{
  "success": true,
  "data": {
    "id": "1dd8b2f2-0a65-4f22-90d6-1c25b1f2664b",
    "nickname": "PlayerOne",
    "claimed": true,
    "claimedAt": "2026-03-26T17:18:30.341Z"
  }
}

3. Массово подтвердить все выданные голоса

Если плагин сначала обрабатывает пачку голосов, а затем хочет подтвердить всё одним запросом, можно использовать claim-all.

Маршрутtext
POST /api/v1/external/votes/servers/:serverId/claim-all
Пример ответаjson
{
  "success": true,
  "data": {
    "claimedCount": 12,
    "claimedAt": "2026-03-26T17:20:01.002Z"
  }
}

Рекомендуемый цикл работы плагина

  • Раз в 15-60 секунд вызвать unclaimed для своего serverId.
  • Для каждого голоса проверить, что игрок онлайн или награду можно безопасно выдать позже.
  • После успешной выдачи награды вызвать claim для конкретного voteId.
  • Если награда не выдана, не подтверждать голос: он останется в очереди и будет доступен повторно.

Статусы и ошибки

  • 401: API key не передан.
  • 403: API key невалидный или уже был заменён новой генерацией.
  • 404: сервер или голос не найдены, либо голос уже подтверждён.
  • 429: превышен rate limit внешнего API. Плагину не нужно опрашивать маршрут чаще нескольких раз в секунду.

Что не делать

  • Не встраивать этот ключ в frontend, launcher или общедоступный клиент.
  • Не подтверждать голос до фактической выдачи награды.
  • Не хранить ключ в логах сервера и не печатать его в консоль при старте.
  • Не использовать этот ключ для публичного голосования: голосование пользователей идёт через отдельный публичный маршрут сайта.