Report sugli annunci

Non ancora attivo. Qui è descritto il contratto definitivo, versione 1.0.0. Finché la sandbox non apre con la prima chiave di test, provalo su un mock del contratto (Test).

I report sugli annunci vanno nel senso opposto al resto dell’API: dici a Gridbeds che fine ha fatto ogni annuncio sul tuo canale e come va. Gridbeds lo mostra all’host nella sua dashboard (visualizzazioni, clic verso la prenotazione, se un annuncio è pubblicato e in evidenza) e lo affianca alle prenotazioni che arrivano da te. Tutte le operazioni qui, compresa la rilettura di un report, richiedono il permesso write:listings, e Gridbeds non invia nessun webhook per loro: è lui a ricevere.

Lo stato di un annuncio

PUT /properties/{property_id}/listing sostituisce lo stato del tuo annuncio di una struttura. Invialo ogni volta che lo stato cambia da te:

{
  "status": "published",
  "rejection": null,
  "public_url": "https://channel.example/listings/12345",
  "promoted": true,
  "promoted_until": "2026-11-30T22:00:00Z",
  "updated_at": "2026-10-18T09:30:00Z"
}

Campo
`status`	`published`: online sul tuo canale. `unpublished`: non online, per scelta tua o dell’host. `pending_review`: nella tua moderazione. `rejected`: rifiutato dalla tua moderazione. Enumerazione aperta.
`rejection`	Obbligatorio con `rejected`, rifiutato con qualsiasi altro stato. Un motivo `reason` (`photos`, `description`, `legal`, `price`, `duplicate`, `policy` o `other`; enumerazione aperta) e un `text` che legge l’host: testo semplice di al massimo 500 caratteri, nella lingua dell’host quando puoi, senza HTML né link.
`public_url`	La pagina HTTPS pubblica dell’annuncio sul tuo canale. Obbligatorio con `published`, altrimenti `null`.
`promoted`	Se l’annuncio è in evidenza adesso (messo in risalto o sponsorizzato) sul tuo canale.
`promoted_until`	Quando finisce la promozione; `null` quando non ha una fine o l’annuncio non è in evidenza.
`updated_at`	Quando lo stato è cambiato da te.

Una sostituzione completa, idempotente: inviare di nuovo lo stesso corpo non cambia nulla.
Vince l’updated_at più recente. Un report più vecchio di quello conservato non cambia nulla e risponde con quello conservato, quindi nuovi tentativi e ordine diverso non fanno danni. Un updated_at più di 300 secondi avanti rispetto all’orologio di Gridbeds viene rifiutato (invalid_parameters, errors[].code updated_at_in_future), così un solo orologio sbagliato non può bloccare il report per sempre.
Una struttura che non puoi leggere come attiva o inattiva riceve lo stesso 404 di GET /properties/{property_id} per un id sconosciuto. Un report già conservato resta, e viene mostrato all’host anche dopo un ritiro.
La risposta è il report conservato da Gridbeds, con property_id e received_at. Un report costa un’unità del tuo limite di richieste.

GET /properties/{property_id}/listing rilegge il report conservato da Gridbeds, e risponde 404 finché non ne invii uno.

Statistiche giornaliere

POST /listing-stats riceve totali giornalieri, un elemento per struttura e per data locale della struttura, al massimo 1.000 per richiesta:

{
  "data": [
    { "property_id": "prp_1qnykkykp69yv8d59hxk5410m9", "date": "2026-10-17", "views": 214, "clicks_to_booking": 9, "impressions": 3870, "saves": 4 }
  ]
}

Campo
`date`	La data locale della struttura: non dopo la sua data odierna, e non più di 90 giorni prima.
`views`	Le visualizzazioni della pagina dell’annuncio.
`clicks_to_booking`	I clic partiti verso la prenotazione (`booking.url` o `url_template`) o che hanno inviato una richiesta di prenotazione.
`impressions`	Le apparizioni nei risultati di ricerca o negli elenchi. Facoltativo.
`saves`	Le volte che l’annuncio è stato salvato tra i preferiti. Facoltativo.

Idempotente per struttura e data. Un nuovo invio sovrascrive il giorno, quindi puoi mandare i dati parziali di oggi tutte le volte che vuoi e correggere un giorno passato inviandolo di nuovo.
Tutto o niente. Una richiesta con un qualsiasi elemento non valido non salva nulla e risponde 400 con una voce in errors[] per ogni elemento non valido (pointer /data/<index>/<member>). Correggi e invia di nuovo tutto il lotto, cosa che l’idempotenza rende sicura.
Un elemento non è valido quando la sua struttura non ti è mai stata distribuita (unknown_property), quando la sua data è dopo la data odierna della struttura o più di 90 giorni prima (date_out_of_range), o quando il lotto indica due volte la stessa struttura e la stessa data (duplicate_day). Una struttura ritirata o cancellata nel frattempo accetta ancora i giorni in cui ti era distribuita.
La risposta dice quanti giorni-struttura sono stati salvati (accepted) e quando (received_at).
I giorni si conservano per 25 mesi, così un host può confrontare un mese con lo stesso mese dell’anno prima, poi si cancellano.
Una richiesta costa max(1, ceil(items / 100)) unità del tuo limite di richieste.

Guida

Riferimento

Report sugli annunci

Lo stato di un annuncio

Statistiche giornaliere

​Lo stato di un annuncio

​Statistiche giornaliere

Lo stato di un annuncio

Statistiche giornaliere