Introduzione all'API

L’API v1 di Gestione Sala espone locali, disponibilità, prenotazioni, lista d’attesa, ospiti, eventi, report, webhook e import a sistemi esterni: agenti vocali, CRM, widget di prenotazione, strumenti di analisi.

Base URL

https://app.gestionesala.com/api/v1

Tutte le richieste usano HTTPS.

Formato

Elemento	Formato
Body di richiesta e risposta	JSON, `Content-Type: application/json`
Date (`serviceDate`)	`YYYY-MM-DD`
Orari (`time`, `earliestTime`, `latestTime`)	`HH:MM`, nel fuso orario del locale
Istanti (`startsAt`, `endsAt`, `updatedAt`)	ISO 8601 in UTC
Numeri di telefono in input	Qualsiasi formato; il server li normalizza in E.164
Numeri di telefono in output	E.164, ad esempio `+393391112233`
ID	UUID

Versioning

La versione è parte del percorso: /api/v1. Non esiste un header di versione.

Risorse

Risorsa	Endpoint
Meta	`/me`, `/health`, `/openapi.json`
Locali e configurazione	`/venues`, turni, chiusure, sale, tavoli, piante, regole, `/service-tags`
Disponibilità	`/availability`, `/availability/slots`, `/availability/days`
Prenotazioni	`/reservations`
Lista d’attesa	`/waitlist`
Ospiti	`/guests`
Eventi e report	`/events`, `/reports/period`, `/reports/eod`, `/exports/reservations`
Webhook	`/webhook-deliveries`, `/webhook-endpoints`. Vedi Webhook
Import	`/imports/guests`, `/imports/reservations`

Ogni endpoint ha una pagina con parametri, risposte e playground nella barra laterale. Il riferimento completo riporta tutti gli endpoint in una sola pagina. La specifica OpenAPI 3.1 è servita anche dall’API: GET /openapi.json.

Comportamento generale

Permessi. Ogni endpoint richiede uno scope; la chiave vede solo i locali a cui è assegnata. Vedi Autenticazione.
Esiti negativi con 200. GET /availability senza disponibilità risponde 200 con available: false, reason e alternatives. GET /guests/lookup senza corrispondenza risponde 200 con found: false.
Elenchi. Gli elenchi restituiscono { "data", "nextCursor" }. Vedi Paginazione.
Annullamento non distruttivo. DELETE /reservations/{id} imposta status: "cancelled". La prenotazione non viene eliminata.
Errori. Tutti gli errori hanno la forma { "error": { "code", "message", "details", "requestId" } }. Vedi Errori.
Identificativo della richiesta. Ogni risposta porta X-Request-Id.

Esempio: flusso di prenotazione

export GS_KEY="gsk_..."
export VENUE="b1e2c3d4-0000-4000-8000-000000000001"

# 1. Verifica la disponibilità
curl -s "https://app.gestionesala.com/api/v1/availability?venueId=$VENUE&serviceDate=2026-09-26&time=20:00&partySize=4" \
  -H "Authorization: Bearer $GS_KEY"

# 2. Cerca l'ospite per numero di telefono
curl -s "https://app.gestionesala.com/api/v1/guests/lookup?phone=3391112233" \
  -H "Authorization: Bearer $GS_KEY"

# 3. Crea la prenotazione
curl -s -X POST "https://app.gestionesala.com/api/v1/reservations" \
  -H "Authorization: Bearer $GS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chiamata-8f2a-prenota" \
  -d '{"venueId":"'"$VENUE"'","serviceDate":"2026-09-26","time":"20:00","partySize":4,"phone":"339 111 22 33","guestName":"Mario Rossi"}'

Autenticazione

Header, formato della chiave, creazione e revoca.

Errori

Formato dell’errore e codici.

Idempotenza

Header Idempotency-Key sulle creazioni.

Limiti di richiesta

Richieste al minuto, header X-RateLimit-*.

Paginazione

Elenchi a cursore e sincronizzazione incrementale.

Webhook

Busta, eventi, firma, ritentativi.

Per iniziare

Meta

Locali

Configurazione del locale

Disponibilità

Prenotazioni

Lista d'attesa

Ospiti

Eventi e report

Webhook

Import

Tutti gli endpoint

Base URL

Formato

Versioning

Risorse

Comportamento generale

Esempio: flusso di prenotazione

Autenticazione

Errori

Idempotenza

Limiti di richiesta

Paginazione

Webhook

​Base URL

​Formato

​Versioning

​Risorse

​Comportamento generale

​Esempio: flusso di prenotazione

Autenticazione

Errori

Idempotenza

Limiti di richiesta

Paginazione

Webhook

Base URL

Formato

Versioning

Risorse

Comportamento generale

Esempio: flusso di prenotazione