Quick Start — API Pubblica

L’API pubblica di SagraFacile (/api/v1/) ti permette di leggere dati di eventi e statistiche in tempo reale da qualsiasi sistema esterno: dispositivi IoT, dashboard personalizzate, contatori automatici.

Accesso in sola lettura, autenticato tramite chiave API.

In 5 minuti

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

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Sagra del Borgo 2026",
      "isOpen": true,
      "currentDay": { "id": 42, "date": "2026-06-11" }
    }
  ],
  "meta": { "generatedAt": "2026-06-11T20:00:00Z", "eventId": "00000000-..." }
}

curl "https://<tuo-dominio>/api/v1/events/3fa85f64-.../live/item-counts" \
  -H "X-Api-Key: sgf_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "data": [
    { "menuItemId": 12, "itemName": "Birra alla spina", "quantitySold": 134 },
    { "menuItemId": 13, "itemName": "Birra in bottiglia", "quantitySold": 57 }
  ],
  "meta": {
    "generatedAt": "2026-06-11T20:05:30Z",
    "eventId": "3fa85f64-...",
    "dayId": 42
  }
}

Autenticazione

Ogni richiesta deve includere il token in uno di questi due modi:

# Header dedicato (consigliato per IoT)
X-Api-Key: sgf_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
# Header Authorization standard
Authorization: Bearer sgf_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

I token hanno sempre il prefisso sgf_. Un token mancante, malformato, scaduto o revocato restituisce 401 Unauthorized.

Permessi (scope)

Ogni chiave API ha uno o più scope che ne delimitano l’accesso:

Chiavi con scope su un singolo evento

Se crei una chiave vincolata a un evento specifico, essa può accedere solo ai dati di quell’evento:

• GET /api/v1/events restituisce un array con il solo evento vincolato.
• Qualsiasi richiesta che fa riferimento a un altro evento restituisce 404.

Questo è il modello consigliato per dispositivi IoT fissi (un contatore per ogni stand), perché limita il danno in caso di compromissione della chiave.

Rate limit

Le richieste sono limitate per organizzazione (non per singola chiave — creare più chiavi non aggira il limite).

Al superamento del limite la risposta è 429 Too Many Requests con gli header:

Esempio: contatore automatico

Script bash che aggiorna un contatore ogni 30 secondi:

#!/bin/bash
API_KEY="sgf_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE="https://<tuo-dominio>/api/v1"
EVENT_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"
ITEM_ID=12   # ID del prodotto da monitorare
 
while true; do
  response=$(curl -sf \
    -H "X-Api-Key: $API_KEY" \
    "$BASE/events/$EVENT_ID/live/item-counts?menuItemIds=$ITEM_ID")
 
  qty=$(echo "$response" | python3 -c \
    "import json,sys; d=json.load(sys.stdin); print(d['data'][0]['quantitySold'])" 2>/dev/null)
 
  echo "$(date '+%H:%M:%S') — Birre vendute: ${qty:-N/A}"
  sleep 30
done

Versioning

/api/v1/ è un contratto stabile:

• L’aggiunta di campi opzionali nelle risposte è non-breaking e può avvenire in qualsiasi momento.
• La rimozione o rinomina di campi, il cambio di semantica dei parametri, o la modifica dei codici di errore richiedono /api/v2/.

Non farti ingannare da altri path come /api/Analytics/ — quelli sono endpoint interni senza garanzie di stabilità.