Saltar al contenido
mcserverscout
ES

API de votos

Recompensa dentro del juego a los jugadores que votan. La API devuelve los votos que ha recibido tu servidor, con nicks y horas. Es gratuita y no necesita clave.

Lo básico

  • Las respuestas son JSON. Envía la cabecera Accept: application/json en cada petición.
  • No hace falta autenticación.
  • Límite: 30 peticiones por minuto por dirección IP.
  • Todas las horas están en UTC.
  • Un jugador puede votar por un servidor una vez al día, y un servidor puede recibir como máximo 30 votos al día.

El UUID de tu servidor

Cada servidor de la lista tiene un UUID permanente que lo identifica en la API, así que sigue funcionando aunque cambie la dirección del servidor. Los dueños ven el UUID en la página del servidor. Si no lo encuentras, contacta con nosotros indicando la dirección de tu servidor y te lo enviaremos.

Listar votos

GET https://mcserverscout.com/api/servers/{uuid}/votes

Devuelve los votos del servidor, del más reciente al más antiguo. Los votos anónimos (sin nick) no se incluyen.

Parámetros de consulta

Todos los parámetros son opcionales.

Parámetro Tipo Descripción
nick string Solo los votos con este nick exacto (distingue mayúsculas y minúsculas, de 2 a 128 caracteres).
date_from date Votos emitidos en esta fecha o después, YYYY-MM-DD.
date_to date Votos emitidos hasta el final de esta fecha, inclusive, YYYY-MM-DD.
limit integer Resultados por página, de 1 a 200. Por defecto, 100.
page integer Número de página, de 1 a 100.

Ejemplo de petición

curl -H "Accept: application/json" \
  "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?nick=Steve&date_from=2026-10-23"

Ejemplo de respuesta

{
  "data": [
    {
      "nick": "Steve",
      "created_at": "2026-10-23T14:30:00+00:00"
    }
  ],
  "links": {
    "first": "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?page=1",
    "last": "https://mcserverscout.com/api/servers/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/votes?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 100,
    "to": 1,
    "total": 1
  }
}

Usa links.next o el parámetro page para obtener las páginas siguientes. El objeto meta también contiene los campos de paginación estándar path y links.

Errores

  • 404: no hay ningún servidor con este UUID. Comprueba que has copiado el UUID completo.
  • 422: un parámetro no es válido, por ejemplo limit=500. El objeto errors de la respuesta indica el parámetro y qué le pasa.
  • 429: más de 30 peticiones en un minuto. Espera el tiempo indicado en la cabecera Retry-After.

Recompensar los votos en un plugin

La forma más sencilla: cuando un jugador ejecute un comando como /vote claim, pregunta a la API si ese nick ha votado hoy y entrega la recompensa si lo ha hecho y todavía no la ha reclamado. Guarda la fecha de reclamación de cada jugador para que un voto no se pueda canjear dos veces.

Una comprobación mínima para un plugin de Paper o Spigot (Java 11+), ejecutada fuera del hilo principal:

// Returns true if the player has voted today (UTC).
CompletableFuture<Boolean> hasVotedToday(String nick) {
    String today = LocalDate.now(ZoneOffset.UTC).toString();
    URI uri = URI.create(API_URL
        + "?limit=1&date_from=" + today
        + "&nick=" + URLEncoder.encode(nick, StandardCharsets.UTF_8));

    HttpRequest request = HttpRequest.newBuilder(uri)
        .header("Accept", "application/json")
        .build();

    return HttpClient.newHttpClient()
        .sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .thenApply(response -> response.statusCode() == 200
            && !response.body().contains("\"data\":[]"));
}

Asigna a API_URL el valor https://mcserverscout.com/api/servers/{uuid}/votes con el UUID de tu servidor. Entrega la recompensa de vuelta en el hilo principal, por ejemplo con Bukkit.getScheduler().runTask(...). Si prefieres recompensar a los jugadores automáticamente, consulta la API cada pocos minutos con date_from igual a la fecha de hoy y procesa los nicks que todavía no hayas visto. Mantente muy por debajo del límite de 30 peticiones por minuto.