Documentazione

Collega il plugin e il bot

Un’unica API REST collega tutto: plugin Minecraft, bot Discord e sito. Ti basta inviare gli eventi giusti e il sito si aggiorna da solo: online, modalità, elo, classifiche, forum e ticket.

Base URLhttp://site.dragonmc.it/api/v1/

AutenticazioneX-API-Key

FormatoJSON

🔑

La tua API key è in Admin → Integrazioni. Va inviata nell’header X-API-Key (oppure come ?key=). Non metterla mai nel client Minecraft.

Endpoint

Tutti gli endpoint di scrittura richiedono la chiave. Quelli pubblici sono marcati come tali.

Metodo	Endpoint	Descrizione	Auth
GET	/api/v1/status	Stato server e modalità (usato dal sito)	pubblico
POST	/api/v1/heartbeat	Online per modalità + stato (ogni 30-60s)	key
POST	/api/v1/duel/result	Registra un duello e aggiorna l’elo	key
POST	/api/v1/elo/sync	Sync massiva della classifica	key
GET	/api/v1/leaderboard?mode=modern	Classifica pubblica	pubblico
GET	/api/v1/player?name=Nick	Profilo elo di un giocatore	pubblico
POST	/api/v1/discord/link	Collega Discord con codice (/link)	key
GET	/api/v1/discord/outbox	Il bot legge gli eventi da pubblicare	key
POST	/api/v1/discord/inbound	Messaggi da Discord → forum/ticket	key
POST	/api/v1/discord/map	Registra l'ID Discord di thread/canale creato	key
POST	/api/v1/pillars/result	Risultato partita PillarsDuels (FFA)	key
POST	/api/v1/modes/sync	Registra tutte le modalità create sul server	key
POST	/api/v1/ticket/status	Cambia stato ticket da Discord	key
POST	/api/v1/ticket/delete	Elimina definitivamente un ticket	key
POST	/api/v1/ticket/create	Apre un ticket da Discord (/ticket)	key
GET	/api/v1/health	Ping senza autenticazione	pubblico

Esempi

Heartbeat

POST /api/v1/heartbeat

curl -X POST "http://site.dragonmc.it/api/v1/heartbeat" \
  -H "X-API-Key: a00e6140…" \
  -H "Content-Type: application/json" \
  -d '{
    "modes": [
      {"slug":"modern","online":42,"status":"live"},
      {"slug":"smp","online":118,"status":"live"},
      {"slug":"pillars","online":16,"status":"live"}
    ]
  }'

Duello

POST /api/v1/duel/result

curl -X POST "http://site.dragonmc.it/api/v1/duel/result" \
  -H "X-API-Key: a00e6140…" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "modern",   // modern | old | pillars
    "winner": "Draco",
    "loser": "Nightfall",
    "winner_elo": 1284,
    "loser_elo": 1240,
    "elo_delta": 18,
    "arena": "Colosseo",
    "duration": 74
  }'

Sync classifica

POST /api/v1/elo/sync

{
  "mode": "old",
  "players": [
    {"name":"Draco","uuid":"…","elo":1420,"wins":31,"losses":9,"streak":4},
    {"name":"Vex","uuid":"…","elo":1310,"wins":22,"losses":14,"streak":-2}
  ]
}

Bot · outbox

GET /api/v1/discord/outbox

{
  "ok": true,
  "events": [
    {
      "id": 12,
      "target": "forum_thread",
      "ref_id": 4,
      "channel_id": "123…",
      "title": "Cerco team",
      "body": "Testo del post…",
      "color": 15118656
    }
  ]
}

Dopo la pubblicazione il bot conferma con
GET /api/v1/discord/outbox?ack=1&ids=12

Flusso Discord ↔ sito

1. Sito → Discord

Quando un utente apre un ticket o un thread, il sito accoda un evento in discord_outbox. Il bot lo legge e crea canale/thread, poi registra l’ID con POST /api/v1/discord/map.

2. Discord → sito

Ogni messaggio nel thread/canale viene inoltrato a POST /api/v1/discord/inbound con kind, author, content e thread_id o ticket_code.

3. Collegamento account

L’utente genera un codice sul sito e scrive /link CODICE. Il bot chiama POST /api/v1/discord/link con discord_id: il sito collega i due account.

Setup rapido

Apri Admin → Integrazioni, copia l’API key.
Nel plugin (Paper 1.21.x) imposta api-url: http://site.dragonmc.it/api/v1/ e api-key, poi invia heartbeat ogni 30s e il risultato di ogni duello.
Per l’elo, invia solo winner, loser e i nuovi elo calcolati dal tuo sistema (o lascia calcolare al sito con elo_delta omesso).
Nel bot Discord (Node/Python) crea un loop che legge /discord/outbox e un listener messageCreate che chiama /discord/inbound.
Configura OAuth2 in includes/config.php per il collegamento automatico (redirect: http://site.dragonmc.it/discord-callback.php).

Serve una mano?

Il ponte è pronto: se il tuo plugin usa un formato diverso, apri un ticket e adattiamo l’endpoint.

Apri un ticket Vai all’admin