Skip to main content
Además del plugin oficial, puedes hablar directamente con la API de Events Whitelist: es la misma que usa el plugin. Sirve para mostrar la whitelist en tu web, integrarla con tu panel de control o construir tu propia sincronización.
URL base: https://whitelist-api.eventsmc.xyz/api/v1

​
Autenticación

Necesitas una clave de vínculo, la misma que genera el plugin:
Se envía en cada petición (y en el handshake del WebSocket) como Bearer token:
La clave se muestra una sola vez al crearla y da acceso de lectura y de baja a tus whitelists. Guárdala en el servidor, nunca en código de cliente ni en un repositorio público. Si se filtra, revócala con /whitelist server-link revoke y crea otra.

​
Alcance de la clave

Si creaste el vínculo con la opción whitelist:, esa clave solo puede tocar esa whitelist: cualquier petición a otra devuelve 403. Sin esa opción, ve todas las whitelists de tu servidor de Discord.

​
Endpoints

​
Listar whitelists

Devuelve las whitelists visibles para la clave, con su id, name, channelId, nickType, registrationMode, maxNicksPerUser, enabled y las listas de roles.

​
Listar los nicks de una whitelist

uuid es null en las cuentas No Premium. Si vas a aplicar la lista en un servidor offline-mode, genera tú el UUID offline (UUID.nameUUIDFromBytes(("OfflinePlayer:" + nick).getBytes(UTF_8))), que es exactamente el que usará ese jugador al entrar. Exportaciones: añade ?format=plain, ?format=easywhitelist o ?format=vanilla y en vez de JSON recibirás el archivo correspondiente, igual que con /whitelist export — ver Exportar.

​
Dar de baja un nick

Es la baja que hace el plugin cuando el staff usa /whitelist remove en el juego. Además de borrar la entrada, el bot revierte los roles que hubiera concedido y lo publica en el canal de logs con origen 🔌 API/plugin. Si el nick ya no estaba, devuelve 404.
La API es de lectura y baja: no existe un endpoint para dar de alta. Las altas se hacen siempre desde Discord (por el jugador o por el staff con /whitelist nick add), que es lo que garantiza que cada nick quede asociado a una cuenta de Discord real.

​
Estado del servicio

Devuelve { "ok": true }. Es el único endpoint que no requiere autenticación.

​
Eventos en tiempo real

​
WebSocket

Mismo Authorization: Bearer en el handshake. Al conectar recibes:
y a partir de ahí, cada alta o baja de tu servidor de Discord:
Los tipos son entry.added y entry.removed.
Reconecta con backoff exponencial y, tras cada reconexión, vuelve a pedir GET /entries para recuperar lo que te perdieras mientras estabas desconectado. Es lo que hace el plugin oficial.

​
Webhooks

Si prefieres que te llamen a ti en vez de mantener una conexión abierta:
El bot hace POST a esa URL con el mismo payload que el WebSocket, en JSON, con un timeout de 5 segundos y sin reintentos. Deja url vacío para desactivar el webhook. El WebSocket y el webhook se pueden usar a la vez.
Usa una URL difícil de adivinar (por ejemplo con un token en la ruta) y comprueba en tu endpoint que el guildId del payload es el tuyo.

​
Códigos de respuesta

​
Límite de peticiones

60 peticiones por minuto y por IP. Es de sobra para cualquier integración normal: si necesitas estar al día al segundo, usa el WebSocket en vez de consultar en bucle.

​
Ejemplo completo

¿Montando una integración?

Cuéntanoslo en el servidor de soporte: te echamos una mano y nos ayuda a decidir qué añadir a la API.