Documentazione dell'API del Bot

Autenticazione

Crea un token nella pagina API del Bot della tua dashboard e invialo nell'header Authorization: Authorization: Bearer <token>. Un token appartiene a un server e legge solo quel server. Viene mostrato una volta; DayZ Hub conserva solo la sua impronta.

curl -H "Authorization: Bearer dhba_..." \
  https://dayzhub.net/api/v1/bot/guilds/<guildId>

URL di base: https://dayzhub.net/api/v1/bot

Endpoint

Ogni risposta è JSON nella stessa busta. Le liste sono paginate con limit (da 1 a 100) e il cursore di page.nextCursor.

{ "ok": true, "data": [ ... ], "page": { "limit": 25, "hasMore": true, "nextCursor": "eyJpZCI6Ij..." } }

Scope

Ogni token ha solo gli scope che gli hai dato. Tutti sono in sola lettura; con questa API non si può cambiare nulla.

Privacy dei membri

I membri compaiono solo dove la funzione li mostra già pubblicamente, come ID Discord. Un membro che si è opposto al trattamento dei dati è sempre mostrato come anonimo, come sotto. Nomi, messaggi, ticket e risposte dei moduli non fanno mai parte dell'API.

{ "id": null, "anonymous": true }

Limiti

I limiti seguono il piano del server. Premium 1: 2 token attivi, 60 richieste al minuto per token. Premium 2: 5 token, 120 al minuto. Premium 3: 10 token, 300 al minuto. Una prova gratuita o un server sponsorizzato conta come Premium 1. Ogni indirizzo IP può fare 300 richieste al minuto. Oltre il limite ricevi 429 con l'header Retry-After. Un piano che scende non revoca nessun token: quelli che hai continuano a funzionare, solo i nuovi sono bloccati finché non torni sotto il limite. Il server ha bisogno di un piano a pagamento o di una prova attiva.

Cache

Le risposte hanno un ETag e una breve cache privata. Invia If-None-Match per ricevere 304 quando nulla è cambiato. Interrogare ogni 30-60 secondi è più che sufficiente.

Browser e CORS

Chiama l'API dal tuo server. CORS è disattivato per impostazione predefinita. Se una pagina web deve chiamarla dal browser di un visitatore, imposta un sito consentito sul token; le richieste da qualsiasi altra origine vengono rifiutate. Tutto ciò che sta in una pagina web è visibile ai visitatori.

Il tuo token, il piano e i limiti

GET /me non controlla il piano. Oltre al token stesso restituisce plan (premium1, premium2, premium3 o none), limits (tokens e perMinute di quel piano) e tokensUsed (token attivi del server). rateLimitPerMin è la frequenza che questo token ha in questo momento.

{ "ok": true, "data": { "guildId": "123456789012345678", "name": "Website", "prefix": "dhba_aB3dE", "scopes": ["guild:read"],
  "allowedOrigin": null, "rateLimitPerMin": 120, "createdAt": "2026-10-01T12:00:00.000Z",
  "plan": "premium2", "limits": { "tokens": 5, "perMinute": 120 }, "tokensUsed": 2 } }

ID di richiesta

Ogni risposta porta l'header X-Request-Id. Se invii un tuo X-Request-Id (fino a 64 lettere, cifre e . _ : -), viene mantenuto, altrimenti ne viene generato uno. Gli errori lo ripetono come requestId. Indicalo quando contatti il supporto.

X-Request-Id: 3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c

{ "ok": false, "error": "rate_limited", "code": "rate_limited", "message": "Too many requests", "requestId": "3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c" }

Errori

Gli errori sono JSON con ok: false, un codice stabile in code (error contiene lo stesso valore), un breve messaggio e il requestId. Decidi in base al codice, mai in base al testo del messaggio.