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

# Sincronizzazione

> Tieni una copia di quello che ti viene pubblicato: elenchi e cursori, updated_since, versioni, tombstone, il ciclo di vita comune a tutte le risorse e la disponibilità.

<Warning>
  **Anteprima: non è ancora attivo nulla.** Qui è descritto il contratto dell'API di distribuzione (versione `1.0.0`). Provalo su un mock del contratto ([Test](/it/distribution-api/testing)).
</Warning>

Il tuo canale tiene una sua copia di quello che gli host gli pubblicano, e la aggiorna chiedendo cosa è cambiato. I webhook te lo dicono prima, ma la fonte sono gli elenchi e il registro degli eventi: quello che ti sei perso resta lì per 35 giorni.

## Elenchi

`GET /locations`, `/owners`, `/properties`, `/amenities` e `/webhooks` rispondono con una pagina:

```json theme={null}
{
  "data": [ … ],
  "next_cursor": "…"
}
```

* `limit` va da 1 a 500, 100 se non lo indichi; oltre 500 viene rifiutato.
* Per la pagina successiva rimanda `next_cursor` come `cursor`. È opaco e legato alla richiesta che l'ha prodotto. Nell'ultima pagina è `null`.
* `/locations`, `/owners` e `/properties` filtrano per `status`, per esempio `status=active,inactive`, e `/properties` anche per `location_id` e `owner_id`.
* Una singola risorsa si legge con `GET /locations/{location_id}`, `/owners/{owner_id}`, `/properties/{property_id}`.
* Una lettura porta un `ETag` (tutte tranne `GET /availability`); rimandalo come `If-None-Match` e una risposta invariata è `304 Not Modified`, ovunque tranne nei registri delle consegne dei webhook (`/webhooks/{webhook_id}/deliveries`).

Le strutture indicano `location_id` e `owner_id`, quindi leggi sedi e proprietari prima delle strutture che vi fanno riferimento.

## La prima copia, poi solo le modifiche

<Steps>
  <Step title="Leggi tutto una volta">
    Elenca ogni risorsa senza `updated_since`, seguendo `next_cursor` fino alla fine. Conserva ogni risorsa con la sua `version` e annota il `updated_at` più grande che hai ricevuto.
  </Step>

  <Step title="Chiedi cosa è cambiato da allora">
    Elenca di nuovo con `updated_since` uguale a quel `updated_at` più grande. Il limite è **inclusivo**, quindi non serve sovrapporre: quello che è cambiato proprio in quel secondo torna di nuovo, e la versione ti dice se ce l'hai già.
  </Step>

  <Step title="Applica in base alla versione">
    Applica una risorsa solo quando la sua `version` è più alta di quella che hai, e ignora una più bassa. La versione cresce a ogni modifica visibile al tuo canale, ma non è un contatore: non aspettarti valori consecutivi.
  </Step>

  <Step title="Ricomincia quando la finestra è passata">
    Un `updated_since` più vecchio della finestra di conservazione, 35 giorni, riceve `410` con `sync-window-expired`. Risincronizza da zero: leggi tutto una volta, come al primo passo.
  </Step>
</Steps>

## Un solo ciclo di vita per tutte le risorse

Sedi, proprietari, strutture, servizi ed endpoint webhook hanno lo stesso `status`, con lo stesso significato ovunque:

| `status` | Significa |
| - | - |
| `active` | Pubblicato per te e in vigore. |
| `inactive` | Pubblicato, ma non in vigore adesso: una struttura che al momento non si può vendere, una sede o un proprietario con tutte le strutture pubblicate inattive, un endpoint webhook sospeso. Può tornare attivo. |
| `withdrawn` | Non pubblicato per te adesso. Può tornare con lo stesso id e una versione più alta. |
| `deleted` | Definitivo. L'id non viene mai più usato. |

Una risorsa `withdrawn` o `deleted` è un **tombstone**, per tutte le risorse, e non viene inviato nient'altro:

```json theme={null}
{ "id": "prp_1qnykkykp69yv8d59hxk5410m9", "status": "withdrawn", "version": 42, "updated_at": "2026-10-16T09:30:00Z" }
```

I tombstone compaiono in un elenco solo quando invii `updated_since`; senza, esistono solo risorse `active` e `inactive`. Una risorsa letta per id risponde con il suo tombstone. Gestisci tutti e quattro i valori su ogni risorsa, anche uno che quella risorsa oggi non raggiunge.

## Disponibilità e prezzi

La disponibilità si legge per struttura e per notte, nelle date della struttura.

* `GET /properties/{property_id}/availability?from=2026-12-20&to=2026-12-27` risponde con le notti di una struttura in una finestra: `to` è escluso, la finestra è al massimo di 365 notti ed entro l'orizzonte pubblicato. Un `from` precedente a oggi per la struttura viene servito da oggi, e la risposta dice quale finestra ha servito. Una finestra oltre l'orizzonte riceve `400` con `window-beyond-horizon` e l'`horizon_end` della struttura. Una struttura ritirata o cancellata riceve `404`.
* `GET /availability?updated_since=…&from=…&to=…` risponde con le notti cambiate, raggruppate per struttura attiva o inattiva. Una pagina finisce a `limit` strutture o a 5.000 notti, quello che arriva prima, quindi le notti di una struttura possono continuare nella pagina successiva sotto lo stesso `property_id`: applicale per data. Una pagina costa `max(1, ceil(nights / 1000))` unità del tuo limite di richieste.

Ogni notte ha `units_available` (0 vuol dire tutto esaurito), `min_stay` e `max_stay` per un arrivo quella notte, `closed_to_arrival`, `closed_to_departure` e una tariffa per ogni piano tariffario. Il `price` di una tariffa è per `base_occupancy` ospiti, come lo paga l'ospite (IVA inclusa, ricarico applicato), ed è `null` quando la tariffa è `closed`; `extra_guest_price` è il prezzo di un adulto in più, `0` se gratuito, `null` quando il prezzo copre tutti.

## Il registro degli eventi

`GET /events` è il tuo registro delle modifiche, nell'ordine in cui sono state registrate, conservato per 35 giorni. Salva il `last_event_id` di ogni pagina e rimandalo come `since`; `next_cursor` è `null` quando sei in pari. Senza `since` il registro parte dall'evento più vecchio conservato. Compaiono solo i tipi di evento coperti dai permessi della tua chiave: `availability.updated` richiede `read:ari`.

Un `since` più indietro del registro conservato riceve `410` con `event-cursor-expired` e il `latest_event_id`: risincronizza con `updated_since`, poi continua il registro da `latest_event_id`.

Un evento nomina una risorsa e la sua versione oppure, per `availability.updated`, una struttura e un intervallo di notti (`from`, `to` escluso) senza versione: rileggi quell'intervallo. I tipi di evento sono `location.created`, `location.updated`, `location.deleted`, `owner.created`, `owner.updated`, `owner.deleted`, `property.created`, `property.updated`, `property.deleted`, `property.distributed`, `property.withdrawn` e `availability.updated`, e se ne possono aggiungere altri.


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