API e plugin ricompense voti

Con ListyMC puoi premiare automaticamente in gioco chi vota il tuo server. Quando un utente vota indicando il proprio nickname Minecraft, il voto entra in una coda di ricompense da consegnare. Il plugin ufficiale ListyMCVotes (o un tuo software) legge la coda tramite l'API con la tua API key, consegna le ricompense e conferma la consegna. Ogni voto viene consegnato una sola volta.

Tutorial: installare il plugin in 5 minuti

Requisiti

• Server Spigot, Paper o Purpur 1.17 o superiore (Java 17+).
• Server approvato su ListyMC.
• Il server Minecraft deve poter raggiungere https://listymc.top in HTTPS (uscita sulla porta 443).

1. Genera la API key

1. Accedi e apri I miei server → il tuo server → scheda Plugin e API.
2. Scegli un nome (es. “Server lobby”) e premi Genera API key.
3. Copia subito la chiave (inizia con lmc_): per sicurezza viene mostrata una sola volta. Se la perdi, revocala e generane un'altra.

2. Installa il plugin

1. Scarica ListyMCVotes.jar (oppure compilalo dal sorgente nella cartella plugin/ del progetto con mvn package).
2. Copialo nella cartella plugins/ del server e riavvia.
3. Si crea il file plugins/ListyMCVotes/config.yml.

3. Configura

api:
  base-url: "https://listymc.top"
  api-key: "lmc_LA_TUA_CHIAVE"
  poll-interval-seconds: 60     # ogni quanto controllare i nuovi voti (min 15)
  timeout-seconds: 10

rewards:
  # Comandi eseguiti dalla console per OGNI voto. Segnaposto: {player} {uuid}
  commands:
    - "eco give {player} 250"
    - "crate key give {player} voto 1"
  # Ricompense casuali aggiuntive (chance in percentuale)
  random:
    - chance: 10
      commands: ["give {player} diamond 3"]
      message: "&bFortunato! Hai trovato 3 diamanti bonus."
  # Traguardi: ricompense extra al raggiungimento di N voti totali del giocatore
  milestones:
    10: ["give {player} netherite_ingot 1"]
    50: ["lp user {player} parent add votante"]
  # Se il giocatore è offline la ricompensa viene consegnata al prossimo accesso
  queue-offline: true

messages:
  prefix: "&8[&aListyMC&8] "
  player-reward: "&aGrazie per aver votato! Hai ricevuto le tue ricompense."
  broadcast-enabled: true
  broadcast: "&e{player} &7ha votato il server su &aListyMC&7! Usa &f/vote"
  vote-command:
    - "&aVota il server su ListyMC e ricevi ricompense!"
    - "&f{url}"

Poi esegui /listymc reload e /listymc status: se la chiave è corretta vedrai il nome del server e i voti totali.

4. Comandi e permessi

• /vote — mostra il link per votare (permesso listymc.vote, attivo per tutti).
• /listymc status — verifica connessione e API key.
• /listymc check <giocatore> — controlla se ha votato nelle ultime 24 ore.
• /listymc top — classifica dei votanti degli ultimi 30 giorni.
• /listymc test <giocatore> — consegna una ricompensa di prova (non tocca ListyMC).
• /listymc reload — ricarica la configurazione.
• Permesso amministrativo: listymc.admin (default: operatori).

5. Come lo vede il giocatore

1. Il giocatore apre la pagina del server su ListyMC e preme VOTA QUESTO SERVER.
2. Inserisce il nickname Minecraft (può salvarlo come predefinito nelle impostazioni del profilo).
3. Entro un minuto riceve le ricompense in gioco, oppure al prossimo accesso se era offline.

Risoluzione problemi

• 401 API key non valida: la chiave è sbagliata o revocata. Generane una nuova.
• Nessuna ricompensa: l'utente deve indicare il nickname al momento del voto; lo stesso nickname riceve al massimo una ricompensa ogni 24 ore per server.
• Timeout: il firewall dell'hosting blocca le connessioni in uscita; chiedi di aprire HTTPS verso https://listymc.top.

Riferimento API v1

URL base: https://listymc.top/api/v1. Tutte le risposte sono JSON nel formato { "ok": true, "data": … } oppure { "ok": false, "error": "…", "code": "…" }.

Autenticazione

Invia la chiave nell'header Authorization: Bearer lmc_… (in alternativa X-API-Key: lmc_…). Ogni chiave è legata a un solo server. Non inserire mai la chiave in codice lato client o in repository pubblici.

Limiti

120 richieste al minuto per chiave. Oltre il limite ricevi 429. Un intervallo di polling di 30–60 secondi è più che sufficiente.

GET /api/v1/server

Informazioni sul server associato alla chiave.

curl -H "Authorization: Bearer lmc_…" https://listymc.top/api/v1/server

{ "ok": true, "data": { "id": "clx…", "name": "Mio Server", "slug": "mio-server",
  "status": "APPROVED", "votesTotal": 1532, "voteUrl": "https://listymc.top/server/mio-server#vota" } }

GET /api/v1/votes/pending?limit=100

Voti con ricompensa ancora da consegnare, dal più vecchio. limit da 1 a 500.

{ "ok": true, "data": { "votes": [
  { "id": "clv1…", "username": "Steve_ITA", "votedAt": "2026-11-10T14:03:11.000Z" }
] } }

POST /api/v1/votes/claim

Conferma la consegna. È idempotente: gli id già confermati o non validi finiscono in ignored.

curl -X POST -H "Authorization: Bearer lmc_…" -H "Content-Type: application/json" \
     -d '{"ids":["clv1…","clv2…"]}' https://listymc.top/api/v1/votes/claim

{ "ok": true, "data": { "claimed": ["clv1…"], "ignored": ["clv2…"] } }

GET /api/v1/votes/check?username=Steve_ITA

Indica se il nickname ha votato il server nelle ultime 24 ore.

{ "ok": true, "data": { "username": "Steve_ITA", "voted": true,
  "lastVoteAt": "2026-11-10T14:03:11.000Z", "nextVoteAt": "2026-11-11T14:03:11.000Z" } }

GET /api/v1/votes/top?days=30&limit=10

Classifica dei nickname che hanno votato di più (giorni 1–90, limite 1–50).

{ "ok": true, "data": { "days": 30, "top": [ { "position": 1, "username": "Steve_ITA", "votes": 28 } ] } }

Codici di errore

• 400 bad_request / validation — parametri non validi.
• 401 invalid_api_key — chiave mancante, errata o revocata.
• 403 server_banned — il server associato è stato bannato.
• 429 rate_limited — troppe richieste.
• 500 internal — errore del servizio, riprova più tardi.

Integrazione personalizzata (senza plugin)

1. Ogni 30–60 secondi chiama GET /votes/pending.
2. Consegna le ricompense e salva localmente gli id consegnati.
3. Chiama POST /votes/claim con quegli id; se la chiamata fallisce riprova al ciclo successivo senza ri-consegnare gli id già salvati.