API do servidor | Documentação do Noxyr

O que a API expõe

A API é somente leitura e restrita a um servidor. Ela serve para páginas de status, planilhas e ferramentas internas que querem os números que o painel mostra, sem login. Ela não pode alterar configurações, fechar tickets nem criar faturas.

Todos os endpoints ficam em https://noxyrbot.com/api/v1 e retornam JSON. A chave identifica o servidor, então nenhum endpoint recebe um ID de servidor.

GET /api/v1/: Quais escopos estão ativados para esta chave e quais endpoints ela consegue acessar.
GET /api/v1/server: Nome, ícone, quantidade de membros, quantidade online, boosts e data de criação.
GET /api/v1/tickets: Totais, contagens de abertos e fechados, volume nos últimos 7 e 30 dias, avaliação média.
GET /api/v1/activity?days=30: Mensagens, entradas e saídas diárias, de até 90 dias.
GET /api/v1/invoices: Contagem de faturas, receita por moeda e status de pagamento. Com o escopo de links de faturas, ?limit= adiciona as faturas recentes com uma URL de imagem para download.
GET /api/v1/reviews: Avaliação média, distribuição de estrelas e as cinco avaliações públicas mais recentes.
GET /api/v1/giveaways: Contagem de sorteios ativos e encerrados, total de participações e os sorteios atuais.

Criando uma chave

Cada servidor tem uma chave. Ela é gerada na página de API do servidor e mostrada uma única vez - só um hash é armazenado, então uma chave perdida precisa ser gerada de novo, o que invalida a antiga.

Abra o servidor no painel e vá em API.
Clique em Gerar e copie a chave que começa com nxr_. Ela não será mostrada de novo.
Desative qualquer escopo que você não precise. Links de faturas vem desativado por padrão porque expõe imagens de faturas de clientes.
Opcional: clique em Configurar canal para que o bot crie no servidor uma categoria e um canal de API com a lista de endpoints.

A página também mostra quando a chave foi usada pela última vez e quantas requisições ela fez, que é a forma mais rápida de perceber uma chave vazada. Desative-a com o interruptor ou revogue para excluí-la por completo.

Escopos

Os escopos controlam endpoints, não campos. Uma requisição a um endpoint cujo escopo está desativado recebe um 403 com uma mensagem que cita o escopo.

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: Adiciona a lista de faturas recentes com links de imagem. Desativado por padrão.
reviews: /reviews
giveaways: /giveaways

Autenticação e exemplo de requisição

Envie a chave como token Bearer no cabeçalho Authorization. As chamadas são permitidas a partir do navegador (o CORS está aberto), mas uma chave em código de front-end é uma chave pública, então chame a API a partir de um servidor que você controla.

curl -H "Authorization: Bearer nxr_your_key" https://noxyrbot.com/api/v1/tickets
Resposta: {"total":128,"open":4,"closed":124,"opened7d":9,"opened30d":41,"closed7d":8,"averageRating":4.6,"ratingsCount":37}

Limites de requisições

Cada chave pode fazer 60 requisições por minuto. O limite é retornado nos cabeçalhos RateLimit padrão em cada resposta, e ultrapassá-lo retorna HTTP 429 com o erro "rate_limited". Não consulte com mais frequência do que os dados mudam - os totais de tickets e vendas podem ser lidos uma vez por minuto sem problemas.

Erros

Todo erro é um JSON com um código de erro legível por máquina e uma mensagem legível por pessoas.

401 não autorizado: O cabeçalho Authorization está ausente, não é um token Bearer, ou a chave não existe.
403 key_disabled: A chave foi desativada no painel.
403 scope_disabled: Esse escopo está desativado para esta chave.
404 not_found: Endpoint desconhecido. A mensagem lista os válidos.
404 guild_unavailable: O bot não está mais no servidor.
429 rate_limited: Mais de 60 requisições em um minuto.
500 internal_error: Algo falhou do lado do Noxyr. Tente de novo mais tarde.