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.

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).

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