A API do MineList permite que o seu servidor verifique se um jogador votou, entregue uma recompensa exatamente uma vez e leia estatísticas públicas. Todos os endpoints retornam JSON e usam requisições HTTPS GET simples, então funcionam em qualquer linguagem.
Como obter a sua chave de API
Adicione o seu servidor, reivindique-o e abra o painel do dono. A chave de API aparece na página de configurações do servidor. Mantenha-a em segredo, pois ela identifica o seu servidor. Se vazar, gere uma nova no painel e atualize o seu plugin ou script.
O endereço base de todos os endpoints é https://minelist.eu.
Verificar um voto
GET /api/v1/vote?key=API_KEY&username=NICKInforma se o jogador votou hoje e se a recompensa já foi resgatada.
{"voted":true,"claimed":false,"next_vote_utc":"2026-10-31T00:00:00Z"}votedé true se o nick tem um voto para o seu servidor no dia UTC atual.claimedé true se você já marcou esse voto como resgatado.next_vote_utcé o horário em que o jogador poderá votar de novo.
Resgatar um voto
GET /api/v1/vote/claim?key=API_KEY&username=NICKMarca o voto de hoje como resgatado. Chame-o logo antes de entregar a recompensa, para que o jogador não possa resgatar duas vezes. Respostas possíveis:
| Resposta | Significado |
|---|---|
{"voted":true,"claimed":true} | O voto era válido e agora está resgatado. Entregue a recompensa. |
{"voted":true,"claimed":false,"already_claimed":true} | O voto já tinha sido resgatado antes. Não entregue nada. |
{"voted":false,"claimed":false} | O jogador não votou hoje. |
Listar os votos deste mês
GET /api/v1/votes?key=API_KEYRetorna todos os votos que o seu servidor recebeu no mês atual. É útil para recompensas mensais aos maiores votantes e para rankings no seu próprio site.
Estatísticas públicas do servidor
GET /api/v1/server/<slug>Este endpoint não precisa de chave. O slug é a última parte do endereço do servidor no MineList. Exemplos de campos da resposta:
| Campo | Descrição |
|---|---|
name | Nome do servidor |
url | Site do servidor |
ip | Endereço de conexão |
online | Se a última verificação deu certo |
players | Jogadores online na última verificação |
max_players | Vagas de jogadores |
version | Versão do servidor |
votes_month | Votos neste mês |
votes_total | Votos desde que o servidor foi adicionado |
uptime_30 | Disponibilidade nos últimos 30 dias, em porcentagem |
rating | Avaliação média |
last_check | Horário da última verificação |
Exemplo com curl
Esta é toda a lógica em forma de comando de shell. Qualquer linguagem capaz de enviar uma requisição HTTP, como Java, PHP, Python ou Node.js, faz o mesmo.
curl -s "https://minelist.eu/api/v1/vote/claim?key=API_KEY&username=Steve"Interprete o JSON e, se claimed for true, execute o seu comando de recompensa, por exemplo give Steve diamond 3.
Suporte ao NuVotifier
Se você prefere recompensas instantâneas, sem consultar a API o tempo todo, o MineList pode enviar os votos ao seu servidor pelo NuVotifier. As duas versões do protocolo são aceitas. A versão 1 usa uma chave pública RSA e a versão 2 usa um token.
- Instale o NuVotifier no seu servidor e reinicie-o.
- No painel do dono, informe o host, a porta (8192 por padrão) e a chave pública (v1) ou o token (v2).
- Clique em Enviar voto de teste e confira se o seu servidor registra o voto.
Se o teste falhar, verifique se a porta do Votifier está aberta no seu firewall e se a chave foi copiada sem espaços nem quebras de linha.
Banner ao vivo
Todo servidor tem um banner ao vivo de 468x60 pixels que mostra o status atual e o número de jogadores:
https://minelist.eu/banner/<slug>.pngExemplo de código HTML para incorporar:
<a href="https://minelist.eu/pt/server/seu-slug">
<img src="https://minelist.eu/banner/seu-slug.png" width="468" height="60" alt="Vote em nós no MineList">
</a>Boas práticas
- Guarde as estatísticas públicas em cache por pelo menos um minuto, em vez de chamar a API a cada visualização de página.
- Nunca coloque a chave de API em código do lado do cliente nem em um repositório público.
- Use o endpoint de resgate apenas uma vez por recompensa.