L’API di MineList permette al tuo server di controllare se un giocatore ha votato, dare una ricompensa esattamente una volta e leggere le statistiche pubbliche. Tutti gli endpoint restituiscono JSON e usano semplici richieste HTTPS GET, quindi funzionano con qualsiasi linguaggio.
Come ottenere la tua chiave API
Aggiungi il tuo server, rivendicalo e apri il pannello del proprietario. La chiave API è mostrata nella pagina delle impostazioni del server. Tienila riservata, perché identifica il tuo server. Se viene diffusa, generane una nuova nel pannello e aggiorna il tuo plugin o script.
L’indirizzo di base di tutti gli endpoint è https://minelist.eu.
Controllare un voto
GET /api/v1/vote?key=API_KEY&username=NICKTi dice se il giocatore ha votato oggi e se la ricompensa è già stata riscattata.
{"voted":true,"claimed":false,"next_vote_utc":"2026-10-31T00:00:00Z"}votedè true se il nick ha un voto per il tuo server nel giorno UTC corrente.claimedè true se hai già segnato quel voto come riscattato.next_vote_utcè il momento in cui il giocatore potrà votare di nuovo.
Riscattare un voto
GET /api/v1/vote/claim?key=API_KEY&username=NICKSegna il voto di oggi come riscattato. Chiamalo subito prima di consegnare la ricompensa, così un giocatore non può riscuoterla due volte. Risposte possibili:
| Risposta | Significato |
|---|---|
{"voted":true,"claimed":true} | Il voto era valido ed è ora riscattato. Consegna la ricompensa. |
{"voted":true,"claimed":false,"already_claimed":true} | Il voto era già stato riscattato in precedenza. Non consegnare nulla. |
{"voted":false,"claimed":false} | Il giocatore non ha votato oggi. |
Elencare i voti di questo mese
GET /api/v1/votes?key=API_KEYRestituisce tutti i voti ricevuti dal tuo server nel mese corrente. È utile per le ricompense mensili ai migliori votanti e per le classifiche sul tuo sito.
Statistiche pubbliche del server
GET /api/v1/server/<slug>Questo endpoint non richiede una chiave. Lo slug è l’ultima parte dell’indirizzo del server su MineList. Campi di esempio della risposta:
| Campo | Descrizione |
|---|---|
name | Nome del server |
url | Sito web del server |
ip | Indirizzo di connessione |
online | Indica se l’ultimo controllo è riuscito |
players | Giocatori online all’ultimo controllo |
max_players | Posti per i giocatori |
version | Versione del server |
votes_month | Voti di questo mese |
votes_total | Voti da quando il server è stato aggiunto |
uptime_30 | Disponibilità negli ultimi 30 giorni, in percentuale |
rating | Valutazione media |
last_check | Ora dell’ultimo controllo |
Esempio con curl
Questa è tutta la logica in forma di comando shell. Qualsiasi linguaggio in grado di inviare una richiesta HTTP, come Java, PHP, Python o Node.js, fa lo stesso.
curl -s "https://minelist.eu/api/v1/vote/claim?key=API_KEY&username=Steve"Analizza il JSON e, se claimed è true, esegui il tuo comando di ricompensa, ad esempio give Steve diamond 3.
Supporto a NuVotifier
Se preferisci ricompense istantanee senza interrogare continuamente l’API, MineList può inviare i voti al tuo server tramite NuVotifier. Sono supportate entrambe le versioni del protocollo. La versione 1 usa una chiave pubblica RSA, la versione 2 usa un token.
- Installa NuVotifier sul tuo server e riavvialo.
- Nel pannello del proprietario inserisci l’host, la porta (8192 per impostazione predefinita) e la chiave pubblica (v1) o il token (v2).
- Premi Invia voto di prova e controlla che il tuo server registri il voto.
Se il test fallisce, assicurati che la porta di Votifier sia aperta nel firewall e che la chiave sia stata copiata senza spazi o interruzioni di riga.
Banner in tempo reale
Ogni server ha un banner in tempo reale di 468x60 pixel che mostra lo stato attuale e il numero di giocatori:
https://minelist.eu/banner/<slug>.pngEsempio di incorporamento in HTML:
<a href="https://minelist.eu/it/server/tuo-slug">
<img src="https://minelist.eu/banner/tuo-slug.png" width="468" height="60" alt="Vota per noi su MineList">
</a>Buone pratiche
- Metti in cache le statistiche pubbliche per almeno un minuto invece di chiamare l’API a ogni visualizzazione di pagina.
- Non inserire mai la chiave API nel codice lato client o in un repository pubblico.
- Usa l’endpoint di riscatto una sola volta per ricompensa.