MineList API за собственици на сървъри

MineList API позволява на сървъра ти да проверява дали играч е гласувал, да дава награда точно веднъж и да чете публична статистика. Всички endpoint-и връщат JSON и използват обикновени HTTPS GET заявки, така че работят от всеки програмен език.

Как да получиш API ключ

Добави сървъра си, заяви го и отвори панела на собственика. API ключът се показва на страницата с настройките на сървъра. Пази го в тайна, защото идентифицира сървъра ти. Ако изтече, генерирай нов в панела и обнови плъгина или скрипта си.

Базовият адрес на всички endpoint-и е https://minelist.eu.

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

GET /api/v1/vote?key=API_KEY&username=NICK

Показва дали играчът е гласувал днес и дали наградата вече е получена.

{"voted":true,"claimed":false,"next_vote_utc":"2026-10-31T00:00:00Z"}

voted е true, ако никът има глас за сървъра ти през текущия UTC ден.
claimed е true, ако този глас вече е отбелязан като получен.
next_vote_utc е моментът, в който играчът може да гласува отново.

Отбелязване на глас като получен

GET /api/v1/vote/claim?key=API_KEY&username=NICK

Отбелязва днешния глас като получен. Извикай го точно преди да раздадеш наградата, за да не може играчът да я вземе два пъти. Възможни отговори:

Отговор	Значение
`{"voted":true,"claimed":true}`	Гласът е валиден и вече е отбелязан като получен. Дай наградата.
`{"voted":true,"claimed":false,"already_claimed":true}`	Гласът вече е бил отбелязан като получен по-рано. Не давай нищо.
`{"voted":false,"claimed":false}`	Играчът не е гласувал днес.

Списък с гласовете този месец

GET /api/v1/votes?key=API_KEY

Връща всички гласове, които сървърът ти е получил през текущия месец. Полезно е за месечни награди за най-активните гласуващи и за класации на собствения ти уебсайт.

Публична статистика на сървъра

GET /api/v1/server/<slug>

Този endpoint не изисква ключ. Slug е последната част от адреса на сървъра в MineList. Примерни полета в отговора:

Поле	Описание
`name`	Име на сървъра
`url`	Уебсайт на сървъра
`ip`	Адрес за свързване
`online`	Дали последната проверка е била успешна
`players`	Играчи онлайн при последната проверка
`max_players`	Брой места за играчи
`version`	Версия на сървъра
`votes_month`	Гласове този месец
`votes_total`	Гласове от добавянето на сървъра
`uptime_30`	Достъпност през последните 30 дни в проценти
`rating`	Средна оценка
`last_check`	Време на последната проверка

Пример с curl

Това е цялата логика във вид на shell команда. Всеки език, който може да изпрати HTTP заявка, например Java, PHP, Python или Node.js, прави същото.

curl -s "https://minelist.eu/api/v1/vote/claim?key=API_KEY&username=Steve"

Обработи JSON отговора и ако claimed е true, изпълни командата за награда, например give Steve diamond 3.

Поддръжка на NuVotifier

Ако предпочиташ моментални награди без постоянно питане, MineList може да изпраща гласовете към сървъра ти през NuVotifier. Поддържат се и двете версии на протокола. Версия 1 използва публичен RSA ключ, версия 2 използва токен.

Инсталирай NuVotifier на сървъра си и го рестартирай.
В панела на собственика въведи хост, порт (по подразбиране 8192) и публичния ключ (v1) или токена (v2).
Натисни Изпрати тестов глас и провери дали сървърът ти записва гласа в лога.

Ако тестът се провали, увери се, че портът на Votifier е отворен във файъруола ти и че ключът е копиран без интервали или нови редове.

Live банер

Всеки сървър има live банер 468x60 пиксела, който показва текущия статус и броя играчи:

https://minelist.eu/banner/<slug>.png

Пример за вграждане в HTML:

<a href="https://minelist.eu/bg/server/tvoj-slug">
  <img src="https://minelist.eu/banner/tvoj-slug.png" width="468" height="60" alt="Гласувай за нас в MineList">
</a>

Добри практики

Кеширай публичната статистика поне една минута, вместо да викаш API-то при всяко зареждане на страница.
Никога не слагай API ключа в код от страна на клиента или в публично хранилище.
Използвай endpoint-а за получаване само веднъж за всяка награда.