Tutorial da API de servidor do Discord: estatísticas ao vivo em JavaScript

Este tutorial mostra como gerar uma chave da Server API do Noxyr, chamar os seis endpoints a partir do Node.js e do navegador e colocar dados ao vivo do Discord em uma página pública. Se você sempre quis um contador real de membros no seu site que se atualize sem uma conexão de bot, é exatamente isso.

Passo 1: gere a chave

Abra o painel do Noxyr, escolha o seu servidor e vá em API Access. Clique em Generate API Key. A chave (começa com nxr_) é mostrada uma única vez; copie-a para uma variável de ambiente agora. Só um hash SHA-256 é armazenado no servidor, então uma chave perdida exige gerar outra.

Passo 2: defina os escopos

Abaixo da chave, seis chaves controlam o que ela pode ler: Server Overview, Tickets, Activity, Invoices, Reviews, Giveaways. Desative tudo o que não precisar. Um escopo desativado retorna 403 imediatamente, então uma chave vazada ainda não consegue ler escopos que você nunca habilitou.

Passo 3: teste rápido com curl

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

Você deve ver um JSON com o id do servidor, o nome, a URL do ícone, a quantidade de membros, a quantidade online e os boosts.

Passo 4: chame a partir do 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);

Passo 5: chame a partir do navegador

O CORS está aberto, então você pode fazer a requisição diretamente de um site estático. Não coloque a chave em código do lado do cliente que vai para usuários reais: qualquer pessoa que abrisse as DevTools a veria. Dois padrões seguros:

• Painel público atrás de um proxy: uma pequena função serverless do seu lado lê a chave de uma variável de ambiente, chama o Noxyr e repassa o JSON para o navegador.
• Ferramenta interna de confiança: proteja a página com a sua própria autenticação e só então insira a chave.

// 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' }
        });
    }
};

Passo 6: exiba os dados

<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>

Limites de requisições e cache

60 requisições por minuto por chave. O tempo real fica ótimo em um painel privado, mas é desperdício em um site público; faça cache das respostas do Noxyr por 30 a 60 segundos na camada de proxy e você nunca chegará perto do limite.

Respostas de erro

• 401 unauthorized: chave ausente ou inválida.
• 403 key_disabled: chave desativada no painel.
• 403 scope_disabled: o escopo do endpoint está desativado; corrija no painel.
• 404 guild_unavailable: o bot foi removido desse servidor.
• 429 rate_limited: desacelere.

Quer saber por que a API tem esse formato? Princípios de design de API para bots do Discord.