Skip to main content
Ogni richiesta include una chiave API nell’header Authorization con schema Bearer. Una richiesta senza chiave valida riceve 401. Fanno eccezione GET /health e GET /openapi.json, che non richiedono chiave.
GET /me restituisce l’organizzazione, gli scope e i locali della chiave che chiama.

​
Tipi di chiave

Il prefisso identifica il tipo di chiave e l’organizzazione a cui appartiene. Una chiave identifica un’organizzazione e un principale con un ruolo proprio. Ogni richiesta vede solo i dati dell’organizzazione della chiave e dei locali assegnati alla chiave: una risorsa fuori da questo perimetro restituisce 404 not_found, non 403.

​
Scope

Ogni endpoint richiede uno scope, indicato nella sua pagina come Scope: <nome>. Una chiave senza lo scope richiesto riceve 403 insufficient_scope prima che la richiesta legga dati; lo scope mancante è in details.requiredScope. La chiave dell’agente vocale creata da Impostazioni → Collegamenti ha gli scope reservations:read, reservations:write, waitlist:read, waitlist:write, guests:read, guests:write, venues:read, floor:read. Una chiave può essere limitata a un sottoinsieme dei locali dell’organizzazione. I locali esclusi non compaiono negli elenchi e restituiscono 404.

​
Chiave pubblica del widget

La chiave gspk_ è pensata per il codice di una pagina web, quindi è leggibile da chiunque. Per questo il suo perimetro è fisso:
  • Endpoint: solo GET /availability, GET /availability/slots, GET /availability/days e POST /reservations. Ogni altro endpoint risponde 403 forbidden con details.reason: "publishable_key".
  • Origine: l’header Origin deve corrispondere a uno dei siti registrati sulla chiave (da 1 a 20, nella forma https://dominio). Un’origine diversa riceve 403 forbidden con details.reason: "origin_not_allowed". Le risposte ammesse portano gli header CORS.
  • Limite: il limite di richieste vale per indirizzo IP del visitatore (per IPv6, per /64), predefinito 20 al minuto. Vedi Limiti di richiesta.
  • Campi: POST /reservations rifiuta serviceTags ed externalRef con 400 invalid_request. La prenotazione restituita non contiene dati dell’ospite.
Le chiavi segrete non ricevono mai gli header CORS.

​
Chiavi di prova

Un’organizzazione di prova ha solo chiavi gsk_test_ e gspk_test_. Le richieste funzionano come in produzione, con queste differenze:
  • ogni risposta JSON contiene livemode: false;
  • nessun webhook, messaggio o sincronizzazione verso SQUADD parte dall’organizzazione di prova.
L’organizzazione di prova si crea come un’organizzazione normale, indicando che è di prova. Il tipo si decide alla creazione e non cambia.

​
Creare una chiave

1

Apri Collegamenti

Nell’app apri Impostazioni → Collegamenti, sezione Agente vocale. Serve il permesso sui collegamenti in ogni locale della chiave.
2

Assegna un nome

Inserisci un nome che identifichi il sistema che userà la chiave, ad esempio Agente telefono sala. Il nome compare in sourceDetail delle prenotazioni create dalla chiave, se la richiesta non indica un channel.
3

Crea la chiave

Premi Crea una chiave. La chiave viene mostrata una sola volta.
Il server conserva solo l’hash SHA-256 della chiave. Una chiave persa non è recuperabile: creane una nuova e revoca quella precedente.

​
Revocare una chiave

Nella stessa sezione, apri il menu della chiave e scegli Revoca. La revoca ha effetto immediato: le richieste successive con quella chiave ricevono 401 api_key_revoked.

​
Errori di autenticazione e di permesso

​
Conservazione della chiave

Non inserire una chiave segreta nel codice sorgente, in un repository o in una pagina web. Passala al sistema chiamante tramite variabile d’ambiente, ad esempio GESTIONESALA_API_KEY.