API v1

API per sviluppatori

Integra il tuo server Minecraft con Minecraft-Kobe: controlla se un giocatore ha votato, consegna il premio in gioco, verifica gli obiettivi collettivi. REST + JSON, pensata per plugin, mod e bot.

REST + JSON120 richieste/minPremio una sola volta🚦 Stato del servizio

Come iniziare

Aggiungi il tuo servere aspetta l'approvazione.
Genera la chiavein Profilo → API per sviluppatori. Si vede una sola volta: salvala.
Chiama l'APIcon la chiave in ogni richiesta. I giocatori devono avere Minecraft collegato al profilo.

Prova subito (curl)

curl -H "Authorization: Bearer kobe_xxxxxxxx" \
  "https://minecraft-kobe.it/api/v1/votes/check?player=Steve"

Autenticazione
Header Authorization: Bearer … oppure X-API-Key
Limiti
120 richieste al minuto per chiave (poi 429)
Errori
{ "ok": false, "error": "…", "code": "…" }

GET/api/v1/votes/check?player=Nick

Il giocatore ha votato?

Il check da usare nel tuo if: true se ha votato nelle ultime 24 ore. claimable dice se c'è un premio ancora da consegnare. player accetta nick o UUID.

playerobbligatorio: Nick o UUID del giocatore

Richiesta

curl -H "Authorization: Bearer $KOBE_API_KEY" \
  "https://minecraft-kobe.it/api/v1/votes/check?player=Nick"

Risposta

{ "ok": true, "player": "Steve", "linked": true, "voted": true,
  "votedAt": "2026-11-10T20:14:00Z", "nextVoteAt": "2026-11-11T20:14:00Z",
  "claimed": false, "claimable": true, "voteId": "cm3x…" }

POST/api/v1/votes/claim

Utente vota → premio

Segna il voto come premiato. È atomico: ogni voto si può riscattare una sola volta, quindi non c'è rischio di premi doppi. Corpo: { "player": "Nick" } oppure { "voteId": "…" }.

player: Nick o UUID (nel corpo JSON)
voteId: In alternativa, l'id del voto (nel corpo JSON)

Risposta

{ "ok": true, "claimed": true, "voteId": "cm3x…", "player": "Steve" }
// già riscattato → 409 { "code": "already_claimed" }

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

Voti da premiare (polling)

Elenco dei voti degli ultimi 7 giorni non ancora riscattati, solo di giocatori con Minecraft collegato. Perfetto per un controllo ogni 30-60 secondi dal plugin.

limit: Quanti voti restituire (default 50)

Richiesta

curl -H "Authorization: Bearer $KOBE_API_KEY" \
  "https://minecraft-kobe.it/api/v1/votes/pending?limit=50"

Risposta

{ "ok": true, "count": 1, "votes": [ { "voteId": "cm3x…", "player": "Steve", "uuid": "…", "votedAt": "…" } ] }

GET/api/v1/votes/goal?target=500&period=month

Obiettivo di voti raggiunto?

Il check per i premi collettivi (es. 500 voti questo mese). period: all, month, week, day.

targetobbligatorio: Numero di voti da raggiungere
period: all, month, week o day (default month)

Richiesta

curl -H "Authorization: Bearer $KOBE_API_KEY" \
  "https://minecraft-kobe.it/api/v1/votes/goal?target=500&period=month"

Risposta

{ "ok": true, "period": "month", "target": 500, "current": 512, "reached": true, "remaining": 0, "percent": 100 }

GET/api/v1/votes/total?period=month

Voti totali

Conteggio dei voti del periodo scelto.

period: all, month, week o day

Richiesta

curl -H "Authorization: Bearer $KOBE_API_KEY" \
  "https://minecraft-kobe.it/api/v1/votes/total?period=month"

Risposta

{ "ok": true, "period": "month", "total": 512 }

GET/api/v1/votes/top?period=month&limit=10

Classifica votanti

I migliori votanti (con Minecraft collegato) per mostrarli in un hologram o su un cartello.

period: all, month, week o day
limit: Quanti giocatori (default 10)

Richiesta

curl -H "Authorization: Bearer $KOBE_API_KEY" \
  "https://minecraft-kobe.it/api/v1/votes/top?period=month&limit=10"

Risposta

{ "ok": true, "top": [ { "rank": 1, "player": "Steve", "uuid": "…", "votes": 27 } ] }

GET/api/v1/votes/recent?limit=20

Ultimi voti

Gli ultimi voti ricevuti, utile per un annuncio in chat.

limit: Quanti voti (default 20)

Richiesta

curl -H "Authorization: Bearer $KOBE_API_KEY" \
  "https://minecraft-kobe.it/api/v1/votes/recent?limit=20"

Risposta

{ "ok": true, "votes": [ { "voteId": "…", "player": "Steve", "votedAt": "…", "claimed": true } ] }

GET/api/v1/server

Info server

Dati del server legato alla chiave e contatori voti (totale, mese, settimana, giorno).

Richiesta

curl -H "Authorization: Bearer $KOBE_API_KEY" \
  "https://minecraft-kobe.it/api/v1/server"

Risposta

