Chiavi API

La sezione Chiavi API permette di creare credenziali per integrazioni esterne (dispositivi IoT, dashboard di terze parti, contatori automatici) con accesso in sola lettura alle statistiche e ai dati degli eventi tramite l’API pubblica /api/v1/.

Creare una chiave

1. Vai su Amministrazione → Chiavi API e clicca Nuova chiave.
2. Inserisci un nome descrittivo (es. “Contatore birre stand 1”).
3. Scegli l’ambito:
   • Tutti gli eventi — la chiave può leggere i dati di qualsiasi evento dell’organizzazione.
   • Un evento specifico — la chiave può accedere solo ai dati di quell’evento. Consigliato per dispositivi IoT dedicati a una singola sagra.
4. Seleziona i permessi (vedi tabella sotto).
5. Imposta facoltativamente una data di scadenza.
6. Clicca Crea.

Permessi (scope)

Revocare una chiave

Clicca sull’icona del cestino accanto alla chiave e conferma. La revoca è immediata e non reversibile: tutte le richieste con quel token restituiranno 401 Unauthorized da quel momento in poi.

Filtrare l’elenco

Sopra la tabella ci sono due filtri, che si applicano insieme: una chiave viene elencata solo se soddisfa entrambi.

• Stato — le stesse tre voci della colonna Stato:
  • Attiva: la chiave funziona.
  • Scaduta: la data di scadenza impostata alla creazione è passata. Non è uno stato registrato: viene ricavato confrontando la scadenza con la data odierna, quindi una chiave senza scadenza non diventa mai scaduta.
  • Revocata: la chiave è stata revocata a mano. Una chiave revocata resta tale anche se nel frattempo la sua scadenza è passata.
• Evento — elenca solo gli eventi a cui almeno una chiave è vincolata, più la voce Non legata a un evento per le chiavi create con ambito “Tutti gli eventi”.

Selezionando più voci dello stesso filtro vengono elencate le chiavi che ne soddisfano almeno una.

La pagina si apre senza filtri: l’elenco mostra tutte le chiavi, comprese quelle scadute e revocate. Il comando Azzera tutto compare solo quando un filtro è attivo e riporta l’elenco a come si presenta all’apertura.

Su schermo piccolo i filtri si aprono con il pulsante Filtri: le scelte diventano effettive quando confermi.

Limiti di utilizzo (rate limit)

Per evitare un uso eccessivo delle risorse, le richieste all’API pubblica sono limitate per organizzazione (non per singola chiave: creare più chiavi non aumenta il limite).

Il limite si applica in tempo reale: se il Day Pass scade durante un evento, il limite scende immediatamente al livello Trial.

Se il limite viene superato, l’API risponde 429 Too Many Requests con gli header Retry-After, X-RateLimit-Limit e X-RateLimit-Remaining.

Usare la chiave

Includi il token in ogni richiesta usando uno di questi due header:

curl https://<tuo-dominio>/api/v1/events \
  -H "X-Api-Key: sgf_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

oppure:

curl https://<tuo-dominio>/api/v1/events \
  -H "Authorization: Bearer sgf_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Esempio: contatore in tempo reale

L’endpoint live/item-counts è pensato per dispositivi che interrogano periodicamente le quantità vendute (es. un contatore di birre alla spina):

curl "https://<tuo-dominio>/api/v1/events/<eventId>/live/item-counts" \
  -H "X-Api-Key: sgf_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Risposta:

{
  "data": [
    { "menuItemId": 12, "itemName": "Birra alla spina", "quantitySold": 134 }
  ],
  "meta": {
    "generatedAt": "2026-06-11T13:06:34Z",
    "eventId": "3fa85f64-...",
    "dayId": 42
  }
}

Se non specifichi dayId, l’endpoint usa il giorno evento attualmente aperto (o l’ultimo chiuso, se nessuno è aperto).

Errori comuni

Per sviluppatori