Convenzioni comuni

Versioni e percorsi

Le rotte pubbliche non sono versionate, tranne i link di condivisione:

Percorso	Versione
`/cus/`, `/biz/feed/`, `/site/*`, `/robots.txt`, `/sitemap.xml`	Nessun prefisso
`/v1/share/*`	`/v1`

Il prefisso /v1 appartiene anche alle rotte interne /v1/biz/*, che non fanno parte di questa documentazione.

Formato degli errori

Ogni errore ha lo stesso corpo JSON:

{ "error": "000000:immobile non trovato" }

Il valore di error è sempre una stringa in italiano. Spesso inizia con un codice a sei cifre seguito da :. Non esiste un campo code separato: se ti serve il codice, leggi i primi sei caratteri.

Situazione	Stato HTTP	Esempio di `error`
Corpo o parametri non validi	`400`	`Validation failed` oppure `000000:richiesta non valida`
API key mancante o errata	`401`	`API key mancante` / `Token non valido`
Risorsa inesistente o non pubblica	`404`	`000000:sito non trovato`
Troppe richieste	`429`	`000000:troppe richieste, riprova più tardi`
Servizio non in grado di elaborare	`503`	`000000:servizio momentaneamente non disponibile, riprova più tardi`
Errore interno	`500`	`Errore interno del server`

Due particolarità da conoscere:

Alcuni errori di dominio con codice (NNNNNN:messaggio) escono con stato 500 e non 4xx. Distinguili dall'errore interno generico guardando se il messaggio inizia con un codice.
Gli errori di validazione di un corpo JSON hanno il solo messaggio Validation failed, senza l'elenco dei campi sbagliati. Controlla i vincoli nella documentazione dell'endpoint.

Codici ricorrenti sulle API pubbliche:

Codice	Significato
`000000`	Errore generico di una rotta pubblica (il testo dice cosa)
`000040`	Evento o prenotazione non trovati
`000042`	Fascia oraria non valida

L'elenco completo dei codici condivisi si trova in contracts/src/errors.ts (ERROR_CODES).

Paginazione

Gli elenchi accettano limit e offset e rispondono con:

{ "rows": [ ... ], "total": 37 }

total è il numero complessivo di risultati, indipendente da limit/offset. Per GET /site/properties il valore predefinito di limit è 12 e il massimo 24. Un limit oltre il massimo viene ridotto al massimo.

Il feed /cus/property non è paginato: restituisce tutto in una sola risposta.

Date e orari

Nelle risposte JSON le date sono stringhe ISO 8601 in UTC, ad esempio 2026-10-16T14:30:00.000Z.
Le fasce orarie degli eventi (start, end, slotStart) sono ISO 8601; inviale con il suffisso Z o con l'offset.

Lingue

Le lingue supportate sono it, en, es. Si scelgono con il parametro di query lang (predefinito it). Il testo dell'annuncio di un immobile arriva come un solo oggetto, già nella lingua richiesta:

{ "title": "Luminoso trilocale", "description": "…", "lang": "it" }

Se l'annuncio non esiste nella lingua richiesta, namai ripiega sull'italiano e, in assenza anche di questo, sul primo disponibile: controlla sempre il campo lang per sapere quale hai ricevuto. Se l'immobile non ha nessun annuncio, ad è null.

Cache

Le risposte pubbliche dichiarano Cache-Control; rispettalo per non pesare sul servizio. In sintesi:

Rotta	Cache
`/site/config`	`max-age=60`, `s-maxage=300`
`/site/properties`, `/site/properties/:id`	`s-maxage=120`
`/site/lookups`	`s-maxage=3600`
`/site/events`, `/site/events/summary`	`s-maxage=30`
`/site/image/*`	`max-age=31536000, immutable` (immagini)
Scritture (`POST`) e prenotazioni	`no-store`
`/v1/share/:token/*`	`no-store` per i dati, `private, max-age=3600` per le immagini

Limiti di frequenza

Solo i POST pubblici del sito sono limitati: 5 richieste all'ora per indirizzo IP e 20 all'ora per sito. Il contatore è comune a form contatti, prenotazioni e annullamenti. Superato il limite si ottiene 429.

L'IP del chiamante è letto dall'header CF-Connecting-IP (Cloudflare); in sviluppo da quello della connessione.

Immagini

Gli URL delle immagini sono percorsi relativi allo stesso host (ad esempio /site/image/property/318). Il parametro w ridimensiona: valori ammessi 400, 800, 1200, 1920. Qualunque altro valore restituisce l'originale.