> ## 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.
# Report sugli annunci
> Di' a Gridbeds che fine ha fatto ogni annuncio sul tuo canale e come va, così l'host lo vede accanto alle prenotazioni che gli mandi.
**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](/it/distribution-api/testing)).
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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//`). 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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.