{ "ok": true, "server": { "id": "…", "name": "…", "online": true, "players": 42 }, "votes": { "total": 3120, "month": 512, "week": 140, "day": 22 } }

Flusso consigliato per i premi

/vota o ingressoIl giocatore entra o digita il comando.
checkSe claimable è true, c'è un premio da dare.
claimSe risponde 200 consegna il premio: ogni voto si riscatta una sola volta.

Per i premi di gruppo usa goal in un controllo periodico (ogni 30-60 s va bene). Chiama sempre l'API in modo asincrono: non bloccare il thread principale del server.

Esempi di codice

Java · Bukkit/Paper

// Bukkit/Paper: premia chi ha votato (esegui in modo asincrono!)
HttpClient http = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://minecraft-kobe.it/api/v1/votes/claim"))
    .header("Authorization", "Bearer " + API_KEY)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"player\":\"" + player.getName() + "\"}"))
    .build();
http.sendAsync(req, HttpResponse.BodyHandlers.ofString()).thenAccept(r -> {
    if (r.statusCode() == 200) // voto valido e mai riscattato → dai il premio
        Bukkit.getScheduler().runTask(plugin, () -> giveReward(player));
});

Node.js

// Node.js 18+ (bot, sito, webhook)
const r = await fetch("https://minecraft-kobe.it/api/v1/votes/check?player=Steve", {
  headers: { Authorization: "Bearer " + process.env.KOBE_API_KEY },
});
const data = await r.json();
if (data.ok && data.claimable) { /* chiama /votes/claim e consegna il premio */ }

Python

# Python 3 (requests)
import os, requests
r = requests.get("https://minecraft-kobe.it/api/v1/votes/total", params={"period": "month"},
                 headers={"Authorization": "Bearer " + os.environ["KOBE_API_KEY"]}, timeout=5)
print(r.json()["total"])

Codici di errore

400bad_requestParametro mancante o non valido

401unauthorizedChiave mancante o errata

403forbiddenLa chiave non può usare questa risorsa (server non approvato)

404not_foundGiocatore o voto non trovato (Minecraft non collegato?)

409already_claimedIl voto è già stato riscattato

429rate_limitedHai superato 120 richieste al minuto: riprova tra poco

5xx—Problema nostro: controlla la pagina Stato e riprova con una pausa

Il sito è in manutenzione o non risponde? Controlla /stato. Per un monitor esterno usa /api/status.

Come iniziare

Aggiungi il tuo servere aspetta l'approvazione.

Genera la chiavein Profilo → API per sviluppatori. Si vede una sola volta: salvala.

Chiama l'APIcon la chiave in ogni richiesta. I giocatori devono avere Minecraft collegato al profilo.

Prova subito (curl)

curl -H "Authorization: Bearer kobe_xxxxxxxx" \
  "https://minecraft-kobe.it/api/v1/votes/check?player=Steve"

Autenticazione
Header Authorization: Bearer … oppure X-API-Key

Limiti
120 richieste al minuto per chiave (poi 429)

Errori
{ "ok": false, "error": "…", "code": "…" }

Flusso consigliato per i premi

/vota o ingressoIl giocatore entra o digita il comando.

checkSe claimable è true, c'è un premio da dare.

claimSe risponde 200 consegna il premio: ogni voto si riscatta una sola volta.

Per i premi di gruppo usa goal in un controllo periodico (ogni 30-60 s va bene). Chiama sempre l'API in modo asincrono: non bloccare il thread principale del server.

Esempi di codice

Java · Bukkit/Paper

// Bukkit/Paper: premia chi ha votato (esegui in modo asincrono!)
HttpClient http = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://minecraft-kobe.it/api/v1/votes/claim"))
    .header("Authorization", "Bearer " + API_KEY)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"player\":\"" + player.getName() + "\"}"))
    .build();
http.sendAsync(req, HttpResponse.BodyHandlers.ofString()).thenAccept(r -> {
    if (r.statusCode() == 200) // voto valido e mai riscattato → dai il premio
        Bukkit.getScheduler().runTask(plugin, () -> giveReward(player));
});

Node.js

// Node.js 18+ (bot, sito, webhook)
const r = await fetch("https://minecraft-kobe.it/api/v1/votes/check?player=Steve", {
  headers: { Authorization: "Bearer " + process.env.KOBE_API_KEY },
});
const data = await r.json();
if (data.ok && data.claimable) { /* chiama /votes/claim e consegna il premio */ }

Python

# Python 3 (requests)
import os, requests
r = requests.get("https://minecraft-kobe.it/api/v1/votes/total", params={"period": "month"},
                 headers={"Authorization": "Bearer " + os.environ["KOBE_API_KEY"]}, timeout=5)
print(r.json()["total"])

Codici di errore

400bad_requestParametro mancante o non valido

401unauthorizedChiave mancante o errata

403forbiddenLa chiave non può usare questa risorsa (server non approvato)

404not_foundGiocatore o voto non trovato (Minecraft non collegato?)

409already_claimedIl voto è già stato riscattato

429rate_limitedHai superato 120 richieste al minuto: riprova tra poco

5xx—Problema nostro: controlla la pagina Stato e riprova con una pausa

Il sito è in manutenzione o non risponde? Controlla /stato. Per un monitor esterno usa /api/status.