API голосования

Основы

• Ответы приходят в формате JSON. Отправляйте заголовок Accept: application/json с каждым запросом.
• Аутентификация не требуется.
• Лимит: 30 запросов в минуту с одного IP-адреса.
• Всё время указано в UTC.
• Игрок может голосовать за сервер раз в день, а сервер может получить не более 30 голосов в день.

UUID вашего сервера

У каждого сервера в списке есть постоянный UUID, который идентифицирует его в API, поэтому интеграция продолжит работать, даже если адрес сервера изменится. UUID показывается владельцам на странице сервера. Если не можете его найти, напишите нам, указав адрес сервера, и мы его пришлём.

Список голосов

GET https://mcserverscout.com/api/servers/{uuid}/votes

Возвращает голоса за сервер, начиная с самых новых. Анонимные голоса (без ника) не включаются.

Параметры запроса

Все параметры необязательны.

Пример запроса

curl -H "Accept: application/json" \
  "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?nick=Steve&date_from=2026-10-23"

Пример ответа

{
  "data": [
    {
      "nick": "Steve",
      "created_at": "2026-10-23T14:30:00+00:00"
    }
  ],
  "links": {
    "first": "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?page=1",
    "last": "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 100,
    "to": 1,
    "total": 1
  }
}

Чтобы получить следующие страницы, используйте links.next или параметр page. Объект meta также содержит стандартные поля пагинации path и links.

Ошибки

• 404: сервера с таким UUID нет. Проверьте, что вы скопировали UUID целиком.
• 422: недопустимый параметр, например limit=500. В объекте errors ответа указано, какой это параметр и что с ним не так.
• 429: больше 30 запросов в минуту. Подождите время, указанное в заголовке Retry-After.

Награды за голоса в плагине

Самый простой способ: когда игрок вводит команду вроде /vote claim, спросите у API, голосовал ли этот ник сегодня, и выдайте награду, если голос есть и награда за него ещё не получена. Сохраняйте для каждого игрока дату получения награды, чтобы один голос нельзя было использовать дважды.

Минимальная проверка для плагина Paper или Spigot (Java 11+), выполняемая вне основного потока:

// Returns true if the player has voted today (UTC).
CompletableFuture<Boolean> hasVotedToday(String nick) {
    String today = LocalDate.now(ZoneOffset.UTC).toString();
    URI uri = URI.create(API_URL
        + "?limit=1&date_from=" + today
        + "&nick=" + URLEncoder.encode(nick, StandardCharsets.UTF_8));

    HttpRequest request = HttpRequest.newBuilder(uri)
        .header("Accept", "application/json")
        .build();

    return HttpClient.newHttpClient()
        .sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .thenApply(response -> response.statusCode() == 200
            && !response.body().contains("\"data\":[]"));
}

Задайте API_URL равным https://mcserverscout.com/api/servers/{uuid}/votes с UUID вашего сервера. Саму награду выдавайте уже в основном потоке, например через Bukkit.getScheduler().runTask(...). Если хотите награждать игроков автоматически, опрашивайте API каждые несколько минут с date_from, равным сегодняшней дате, и обрабатывайте ники, которых ещё не видели. Держитесь с запасом ниже лимита в 30 запросов в минуту.