Base URL e convenzioni
Base URL API produzione: https://api.shieldplay.it/api/v1. I path seguenti sono relativi a questa base. Invia body JSON con Content-Type: application/json. Risposte corrette usano status 2xx; validazione, autenticazione, autorizzazione e rate limit restituiscono errori 4xx corrispondenti.
GET https://api.shieldplay.it/health
{ "status": "ok", "timestamp": 1780000000000 }Autenticazione dashboard
| Endpoint | Metodo | Uso |
|---|---|---|
| /auth/register | POST | Crea account e organizzazione. |
| /auth/login | POST | Avvia sessione dashboard. |
| /auth/logout | POST | Termina sessione corrente. |
| /auth/me | GET | Legge profilo staff e organizzazione autenticata. |
| /auth/providers | GET | Elenca provider di login attivi. |
| /auth/google/authorize | GET | Avvia Google login se abilitato. |
| /auth/password-reset/request | POST | Richiede reset password. |
| /auth/password-reset/confirm | POST | Completa reset password. |
Il dashboard usa il cookie httpOnly ac_session. I client staff possono inviare anche il JWT corrispondente come Authorization: Bearer <token>. Non incorporare mai token in siti pubblici.
Autenticazione agente
Gli agenti Minecraft usano una chiave specifica del server, non una sessione staff. Generala o ruotala dal flusso gestione server, salvala solo nel config.yml del server e inviala nell’header x-api-key.
x-api-key: TUA_CHIAVE_SPECIFICA_SERVER
content-type: application/jsonIngestione eventi agente
POST https://api.shieldplay.it/api/v1/events/violation
{
"playerUuid": "00000000-0000-0000-0000-000000000000",
"playerName": "ExamplePlayer",
"checkName": "XRayCheck",
"category": "movement",
"severity": "MEDIUM",
"points": 1,
"metrics": { "review_only": true, "evidence_family": "xray_pattern" }
}| Endpoint | Metodo | Scopo payload |
|---|---|---|
| /events/heartbeat | POST | Aggiorna versione agente, salute runtime e stato connessione. |
| /events/players/snapshot | POST | Invia snapshot live limitato; massimo 500 giocatori per richiesta. |
| /events/player/join | POST | Registra entrata giocatore. |
| /events/player/leave | POST | Registra uscita giocatore. |
| /events/violation | POST | Invia check, categoria, gravità, punti e metriche strutturate. |
| /events/staff-access | GET | Recupera UUID staff, esenzioni, lingua GUI e override materiali X-Ray. |
L’API agente accetta categorie combat, movement, interaction e network. review_only=true impedisce esplicitamente che un segnale sia idoneo da solo a una punizione automatica.
Endpoint gestione Owner e staff
| Famiglia endpoint | Funzionalità |
|---|---|
| /servers e /servers/:id/rotate-key | Crea, elenca e gestisce server; ruota una key compromessa. |
| /staff-access | Legge accesso staff Minecraft per server. |
| /staff-access/servers/:serverId | Aggiorna roster Owner/Admin. |
| /staff-access/servers/:serverId/gui-language | Impostazione GUI agente IT/EN riservata Owner. |
| /staff-access/servers/:serverId/check-exemptions | Esenzioni staff esatte per-check riservate Owner. |
| /staff-access/servers/:serverId/xray-rare-ores | Override materiali X-Ray monitorati riservato Owner. |
| /checks, /players, /live-players, /violations, /incidents, /punishments | Dati di revisione e operazioni esposti nel dashboard. |
API notifiche
Usa /webhooks per creare, modificare, eliminare e testare webhook in uscita dell’organizzazione. Iscrivendo un URL Discord a xray.flagged ricevi un embed X-Ray mention-safe. /discord/channels riguarda l’integrazione separata di canali Discord gestiti.
La consegna è asincrona e non blocca una violazione salvata. I cooldown X-Ray Discord sopprimono messaggi duplicati per webhook nella finestra configurata.
Errori, limiti e retry sicuri
Valida l’input prima di riprovare un 400. Aggiorna credenziali staff dopo un 401, verifica ownership o ruolo dopo un 403 e tratta un 404 come risorsa assente o fuori tenant. Per 429 rispetta la finestra di retry e applica backoff esponenziale con jitter. Evita loop stretti dell’agente, mantieni heartbeat ragionevoli e conserva eventi offline per replay controllato.
Billing e webhook Stripe
Il billing dashboard usa endpoint /billing. Il webhook Stripe è un endpoint interno server-side e non deve essere chiamato da agenti o browser. Chiavi pagamento e signing secret appartengono solo alle variabili ambiente del server di produzione.