Sviluppatori · API

API plugin: collega il tuo server di gioco

Collega il tuo server di gioco (Minecraft, Rust, ARK…) alla tua raccolta: i progressi appaiono in gioco e le ricompense vengono assegnate automaticamente.

GET/api/plugin/campaignGET/api/plugin/donations

1. Autenticazione

Generare una chiave

Nella dashboard: Raccolta → scheda Modifica → «Plugin in gioco» → Genera una chiave. La chiave completa (ka_live_…) è mostrata una sola volta: copiala e incollala nella configurazione del tuo plugin.

Una chiave è limitata a una sola raccolta / un solo server.
Viene memorizzata solo l’impronta SHA-256: nessuno può rileggere la tua chiave. Persa? Generane una nuova.
Puoi revocare una chiave in qualsiasi momento; smette di funzionare subito.

Usare la chiave

Invia la chiave nell’intestazione Authorization di ogni richiesta:

header

Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx

Sicurezza: la chiave è un segreto server. Non metterla mai in un client di gioco, un repository pubblico o qualsiasi cosa accessibile ai giocatori.

2. Generalità

URL base	`https://keepalive.gg` · dev locale `http://localhost:3100`
Formato	JSON per richieste e risposte.
Limite di frequenza	~120 richieste / minuto per chiave. Oltre → `429`.
Polling	Un intervallo da 30 a 60 s è più che sufficiente.

Gli errori seguono un formato standard: { "error": { "code", "message" } }

401Chiave assente, non valida o revocata.
404La raccolta non esiste più.
429Troppe richieste, riprova tra un istante.

GET/api/plugin/campaign

Restituisce i progressi della raccolta collegata alla chiave; chiamalo periodicamente per aggiornare la visualizzazione in gioco.

cURL

curl https://keepalive.gg/api/plugin/campaign \
  -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Risposta 200

{
  "campaign": {
    "slug": "skycraft-survie",
    "title": "SkyCraft Survie",
    "game": "minecraft",
    "status": "published",
    "goalKind": "monthly",
    "goalCents": 2000,
    "currency": "EUR",
    "raisedCents": 1450,
    "pct": 73,
    "supporters": 12,
    "rewards": [
      { "minCents": 500, "title": "Role", "description": "…" }
    ]
  }
}

goalCents / raisedCents sono in centesimi · pct già limitato da 0 a 100 · goalKind è monthly o oneshot.

GET/api/plugin/donations

Elenca le donazioni incassate, dalla più vecchia alla più recente, per assegnare le ricompense. Il cursore evita di riscaricare le vecchie donazioni.

Param	Predefinito	Descrizione
`after`	nessuno	Cursore opaco: il `nextCursor` della pagina precedente. Omettilo alla prima chiamata.
`limit`	50	Numero massimo di donazioni (max 50).

cURL

curl "https://keepalive.gg/api/plugin/donations?after=CURSOR" \
  -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Risposta 200

{
  "donations": [
    {
      "id": "don_9f2c…",
      "donorName": "Nova",
      "amountCents": 1000,
      "currency": "EUR",
      "message": "gg",
      "recurring": false,
      "rewardTitle": "Kit VIP",
      "createdAt": "2026-07-21T18:04:11.000Z"
    }
  ],
  "nextCursor": "2026-07-21T18:04:11.000Z|don_9f2c…"
}

Campi esposti (solo pubblici):

Campo	Descrizione
`id`	Identificativo univoco della donazione (serve per deduplicare).
`donorName`	Nome pubblico inserito dal donatore (`null` se anonimo).
`amountCents`	Importo della donazione, in centesimi.
`message`	Messaggio pubblico del donatore (`null` se assente).
`recurring`	`true` se è una donazione mensile.
`rewardTitle`	Livello sbloccato da assegnare in gioco (`null` se assente).
`createdAt`	Data ISO 8601.

Mai un’email, un id Stripe o l’importo netto: solo ciò che è già pubblico nella pagina della raccolta.

Ciclo di polling consigliato

pseudocodice

cursore = carica_cursore()           # vuoto al primo avvio
ids_gestiti = carica_ids()           # anti-duplicato

ogni 30 a 60 s:
  page = GET /api/plugin/donations?after=cursore
  per ogni donazione in page.donations:
    se donazione.id già gestito: continua
    se donazione.rewardTitle e donazione.donorName:
      giocatore = trova_giocatore(donazione.donorName)
      se giocatore: assegna_ricompensa(giocatore, donazione.rewardTitle)
    segna donazione.id come gestito
  se page.nextCursor:
    cursore = page.nextCursor ; salva(cursore)

Deduplica sempre per id: non assegnare mai due volte la stessa ricompensa, nemmeno al limite del cursore.

3. Assegnare la ricompensa al giocatore giusto

KeepAlive non conosce l’account di gioco del donatore, solo il nome pubblico che ha inserito (donorName). La convenzione consigliata:

Invita i tuoi giocatori a donare usando il proprio nome in gioco come nome pubblico.

Il tuo plugin fa corrispondere donorName al giocatore (senza distinzione di maiuscole). Se al momento della donazione non corrisponde nessuno, tieni la ricompensa in sospeso e riassegnala alla riconnessione.

In arrivo: un flusso «codice da riscattare» (/claim <code> in gioco) renderà l’attribuzione affidabile al 100%, indipendentemente dal nome.

Pronto a collegare il tuo server?

Genera una chiave API dal pannello della tua raccolta e segui gli esempi qui sopra.

Apri il mio pannello →