API MineList pentru proprietarii de servere

API-ul MineList permite serverului tău să verifice dacă un jucător a votat, să acorde o recompensă exact o singură dată și să citească statisticile publice. Toate endpoint-urile returnează JSON și folosesc cereri HTTPS GET simple, deci funcționează din orice limbaj de programare.

Cum obții cheia API

Adaugă-ți serverul, revendică-l și deschide panoul proprietarului. Cheia API apare în pagina de setări a serverului. Păstrează-o privată, deoarece îți identifică serverul. Dacă a fost expusă, generează una nouă în panou și actualizează pluginul sau scriptul.

Adresa de bază a tuturor endpoint-urilor este https://minelist.eu.

Verificarea unui vot

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

Îți spune dacă jucătorul a votat astăzi și dacă recompensa a fost deja preluată.

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

voted este true dacă nick-ul are un vot pentru serverul tău în ziua UTC curentă.
claimed este true dacă ai marcat deja acel vot ca preluat.
next_vote_utc este momentul în care jucătorul poate vota din nou.

Preluarea unui vot

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

Marchează votul de astăzi ca preluat. Apelează-l chiar înainte de a oferi recompensa, ca jucătorul să nu o poată ridica de două ori. Răspunsuri posibile:

Răspuns	Semnificație
`{"voted":true,"claimed":true}`	Votul a fost valid și acum este preluat. Oferă recompensa.
`{"voted":true,"claimed":false,"already_claimed":true}`	Votul fusese preluat mai devreme. Nu oferi nimic.
`{"voted":false,"claimed":false}`	Jucătorul nu a votat astăzi.

Lista voturilor din această lună

GET /api/v1/votes?key=API_KEY

Returnează toate voturile primite de serverul tău în luna curentă. Este util pentru recompensele lunare ale celor mai activi votanți și pentru clasamente pe site-ul tău.

Statistici publice ale serverului

GET /api/v1/server/<slug>

Acest endpoint nu necesită cheie. Slug-ul este ultima parte a adresei serverului pe MineList. Exemple de câmpuri din răspuns:

Câmp	Descriere
`name`	Numele serverului
`url`	Site-ul serverului
`ip`	Adresa de conectare
`online`	Dacă ultima verificare a reușit
`players`	Jucători online la ultima verificare
`max_players`	Locuri pentru jucători
`version`	Versiunea serverului
`votes_month`	Voturi în această lună
`votes_total`	Voturi de la adăugarea serverului
`uptime_30`	Disponibilitate în ultimele 30 de zile, în procente
`rating`	Nota medie
`last_check`	Momentul ultimei verificări

Exemplu cu curl

Aceasta este întreaga logică în formă de shell. Orice limbaj care poate trimite o cerere HTTP, precum Java, PHP, Python sau Node.js, face același lucru.

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

Procesează JSON-ul și, dacă claimed este true, rulează comanda de recompensă, de exemplu give Steve diamond 3.

Suport NuVotifier

Dacă preferi recompense instant, fără interogări repetate, MineList poate trimite voturile către serverul tău prin NuVotifier. Sunt suportate ambele versiuni ale protocolului. Versiunea 1 folosește o cheie publică RSA, versiunea 2 folosește un token.

Instalează NuVotifier pe server și repornește-l.
În panoul proprietarului introdu host-ul, portul (implicit 8192) și cheia publică (v1) sau tokenul (v2).
Apasă Trimite vot de test și verifică dacă serverul înregistrează votul în jurnal.

Dacă testul eșuează, asigură-te că portul Votifier este deschis în firewall și că ai copiat cheia fără spații sau întreruperi de rând.

Banner live

Fiecare server are un banner live de 468x60 pixeli care arată starea curentă și numărul de jucători:

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

Exemplu de inserare în HTML:

<a href="https://minelist.eu/ro/server/slug-ul-tau">
  <img src="https://minelist.eu/banner/slug-ul-tau.png" width="468" height="60" alt="Votează pentru noi pe MineList">
</a>

Bune practici

Păstrează statisticile publice în cache cel puțin un minut, în loc să apelezi API-ul la fiecare afișare a paginii.
Nu pune niciodată cheia API în codul de partea clientului sau într-un depozit public.
Folosește endpoint-ul de preluare o singură dată pentru fiecare recompensă.