Skip to main content
Anteprima: non è ancora attivo nulla. Qui è descritto il contratto dell’API di distribuzione (versione 1.0.0). Provalo su un mock del contratto (Test).
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:
  • 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

1

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

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à.
3

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

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.

​
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: Una risorsa withdrawn o deleted è un tombstone, per tutte le risorse, e non viene inviato nient’altro:
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.