> ## Documentation Index > Fetch the complete documentation index at: https://docs.gridbeds.com/llms.txt > Use this file to discover all available pages before exploring further. # API di integrazione > Leggi e crea le prenotazioni e gli ospiti di un'organizzazione dalla tua app, con un token con permessi che la struttura ti rilascia. L'API di integrazione di Gridbeds permette a un'app di lavorare con le prenotazioni e gli ospiti dell'organizzazione che l'ha installata. Ogni pagina sotto **Endpoint** è generata dal documento OpenAPI dell'API, lo stesso file su cui l'API è costruita e verificata, e il suo playground invia richieste reali. Le pagine di riferimento sono in inglese, come il documento da cui sono generate. L'URL di base della produzione è `https://api.gridbeds.com/api`, e ogni percorso inizia con `/v1/integration/`. Il menu dei server del playground offre anche la sandbox. ## Autenticazione Invia un token di integrazione con ogni richiesta: ```http theme={null} Authorization: Bearer ``` Un token appartiene a una sola installazione di un'app. Chi nella struttura può gestire le integrazioni connette l'app in Gridbeds, da **Impostazioni → Integrazioni** (**Marketplace app**), e lì rilascia il token, concedendo i permessi (scope) richiesti dall'app o solo una parte. Il token viene mostrato una volta sola; rilasciarne uno nuovo revoca il precedente. Ogni operazione indica il permesso che richiede: | Permesso | Operazioni | | - | - | | nessuno | [Get the calling installation](/it/api-reference/identity/get-the-calling-installation) | | `reservations.read` | [List reservations](/it/api-reference/reservations/list-reservations), [Get a reservation](/it/api-reference/reservations/get-a-reservation) | | `reservations.write` | [Create a reservation](/it/api-reference/reservations/create-a-reservation) | | `guests.read` | [List guests](/it/api-reference/guests/list-guests) | | `guests.write` | [Create a guest](/it/api-reference/guests/create-a-guest) | Inizia da **Get the calling installation**: risponde con l'installazione, la sua organizzazione, il suo stato, l'app e i permessi concessi al token, e non richiede alcun permesso. ## Un'organizzazione per token Ogni richiesta legge e scrive i dati dell'organizzazione che ha installato l'app, e nient'altro. Un record di un'altra organizzazione risponde 404, esattamente come uno che non esiste. ## Errori Una richiesta rifiutata risponde con un corpo JSON: | Campo | | | - | - | | `message` | Cosa non è andato, in una frase per una persona. Non basarti su di essa: il testo può cambiare e segue la lingua della richiesta. | | `code` | Un identificativo stabile del rifiuto, presente quando c'è, per esempio `idempotency_key_reused`. Basati su questo. | | `errors` | In caso di validazione non superata: i messaggi per ogni campo non valido, per nome del campo. | | Stato | Quando | | - | - | | 401 | Il token manca, è sconosciuto o revocato, oppure è il token di accesso di un utente. | | 403 | Al token non è stato concesso il permesso dell'operazione, oppure la sua installazione è disattivata o in errore. | | 404 | Non c'è un record simile nell'organizzazione del token. | | 409 | La prima richiesta con questo `Idempotency-Key` è ancora in elaborazione (`idempotency_in_flight`). Riprova tra poco. | | 422 | La richiesta non ha superato la validazione, oppure chiede qualcosa che l'organizzazione non può fare (`code` dice cosa). | | 429 | L'installazione ha superato il limite di richieste. | ## Limite di richieste Un'installazione può fare 120 richieste al minuto. Oltre, l'API risponde 429 con l'header `Retry-After`, i secondi da attendere, insieme a `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset` (quando finisce la finestra, come timestamp Unix). Il corpo contiene `error`, `message` e `retry_after`. ## Ripetere una creazione in sicurezza **Create a reservation** e **Create a guest** accettano l'header `Idempotency-Key`. Per almeno 24 ore, la stessa chiave con lo stesso corpo risponde con la prima risposta invece di creare un secondo record. La stessa chiave con un corpo diverso viene rifiutata con 422 (`idempotency_key_reused`). ## Versioni La versione dell'API è nel percorso: `/v1/`. Il riferimento mostra la versione del documento OpenAPI; una modifica che romperebbe un client già costruito su di esso, come un'operazione o un campo di risposta rimosso o un campo di richiesta diventato obbligatorio, viene pubblicata solo come nuova versione maggiore del documento. A chi appartiene il token: l'installazione, la sua organizzazione e i suoi permessi. Elenca, leggi e crea le prenotazioni dell'organizzazione. Elenca e crea i profili degli ospiti per cui si fa una prenotazione. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.