API del server | Documentazione di Noxyr

Cosa espone l'API

L'API è di sola lettura e limitata a un server. È pensata per pagine di stato, fogli di calcolo e strumenti interni che vogliono i numeri mostrati dalla dashboard senza accedere. Non può cambiare impostazioni, chiudere ticket o creare fatture.

Ogni endpoint sta sotto https://noxyrbot.com/api/v1 e restituisce JSON. La chiave identifica il server, quindi nessun endpoint richiede un ID server.

GET /api/v1/: Quali ambiti sono attivi per questa chiave e quali endpoint può raggiungere.
GET /api/v1/server: Nome, icona, numero di membri, membri online, boost e data di creazione.
GET /api/v1/tickets: Totali, conteggi di aperti e chiusi, volume degli ultimi 7 e 30 giorni, valutazione media.
GET /api/v1/activity?days=30: Messaggi, ingressi e uscite giornalieri, fino a 90 giorni.
GET /api/v1/invoices: Numero di fatture, ricavi per valuta e stato del pagamento. Con l'ambito invoice links, ?limit= aggiunge le fatture recenti con un URL scaricabile dell'immagine.
GET /api/v1/reviews: Valutazione media, ripartizione per stelle e le cinque recensioni pubbliche più recenti.
GET /api/v1/giveaways: Conteggi di quelli attivi e conclusi, numero totale di partecipazioni e giveaway in corso.

Creare una chiave

Ogni server ha una sola chiave. Viene generata nella pagina API del server e mostrata una volta sola: viene conservato solo un hash, quindi una chiave persa va rigenerata, il che invalida quella vecchia.

Apri il server nella dashboard e vai su API.
Premi Genera e copia la chiave che inizia con nxr_. Non verrà mostrata di nuovo.
Disattiva gli ambiti che non ti servono. Invoice links è disattivato per impostazione predefinita perché espone le immagini delle fatture dei clienti.
Facoltativo: premi Configura canale per far creare al bot una categoria e un canale API nel server con l'elenco degli endpoint.

La pagina mostra anche quando la chiave è stata usata l'ultima volta e quante richieste ha fatto, il modo più rapido per notare una chiave trapelata. Disattivala con l'interruttore, oppure revocala per eliminarla del tutto.

Ambiti

Gli ambiti regolano gli endpoint, non i singoli campi. Una richiesta a un endpoint il cui ambito è disattivato riceve un 403 con un messaggio che indica l'ambito.

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: Aggiunge l'elenco delle fatture recenti con i link alle immagini. Disattivato per impostazione predefinita.
reviews: /reviews
giveaways: /giveaways

Autenticazione ed esempio di richiesta

Invia la chiave come token Bearer nell'header Authorization. Le chiamate dal browser sono consentite (CORS è aperto), ma una chiave nel codice front-end è una chiave pubblica, quindi chiama l'API da un server che controlli tu.

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

Limiti di richiesta

Ogni chiave può fare 60 richieste al minuto. Il limite viene restituito negli header RateLimit standard in ogni risposta, e superarlo restituisce HTTP 429 con errore "rate_limited". Non interrogare più spesso di quanto cambino i dati: i totali di ticket e vendite si possono leggere una volta al minuto senza problemi.

Errori

Ogni errore è in JSON con un codice di errore leggibile dalle macchine e un messaggio leggibile dalle persone.

401 non autorizzato: L'header Authorization manca, non è un token Bearer, oppure la chiave non esiste.
403 key_disabled: La chiave è stata disattivata nella dashboard.
403 scope_disabled: Questo ambito è disattivato per questa chiave.
404 not_found: Endpoint sconosciuto. Il messaggio elenca quelli validi.
404 guild_unavailable: Il bot non è più nel server.
429 rate_limited: Più di 60 richieste in un minuto.
500 internal_error: Qualcosa non ha funzionato dalla parte di Noxyr. Riprova più tardi.