> ## 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. # Elenca gli eventi > Scope: `events:read`. Ogni evento ha la stessa busta dei webhook. ## OpenAPI ````yaml /openapi.yaml get /events openapi: 3.1.0 info: title: Gestione Sala API version: 1.0.0 description: >- Autenticazione: Authorization: Bearer . Errori: {error:{code,message,details,requestId}}, anche per un percorso che non esiste (404 not_found); un metodo che il percorso non ha è un 405 della piattaforma, senza corpo. Risorsa singola: {nomeRisorsa: {...}}; lista d'attesa: entry. Elenchi: {data,nextCursor}, limit fino a 200. Intervalli di giorni: from/to. serviceDate YYYY-MM-DD e time HH:mm nell'ora del locale; startsAt/endsAt/updatedAt ISO 8601 UTC; timezone IANA. Un id di percorso storto è 404. Ogni risposta porta X-Request-Id; quelle con una chiave riconosciuta anche X-RateLimit-Limit/Remaining/Reset (per la chiave pubblica del widget, il tetto del tuo indirizzo IP); il 429 anche Retry-After. Idempotency-Key: legata a chiave API, operazione e corpo; riusata con un altro corpo è 422 idempotency_key_reused, ancora in corso 409 idempotency_in_progress. Chiavi di prova (gsk_test_, organizzazione di prova): ogni risposta JSON porta livemode:false, nessun webhook, messaggio o sincronizzazione SQUADD parte. Chiave pubblica del widget (gspk_): solo GET /availability, /availability/slots, /availability/days e POST /reservations, dai siti ammessi (CORS, header Origin), con un limite per indirizzo IP; senza serviceTags né externalRef, e la prenotazione creata torna senza i dati dell'ospite. Altrove: 403 forbidden, details.reason publishable_key o origin_not_allowed. servers: - url: https://app.gestionesala.com/api/v1 security: [] tags: - name: Meta description: Identità della chiave, stato del servizio e specifica OpenAPI - name: Locali description: Locali accessibili alla chiave e relativo `venueId` - name: Configurazione del locale description: Turni, chiusure, sale, tavoli, piante, regole e stato della sala - name: Disponibilità description: Disponibilità per orario, per giorno e su un intervallo di giorni - name: Prenotazioni description: Lettura, creazione, modifica e annullamento delle prenotazioni - name: Lista d'attesa description: Voci in attesa di un posto, richiamo e conversione in prenotazione - name: Ospiti description: Rubrica degli ospiti, ricerca per telefono e tag di servizio - name: Eventi e report description: Storico degli eventi, consuntivi ed export delle prenotazioni - name: Webhook description: >- Consegne, reinvio, evento di prova e rotazione del segreto di firma. Firma: X-Gestionesala-Signature = v1=HMAC-SHA256(segreto, "v1\n\n\n"), con X-Gestionesala-Timestamp e X-Gestionesala-Idempotency-Key; in una rotazione due firme separate da virgola. - name: Import description: Import di ospiti e prenotazioni da un altro gestionale paths: /events: get: tags: - Eventi e report summary: Elenca gli eventi description: 'Scope: `events:read`. Ogni evento ha la stessa busta dei webhook.' operationId: listEvents parameters: - name: limit in: query required: false description: Righe per pagina schema: type: integer minimum: 1 maximum: 200 default: 50 - name: cursor in: query required: false description: Il nextCursor della risposta precedente schema: type: string - name: since in: query required: false description: Solo gli eventi dopo questo istante schema: type: string description: Istante ISO 8601 con fuso format: date-time - name: type in: query required: false description: Uno o più tipi schema: type: array items: type: string enum: - reservation_created - reservation_confirmed - reservation_modified - reservation_cancelled - guest_arrived - guest_seated - table_released - reservation_late - reservation_no_show - meal_completed - waitlist_entry_created - compatible_table_freed - guest_profile_changed - waitlist_entry_cancelled - reservation_needs_attention style: form explode: true - name: venueId in: query required: false description: Solo questo locale schema: type: string format: uuid responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Event' nextCursor: anyOf: - type: string - type: 'null' required: - data - nextCursor '400': description: invalid_request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: unauthenticated, api_key_invalid, api_key_revoked content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: forbidden, insufficient_scope content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: rate_limited content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] components: schemas: Event: type: object properties: id: type: string description: 'L''evento: coincide con eventId' format: uuid eventId: type: string description: Lo stesso eventId del webhook format: uuid type: type: string enum: - reservation_created - reservation_confirmed - reservation_modified - reservation_cancelled - guest_arrived - guest_seated - table_released - reservation_late - reservation_no_show - meal_completed - waitlist_entry_created - compatible_table_freed - guest_profile_changed - waitlist_entry_cancelled - reservation_needs_attention createdAt: type: string description: Quando è accaduto il fatto format: date-time venueId: type: string format: uuid apiVersion: type: string const: v1 data: description: >- In /events la fotografia del fatto, com'era quando è accaduto (guest della prenotazione nullo); nel webhook la prenotazione di quando parte, e updatedAt dice quale è più nuova. guest_profile_changed: in /events solo l'id dell'ospite, nel webhook la scheda intera. anyOf: - type: object properties: reservation: anyOf: - $ref: '#/components/schemas/Reservation' - type: 'null' required: - reservation - type: object properties: waitlistEntry: anyOf: - $ref: '#/components/schemas/WaitlistEntry' - type: 'null' required: - waitlistEntry - type: object properties: guest: anyOf: - anyOf: - $ref: '#/components/schemas/Guest' - type: object properties: id: type: string format: uuid required: - id - type: 'null' reason: anyOf: - type: string description: guest_created, profile_changed, service_tags_changed - type: 'null' required: - guest - reason required: - id - eventId - type - createdAt - venueId - apiVersion - data Error: type: object properties: error: type: object properties: code: type: string description: Il codice su cui ramificare message: type: string description: Per chi legge i log details: type: object description: >- Cosa serve per correggere o riprovare: fields (i campi storti), requiredScope, reason; per no_availability anche alternatives, gli orari vicini nella forma di GET /availability properties: fields: type: array items: type: string requiredScope: type: string reason: type: string alternatives: type: array items: $ref: '#/components/schemas/Proposal' requestId: type: string description: Lo stesso valore dell'header X-Request-Id required: - code - message - details required: - error Reservation: type: object properties: id: type: string format: uuid venueId: type: string format: uuid serviceDate: type: string description: Giorno di servizio, YYYY-MM-DD format: date time: type: string description: Ora locale del locale, HH:mm pattern: ^([01]\d|2[0-3]):[0-5]\d$ startsAt: type: string description: Istante ISO 8601 con fuso format: date-time endsAt: type: string description: Istante ISO 8601 con fuso format: date-time partySize: type: integer status: type: string enum: - created - confirmed - arrived - seated - released - completed - no_show - cancelled tableAssigned: type: boolean needsAttention: type: boolean description: Valida, ma da sistemare in sala notes: anyOf: - type: string - type: 'null' source: type: string enum: - phone - voice_agent - floor - waitlist - walk_in - api - import sourceDetail: anyOf: - type: string description: Nome della chiave o channel - type: 'null' externalRef: anyOf: - type: string - type: 'null' guestId: anyOf: - type: string format: uuid - type: 'null' updatedAt: type: string description: Anche la versione, per If-Match format: date-time guest: anyOf: - type: object properties: name: anyOf: - type: string - type: 'null' allergies: anyOf: - type: string - type: 'null' allergens: type: array items: type: string enum: - gluten - crustaceans - eggs - fish - peanuts - soybeans - milk - nuts - celery - mustard - sesame - sulphites - lupin - molluscs required: - name - allergies - allergens - type: 'null' guestDetails: anyOf: - $ref: '#/components/schemas/ReservationGuest' - type: 'null' table: anyOf: - $ref: '#/components/schemas/ReservationTable' - type: 'null' required: - id - venueId - serviceDate - time - startsAt - endsAt - partySize - status - tableAssigned - needsAttention - notes - source - sourceDetail - externalRef - guestId - updatedAt - guest WaitlistEntry: type: object properties: id: type: string format: uuid venueId: type: string format: uuid serviceDate: type: string description: Giorno di servizio, YYYY-MM-DD format: date partySize: type: integer earliestTime: type: string description: Ora locale del locale, HH:mm pattern: ^([01]\d|2[0-3]):[0-5]\d$ latestTime: type: string description: Ora locale del locale, HH:mm pattern: ^([01]\d|2[0-3]):[0-5]\d$ status: type: string enum: - waiting - called - converted - cancelled guestId: anyOf: - type: string format: uuid - type: 'null' reservationId: anyOf: - type: string description: La prenotazione nata dalla conversione format: uuid - type: 'null' createdAt: type: string description: Istante ISO 8601 con fuso format: date-time updatedAt: type: string description: Anche la versione, per If-Match format: date-time guest: anyOf: - type: object properties: name: anyOf: - type: string - type: 'null' phone: type: string required: - name - phone - type: 'null' required: - id - venueId - serviceDate - partySize - earliestTime - latestTime - status - guestId - reservationId - createdAt - updatedAt - guest Guest: type: object properties: id: type: string format: uuid phone: type: string description: E.164 name: anyOf: - type: string - type: 'null' firstName: anyOf: - type: string - type: 'null' lastName: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' allergies: anyOf: - type: string - type: 'null' allergens: type: array items: type: string enum: - gluten - crustaceans - eggs - fish - peanuts - soybeans - milk - nuts - celery - mustard - sesame - sulphites - lupin - molluscs notes: anyOf: - type: string - type: 'null' visitCount: type: integer noShowCount: type: integer cancelledCount: type: integer lastVisitAt: anyOf: - type: string description: Istante ISO 8601 con fuso format: date-time - type: 'null' consents: type: object campaignTags: type: array items: type: string serviceTags: type: array items: type: string externalRef: anyOf: - type: string - type: 'null' createdAt: type: string description: Istante ISO 8601 con fuso format: date-time updatedAt: type: string description: Anche la versione, per If-Match format: date-time required: - id - phone - name - firstName - lastName - email - allergies - allergens - notes - visitCount - noShowCount - cancelledCount - lastVisitAt - consents - campaignTags - serviceTags - externalRef - createdAt - updatedAt Proposal: type: object properties: time: type: string description: Ora locale del locale, HH:mm pattern: ^([01]\d|2[0-3]):[0-5]\d$ startsAt: type: string description: Istante ISO 8601 con fuso format: date-time endsAt: type: string description: Istante ISO 8601 con fuso format: date-time turnTimeMinutes: type: integer seats: type: integer overflowsShift: type: boolean required: - time - startsAt - endsAt - turnTimeMinutes - seats - overflowsShift ReservationGuest: type: object properties: id: type: string format: uuid phone: type: string description: E.164 email: anyOf: - type: string - type: 'null' firstName: anyOf: - type: string - type: 'null' lastName: anyOf: - type: string - type: 'null' name: anyOf: - type: string - type: 'null' allergies: anyOf: - type: string - type: 'null' allergens: type: array items: type: string enum: - gluten - crustaceans - eggs - fish - peanuts - soybeans - milk - nuts - celery - mustard - sesame - sulphites - lupin - molluscs notes: anyOf: - type: string - type: 'null' visitCount: type: integer noShowCount: type: integer externalRef: anyOf: - type: string - type: 'null' updatedAt: type: string description: Istante ISO 8601 con fuso format: date-time required: - id - phone - email - firstName - lastName - name - allergies - allergens - notes - visitCount - noShowCount - externalRef - updatedAt ReservationTable: type: object properties: tableId: anyOf: - type: string format: uuid - type: 'null' tableCombinationId: anyOf: - type: string format: uuid - type: 'null' tables: type: array description: I tavoli occupati, uno per uno items: type: object properties: id: type: string format: uuid name: type: string minSeats: type: integer maxSeats: type: integer required: - id - name - minSeats - maxSeats required: - tableId - tableCombinationId - tables securitySchemes: apiKey: type: http scheme: bearer bearerFormat: gsk_... | gsk_test_... | gspk_... ````