Tutorial de la API de servidores de Discord: estadísticas en directo con JavaScript

Este tutorial explica cómo generar una clave de la API de servidores de Noxyr, llamar a los seis endpoints desde Node.js y el navegador, y mostrar datos de Discord en directo en una página pública. Si alguna vez quisiste un contador real de miembros en tu web que se actualice sin conexión con un bot, esto es justo eso.

Paso 1: genera la clave

Abre el panel de Noxyr, elige tu servidor y ve a Acceso a la API. Haz clic en Generar clave de API. La clave (empieza por nxr_) se muestra una sola vez; cópiala ahora en una variable de entorno. En el servidor solo se guarda un hash SHA-256, así que si pierdes la clave tendrás que generar otra.

Paso 2: define los permisos

Debajo de la clave hay seis interruptores que limitan lo que puede leer la clave: Resumen del servidor, Tickets, Actividad, Facturas, Reseñas y Sorteos. Desactiva todo lo que no necesites: un permiso desactivado devuelve 403 al instante, así que una clave filtrada tampoco puede leer los permisos que nunca activaste.

Paso 3: prueba rápida con curl

curl https://noxyrbot.com/api/v1/server \
  -H "Authorization: Bearer nxr_YOUR_KEY"

Deberías ver JSON con el id de tu servidor, su nombre, la URL del icono, el número de miembros, el número de conectados y los boosts.

Paso 4: llámala desde Node.js

const KEY = process.env.NOXYR_API_KEY;

async function getStats() {
    const [server, tickets, activity] = await Promise.all([
        fetch('https://noxyrbot.com/api/v1/server',              { headers: { Authorization: `Bearer ${KEY}` } }),
        fetch('https://noxyrbot.com/api/v1/tickets',             { headers: { Authorization: `Bearer ${KEY}` } }),
        fetch('https://noxyrbot.com/api/v1/activity?days=7',     { headers: { Authorization: `Bearer ${KEY}` } })
    ]);
    return {
        server:   await server.json(),
        tickets:  await tickets.json(),
        activity: await activity.json()
    };
}

getStats().then(console.log);

Paso 5: llámala desde el navegador

CORS está abierto, así que puedes hacer fetch directamente desde un sitio estático. No incrustes la clave en código del lado del cliente que llegue a usuarios reales: cualquiera que abra las herramientas de desarrollo podría verla. Dos patrones seguros:

• Panel público detrás de un proxy: una pequeña función sin servidor de tu lado lee la clave de una variable de entorno, llama a Noxyr y reenvía el JSON al navegador.
• Herramienta interna de confianza: protege la página con tu propia autenticación y luego introduce la clave.

// Cloudflare Worker / Vercel Edge - key stays on the server
export default {
    async fetch(request, env) {
        const upstream = await fetch('https://noxyrbot.com/api/v1/server', {
            headers: { Authorization: `Bearer ${env.NOXYR_API_KEY}` }
        });
        return new Response(await upstream.text(), {
            headers: { 'content-type': 'application/json', 'cache-control': 'public, max-age=60' }
        });
    }
};

Paso 6: muéstralo en la página

<div id="members">…</div>
<script>
    fetch('/api/live-server-stats')
        .then((r) => r.json())
        .then((data) => {
            document.getElementById('members').textContent =
                `${data.memberCount.toLocaleString()} members · ${data.onlineCount} online`;
        });
</script>

Límites de peticiones y caché

60 peticiones por minuto por clave. El tiempo real queda muy bien en un panel privado, pero es un desperdicio en una web pública: guarda en caché las respuestas de origen durante 30–60 segundos en tu capa de proxy y nunca te acercarás al límite.

Respuestas de error

• 401 unauthorized: clave ausente o incorrecta.
• 403 key_disabled: clave desactivada en el panel.
• 403 scope_disabled: el permiso de ese endpoint está desactivado; corrígelo en el panel.
• 404 guild_unavailable: el bot se ha eliminado de ese servidor.
• 429 rate_limited: reduce el ritmo.

¿Quieres saber por qué la API tiene esta forma? Principios de diseño de API para bots de Discord.