> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gestionesala.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Documentazione di Gestione Sala. Il testo completo, incluso il riferimento API, è in https://docs.gestionesala.com/llms-full.txt. Per endpoint, campi e codici di errore la fonte di verità è openapi.yaml: non usare endpoint o campi non documentati.

# Introduzione all'API

> API REST v1 di Gestione Sala: base URL, formato di richieste e risposte, versioning, elenco degli endpoint.

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

```text theme={null}
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](/api/webhook) |
| Import                  | `/imports/guests`, `/imports/reservations`                                |

Ogni endpoint ha una pagina con parametri, risposte e playground nella barra laterale. Il [riferimento completo](/api/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](/api/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](/api/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](/api/errori).
* **Identificativo della richiesta.** Ogni risposta porta `X-Request-Id`.

## Esempio: flusso di prenotazione

```bash theme={null}
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"}'
```

<CardGroup cols={2}>
  <Card title="Autenticazione" icon="key" href="/api/autenticazione">
    Header, formato della chiave, creazione e revoca.
  </Card>

  <Card title="Errori" icon="triangle-exclamation" href="/api/errori">
    Formato dell'errore e codici.
  </Card>

  <Card title="Idempotenza" icon="repeat" href="/api/idempotenza">
    Header `Idempotency-Key` sulle creazioni.
  </Card>

  <Card title="Limiti di richiesta" icon="gauge" href="/api/limiti">
    Richieste al minuto, header `X-RateLimit-*`.
  </Card>

  <Card title="Paginazione" icon="list" href="/api/paginazione">
    Elenchi a cursore e sincronizzazione incrementale.
  </Card>

  <Card title="Webhook" icon="webhook" href="/api/webhook">
    Busta, eventi, firma, ritentativi.
  </Card>
</CardGroup>