> ## 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 distribuzione

> Leggi le strutture, i prezzi e la disponibilità che gli host su Gridbeds pubblicano sul tuo portale, e sappi quando cambiano.

<Warning>
  **Anteprima: non è ancora attivo nulla.** L'API di distribuzione è un contratto pubblicato nella versione `1.0.0`, e ogni operazione è prevista, non ancora attiva. Oggi puoi sviluppare su un mock del contratto ([Test](/it/distribution-api/testing)); la sandbox apre con la prima chiave di test. Manda i tuoi commenti su qualsiasi parte a [support@gridbeds.com](mailto:support@gridbeds.com).
</Warning>

L'API di distribuzione di Gridbeds è per i portali di annunci e gli altri canali di distribuzione. Dà al tuo canale le sedi, i proprietari e le strutture che gli host su Gridbeds scelgono di pubblicarti, con la disponibilità notte per notte, i prezzi e le restrizioni di ogni struttura, e ti avvisa quando qualcosa cambia.

## I dati li leggi tu, gli avvisi arrivano da noi

Leggi tutto con richieste `GET`. Un webhook dice solo che qualcosa è cambiato e lo nomina: leggi la risorsa che nomina per vedere cosa è cambiato. Gli stessi avvisi li puoi leggere anche come registro ordinato, `GET /events`, ed è così che recuperi quello che ti sei perso.

| Risorsa | Cos'è |
| - | - |
| **Sede** (location) | Un edificio o un indirizzo dove si trovano strutture pubblicate: indirizzo, coordinate, fuso orario, foto. |
| **Proprietario** (owner) | Chi offre le strutture: un'azienda o una persona fisica, con un nome visualizzato e, per un'azienda, i suoi dati legali. |
| **Struttura** (property) | Un annuncio per ogni tipologia di camera: unità, capienza, foto, piani tariffari, costi aggiuntivi, orari di check-in e check-out, regole della casa e i dati legali che chiede il suo paese. |
| **Disponibilità** (availability) | Per struttura e per notte: unità disponibili, soggiorno minimo e massimo, chiusure all'arrivo e alla partenza, e un prezzo per ogni piano tariffario. |
| **Servizio** (amenity) | Il catalogo dei codici dei servizi usati dalle strutture, con i relativi codici OpenTravel. |
| **Evento** (event) | Una voce del registro delle modifiche, la stessa cosa che consegna un webhook. |

`GET /channel` descrive il canale a cui appartiene la tua chiave: l'ambiente, i permessi (scope) della chiave, il tuo limite di richieste e quante strutture ti sono distribuite. Può chiamarlo qualsiasi chiave.

## Ambienti

| Ambiente | URL di base | Chiavi |
| - | - | - |
| Produzione | `https://api.gridbeds.com/api/v1/distribution` | `gbd_live_…` |
| Sandbox | `https://staging-api.gridbeds.com/api/v1/distribution` | `gbd_test_…` |

Si accetta solo HTTPS, con TLS 1.2 o successivo. Una richiesta in HTTP semplice viene rifiutata, mai reindirizzata, perché la sua chiave ha già attraversato la rete in chiaro: considerala compromessa e sostituiscila.

## Convenzioni

* **Gli id** sono stringhe opache con un prefisso (`loc_`, `own_`, `prp_`, `rpl_`, `pho_`, `whk_`, `dlv_`, `evt_`), specifiche del tuo canale e mai riusate. Non interpretarle.
* **Gli istanti** sono RFC 3339 in UTC, al secondo, con la `Z` finale: `2026-10-16T09:30:00Z`.
* **Le notti** sono date nel fuso orario della struttura (`timezone`).
* **Gli importi** sono `{"amount": 45000, "currency": "RON"}`: un intero nelle unità minori ISO 4217, quindi 45000 RON sono 450,00 lei.
* **I testi** sono una mappa da una lingua BCP 47 a testo semplice, e contengono sempre la lingua di origine della struttura: `ro` per una struttura in Romania. Niente HTML, link, indirizzi e-mail o numeri di telefono.
* **Ogni enumerazione è aperta**: accetta anche valori che non conosci.

## Versioni

La versione 1 cresce soltanto: campi nuovi, valori nuovi in un'enumerazione, nuovi tipi di evento e nuovi schemi di identificativi legali arrivano senza una nuova versione. Una modifica incompatibile è una nuova versione, `/v2`, annunciata con almeno 30 giorni di anticipo con le intestazioni `Deprecation` e `Sunset`.

## Continua

<CardGroup cols={2}>
  <Card title="Autenticazione" icon="key-round" href="/it/distribution-api/authentication">
    Chiavi, permessi e rotazione.
  </Card>

  <Card title="Sincronizzazione" icon="refresh-cw" href="/it/distribution-api/synchronisation">
    Elenchi, `updated_since`, versioni e tombstone.
  </Card>

  <Card title="Dati legali" icon="scale" href="/it/distribution-api/legal-data">
    Cosa chiede la legge di ogni paese a un annuncio.
  </Card>

  <Card title="Webhook" icon="webhook" href="/it/distribution-api/webhooks">
    Verifica della firma, nuovi tentativi e sospensione.
  </Card>

  <Card title="Errori e limiti" icon="triangle-alert" href="/it/distribution-api/errors-and-limits">
    Problem details e le intestazioni `RateLimit`.
  </Card>

  <Card title="Test" icon="flask-conical" href="/it/distribution-api/testing">
    Oggi un mock del contratto, poi la sandbox.
  </Card>
</CardGroup>

Ogni pagina sotto **Riferimento** è generata dal contratto, il documento OpenAPI su cui questa API sarà costruita e verificata. Le pagine di riferimento sono in inglese, come il documento da cui sono generate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.