Wolk logoWolk

settembre 2026

Feed XML immobiliari: requisiti tecnici e guida alla convalida

Feed XML immobiliari: requisiti tecnici e guida alla convalida

Un feed XML immobiliare è un file XML accessibile via URL che, con codifica UTF-8 e identificativi univoci per ogni annuncio, permette a portali e gestionali di importare e aggiornare automaticamente i dati di un immobile. I requisiti minimi sono sempre gli stessi: encoding corretto, ID stabili nel tempo, struttura raggiungibile pubblicamente o tramite credenziali. Il risultato, se tutto funziona, è una sincronizzazione quotidiana senza intervento manuale: nuovi annunci pubblicati, prezzi aggiornati, immobili venduti rimossi in automatico.

In breve:

  • È fondamentale usare un identificativo stabile nel tempo e sempre lo stesso campo proveniente dal gestionale per evitare duplicati e perdite di storico.
  • Il full feed, che aggiorna tutti gli immobili ogni volta, è preferibile e più sicuro rispetto a un feed incrementale, perché evita il rischio di annunci rimasti pubblicati per errore.
  • Le immagini devono essere URLs pubblici in formato JPEG o PNG, senza hotlinking o errori di raggiungibilità, per garantire una corretta importazione.
  • Validare sempre il file XML con strumenti come il validator W3C e lo schema XSD del portale prima dell’invio per ridurre errori di struttura e encoding.
  • La qualità dei dati, come descrizioni dettagliate e foto di qualità, influisce sulla visibilità e sull’efficacia del posizionamento sui portali immobiliari.
Wolk
Crea annunci immobiliari più rapidamente
Wolk trasforma tour e foto in un annuncio pronto per MLS, un copione video social e un messaggio di testo.

Indice

Cos’è un feed XML immobiliare e come è strutturato

Ogni feed XML immobiliare parte da una dichiarazione standard <?xml version="1.0" encoding="UTF-8"?>. La codifica UTF-8 non è un dettaglio tecnico secondario: molti errori di importazione nascono da caratteri accentati o simboli di valuta scritti con un encoding diverso, che il parser del portale scarta o interpreta male.

La struttura tipica prevede un container principale (spesso chiamato <dataset> o <realestates>) che racchiude una serie di nodi ripetuti, uno per annuncio, con etichette come <annuncio> o <property>. Qui conta molto la sensibilità al maiuscolo/minuscolo: Kyero segnala esplicitamente che il proprio parser è case sensitive, quindi <Price> e <price> non sono la stessa cosa.

I nodi che quasi ogni specifica richiede sono:

  • id o riferimento: identificativo univoco dell’annuncio, stabile nel tempo.
  • prezzo: valore numerico, spesso senza simboli di valuta all’interno del tag.
  • mq o superficie: metratura espressa in un formato numerico coerente.
  • indirizzo, comune, provincia: localizzazione testuale.
  • lat e long: coordinate geografiche per la mappa del portale.
  • descrizione: testo libero, quasi sempre racchiuso in CDATA per evitare conflitti con caratteri speciali come & o <.
  • allegati: URL delle immagini, spesso in un nodo ripetuto tipo <foto>.

Le date, quando presenti (data di aggiornamento, data di inserimento), seguono di solito il formato ISO AAAA-MM-GG, ma ogni gestionale può avere convenzioni proprie: Gestionaleimmobiliare documenta il proprio tracciato con un file XML unico che elenca tutti gli immobili dell’agenzia.

Campi obbligatori e identificativi univoci: come evitare scarti e duplicati

L’identificativo univoco è il punto più fragile di tutta la pipeline. Un external_id o un gid che cambia da un’esportazione all’altra fa scomparire e riapparire lo stesso immobile come se fosse nuovo, con effetti diretti sul posizionamento dell’annuncio e sulle statistiche del portale. Insieme all’ID dell’annuncio serve quasi sempre anche un ID agenzia, per associare correttamente il catalogo al fornitore giusto.

I campi che i portali segnano come obbligatori più di frequente sono:

  • comune (spesso con codice ISTAT associato)
  • prezzo
  • superficie in metri quadri
  • data dell’ultimo aggiornamento (data_upd o simile)
  • tipologia catastale o categoria immobile

Quando l’ID non è coerente, il portale può trattare l’annuncio come duplicato, oppure cancellarlo e ricrearlo perdendo storico di visualizzazioni e contatti ricevuti. Il mapping dal gestionale verso il feed va quindi progettato partendo dalla chiave primaria del database interno, non da un valore calcolato ogni volta (come un numero di riga).

Un consiglio: usa sempre lo stesso campo del database come fonte dell’ID nel feed, anche se cambi gestionale o fornitore di sito. Un ID che muta rompe lo storico dell’annuncio su ogni portale collegato.

Full feed vs incremental: quale modello scegliere e cosa implica

La maggior parte dei portali immobiliari lavora con la logica del “full feed”: ogni prelievo deve contenere l’elenco completo e assoluto degli immobili attivi dell’agenzia, non solo le variazioni. Se un annuncio non compare più nel file, il portale lo interpreta come rimosso e lo disattiva in automatico, come confermano le linee guida sui feed incrementali di Resales Online.

Questo significa che un feed incrementale, pensato per inviare solo le modifiche, non è quasi mai accettato dai portali generalisti: il rischio è che un annuncio venduto rimanga pubblicato per errore, o che un immobile ancora attivo venga cancellato perché assente per sbaglio da un file parziale.

Le implicazioni operative sono concrete:

  • ogni esportazione deve rigenerare l’intero catalogo attivo, non solo le righe cambiate dall’ultimo prelievo
  • la cancellazione di un annuncio avviene semplicemente omettendolo dal file, senza bisogno di un flag “delete” dedicato
  • serve un fallback per gli immobili temporaneamente sospesi (in trattativa, in attesa di documenti), da tenere fuori dal feed pubblico ma non cancellati dal gestionale interno

Il workflow più solido resta comunque quello descritto da Kyero: trattare il feed XML come unica fonte di verità per il portale. Ogni modifica fatta direttamente sull’interfaccia del portale viene sovrascritta al prelievo successivo, quindi ha senso solo intervenire a monte, nel gestionale.

Immagini e allegati: requisiti pratici e fallimenti comuni

Le immagini in un feed XML immobiliare non vengono mai incluse come file allegato: si passano come URL pubblici, uno per ogni foto, piantina o tour virtuale a 360 gradi. Il portale scarica l’immagine direttamente dal link indicato nel nodo dedicato del feed.

I controlli da fare prima di ogni invio sono questi:

  1. Verifica il numero massimo di immagini per annuncio: molti portali impongono un tetto massimo di foto per annuncio, che varia da portale a portale, oltre il quale le immagini eccedenti vengono ignorate.
  2. Controlla i formati supportati: JPEG e PNG sono quasi sempre accettati, mentre WebP o formati proprietari possono causare uno scarto silenzioso.
  3. Evita immagini protette da hotlink: se il server di origine blocca le richieste provenienti da un domino diverso, il portale non riesce a scaricare la foto e l’annuncio resta senza immagini o viene rifiutato.
  4. Testa la raggiungibilità reale dell’URL: un link che restituisce reindirizzamenti multipli, errore 403 o 404 blocca l’import di quell’immagine, anche se il resto del feed è corretto.
  5. Controlla il peso del file: immagini troppo pesanti possono far scadere il timeout di download del portale durante il prelievo notturno.

Un controllo di integrità pre-pubblicazione che verifichi la raggiungibilità effettiva degli URL immagine riduce sensibilmente i rifiuti di import legati a questo singolo punto.

Esempio di tracciato e snippet XML: un file commentato

Un tracciato minimale, coerente con le richieste più comuni dei portali, ha questa forma:

<?xml version="1.0" encoding="UTF-8"?>
<dataset>
  <annuncio>
    <id>AG001-00123</id>
    <riferimento>V-345</riferimento>
    <tipologia>appartamento</tipologia>
    <prezzo>185000</prezzo>
    <mq>85</mq>
    <comune>Roma</comune>
    <indirizzo>Via Appia Nuova 210</indirizzo>
    <lat>41.858</lat>
    <long>12.520</long>
    <descrizione><![CDATA[Luminoso trilocale al terzo piano, con balcone e box auto.]]></descrizione>
    <data_upd>2026-03-04</data_upd>
    <foto>https://esempio.it/immagini/AG001-00123-1.jpg</foto>
    <foto>https://esempio.it/immagini/AG001-00123-2.jpg</foto>
  </annuncio>
</dataset>

Il nodo id e il nodo prezzo sono quasi sempre obbligatori. Il campo data_upd è spesso opzionale ma raccomandato: alcuni portali lo usano per decidere se rielaborare l’annuncio o saltarlo se non è cambiato nulla dall’ultimo prelievo.

Alcuni fornitori, come documentato da CasaScan, separano il catalogo in due file distinti: uno per le agenzie (agenzie.xml) e uno per gli immobili (immobili.xml), con una logica automatica che elimina l’agenzia dal sistema se non è più presente nel primo file.

Sul naming dei file, GestionaleImmobiliare.it raccomanda convenzioni come gestionale_sync.tar.gz per il feed compresso, utile quando il catalogo supera qualche centinaio di immobili e il file XML non compresso diventerebbe troppo pesante per un prelievo rapido.

Convalida e test: strumenti e processo (W3C, XSD, feed di test)

Prima di consegnare un feed a un portale, la convalida tramite il validator W3C resta il passaggio più affidabile per intercettare errori di encoding e struttura XML malformata. Lo strumento segnala subito tag non chiusi, entità non escapate e problemi di codifica che altrimenti emergerebbero solo dopo un rifiuto silenzioso da parte del portale.

Il processo consigliato segue questi passaggi:

  • valida la struttura XML con il validator W3C prima di ogni invio
  • confronta il feed con uno schema XSD ufficiale, quando il portale lo fornisce (Kyero pubblica il proprio XSD e un feed di test scaricabile pubblicamente)
  • prepara un feed di prova con pochi annunci fittizi, invia l’URL al supporto tecnico del portale e attendi un riscontro prima di collegare il catalogo reale
  • tieni un log dei prelievi (data, ora, esito) per capire subito se un cambiamento nel gestionale ha rotto la sincronizzazione

Automatizzare la validazione dentro la pipeline di pubblicazione, invece di farla manualmente prima di ogni invio, riduce in modo netto i ticket di supporto ripetitivi legati agli stessi errori di formato.

Un errore frequente è inviare un feed con encoding dichiarato UTF-8 nell’intestazione ma salvato realmente in un’altra codifica dall’editor di testo: il validator W3C intercetta anche questo disallineamento tra dichiarazione e contenuto reale del file.

Modalità di consegna e schedulazione: URL, FTP e prelievo giornaliero

I portali prelevano il feed in modi diversi, a seconda della piattaforma. Le modalità più comuni sono file XML pubblico su HTTP(S), a volte protetto da basic auth, oppure consegna via FTP o SFTP, oppure caricamento in un’area partner dedicata sul sito del portale stesso.

La frequenza di prelievo segue spesso un orario fisso notturno: AgestaMLS preleva i file attorno all’1:30 di notte e applica controlli di qualità che possono bloccare gli annunci con dati incompleti, escludendoli dalla pubblicazione senza fermare l’intero import.

Alcuni punti operativi da tenere a mente per la schedulazione:

  • il nome del file conta: convenzioni come dataset_IDAGENZIA.xml permettono al portale di riconoscere automaticamente il fornitore senza configurazione manuale aggiuntiva
  • per volumi grandi conviene progettare feed paginati o suddivisi direttamente dal gestionale, con compressione a monte per evitare timeout durante lo scaricamento
  • header HTTP coerenti (content type, content length) evitano che il portale interrompa il download a metà file
  • un feed che risponde con timeout frequenti va spesso spostato su un server con banda dedicata, separato dal sito vetrina dell’agenzia

Errori comuni e checklist di debug per sviluppatori

Quando un annuncio non compare sul portale nonostante sembri corretto nel gestionale, la diagnosi segue quasi sempre lo stesso ordine.

  1. Verifica che l’URL del feed risponda con HTTP 200: un redirect o un errore del server blocca il prelievo prima ancora che il parser legga una riga.
  2. Controlla l’encoding effettivo del file, non solo la dichiarazione nell’intestazione XML.
  3. Valida contro lo schema XSD, se disponibile, per intercettare nodi mancanti o mal posizionati.
  4. Controlla la presenza di tutti i campi obbligatori richiesti dal portale specifico, che spesso differiscono da un fornitore all’altro.
  5. Ispeziona gli URL delle immagini uno per uno: redirect multipli, errori 403/404 o hotlinking bloccato sono la causa più frequente di annunci pubblicati senza foto.
  6. Controlla le coordinate geografiche: lat/long fuori range o invertite fanno comparire l’immobile su una mappa sbagliata o lo fanno marcare come “incompleto” da alcuni portali.

Un consiglio: quando apri un ticket di assistenza con un portale, includi sempre l’URL completo del feed, un esempio dell’annuncio problematico e, se il feed è protetto, credenziali di test valide o una copia temporanea pubblica: questo accorcia i tempi di risposta del supporto tecnico.

Come accelerare la pubblicazione con strumenti moderni: il vantaggio operativo

Gran parte degli errori nei feed XML non nasce dal formato in sé, ma dalla qualità dei dati che arrivano dal gestionale: descrizioni incomplete, campi mancanti, metadata scritti in modo incoerente da un agente all’altro. Wolk affronta questo problema a monte, prima ancora che i dati finiscano nel feed.

Durante il sopralluogo, l’agente descrive a voce ogni ambiente mentre scatta le foto: la trascrizione avviene interamente sul dispositivo, senza caricare l’audio, e in circa 15 secondi produce un kit pronto con testo per l’annuncio, script per i social e messaggio per il cliente. Il vantaggio per chi gestisce il feed è diretto.

  • descrizioni già strutturate e coerenti riducono i campi lasciati vuoti o compilati in modo generico
  • meno tempo passato a rincorrere gli agenti per completare i dati mancanti prima dell’esportazione
  • un flusso più ordinato tra sopralluogo, gestionale e feed XML verso i portali, con meno interventi manuali di correzione

Il kit annuncio generato da Wolk è pensato per essere rifinito prima della pubblicazione, non per sostituire il controllo umano sui dati che finiscono nel feed.

Normative e linee guida specifiche per i feed immobiliari in Italia

In Italia non esiste una legge dedicata al formato tecnico dei feed XML immobiliari: le regole vincolanti arrivano dai singoli portali e gestionali, non da un ente normativo unico. Ogni fornitore, da Kyero a GestionaleImmobiliare.it, pubblica una propria specifica tecnica che l’agenzia deve seguire per essere accettata nel sistema di importazione.

Quello che resta invece sotto normativa generale è il contenuto dei dati trasmessi. La descrizione dell’immobile, il prezzo, la classe energetica quando richiesta e i dati di contatto dell’agenzia devono rispettare le stesse regole di trasparenza commerciale valide per qualunque annuncio pubblicato, indipendentemente dal canale tecnico usato per distribuirlo. Un feed XML non è un’area franca rispetto agli obblighi informativi che l’agenzia ha già verso il cliente finale.

Sul fronte privacy, i dati presenti nel feed (nome dell’agente, numero di telefono, indirizzo dell’immobile) rientrano nel trattamento dati regolato dal GDPR, quindi vanno gestiti con la stessa attenzione riservata a qualsiasi altro canale di pubblicazione dell’agenzia. Prima di collegare un nuovo portale, verificare che l’accordo con il fornitore del feed specifichi chi è responsabile del trattamento dei dati trasmessi automaticamente, soprattutto quando il feed passa attraverso un servizio terzo di normalizzazione o aggregazione.

La responsabilità sulla correttezza dei dati pubblicati resta sempre dell’agenzia, anche quando l’esportazione è automatizzata: un prezzo o una metratura errata nel feed produce lo stesso effetto legale di un errore scritto a mano su un annuncio cartaceo.

Normative e linee guida specifiche per i feed immobiliari in Italia — overview diagram

Strategie di ottimizzazione del feed per migliorare la visibilità sui portali immobiliari

Un feed tecnicamente valido non garantisce automaticamente una buona posizione nei risultati di ricerca del portale. La visibilità dipende in gran parte dalla completezza e dalla qualità dei singoli campi, non solo dalla loro presenza formale.

Le descrizioni scritte con CDATA e ricche di dettagli concreti (superficie utile, esposizione, spese condominiali, anno di ristrutturazione) tendono a performare meglio dei testi generici copiati da un template, perché molti algoritmi di ranking dei portali penalizzano contenuti duplicati o troppo brevi. Aggiornare regolarmente il campo data_upd segnala inoltre freschezza dell’annuncio, un fattore che diversi portali usano per decidere l’ordine di visualizzazione nei risultati di ricerca.

Le immagini contano tanto quanto il testo: un annuncio con almeno 10-15 foto di qualità, comprese piantine quando disponibili, riceve in genere più clic rispetto a uno con due o tre scatti generici. Evitare watermark invasivi o foto a bassa risoluzione aiuta a non essere penalizzati nei filtri di qualità che alcuni portali applicano automaticamente.

Un altro punto spesso trascurato è la normalizzazione delle categorie: se il gestionale usa etichette interne diverse da quelle richieste dal portale (per esempio “bilocale” contro “appartamento 2 stanze”), serve una mappa di conversione per evitare che l’annuncio finisca in una categoria di ricerca sbagliata, invisibile a chi filtra per tipologia corretta. La normalizzazione dei campi tra portali diversi è uno dei passaggi che richiede più cura quando l’agenzia distribuisce lo stesso catalogo su più canali.

Strategie di ottimizzazione del feed per migliorare la visibilità sui portali immobiliari — overview diagram

Metodi di aggiornamento e sincronizzazione dati per garantire la coerenza degli annunci

La coerenza tra gestionale e portali dipende dalla frequenza e dal metodo di sincronizzazione scelti, non solo dalla correttezza del singolo file XML. La maggior parte delle agenzie opta per un prelievo automatico giornaliero, spesso programmato in orario notturno per non sovraccaricare i server durante le ore di traffico più alto.

Il punto critico è mantenere un’unica fonte di verità: se un agente modifica un prezzo direttamente sull’interfaccia del portale invece che nel gestionale, quella modifica viene sovrascritta al prelievo successivo del feed, generando confusione e ticket di supporto inutili. La disciplina operativa più semplice è vietare modifiche manuali sui portali e imporre che ogni cambiamento passi sempre dal gestionale interno.

Per i cataloghi di dimensioni medio-grandi, conviene impostare un controllo automatico che confronti il numero di annunci attivi nel gestionale con quelli effettivamente pubblicati sul portale dopo ogni prelievo. Una discrepanza persistente segnala quasi sempre un problema di campi obbligatori mancanti o di immagini irraggiungibili, non un guasto del portale stesso.

Quando l’agenzia distribuisce lo stesso catalogo su più portali con specifiche diverse, un livello intermedio di normalizzazione tra il gestionale e ciascun feed riduce il rischio di errori: un singolo campo di origine può alimentare formati di uscita differenti, mantenendo però la stessa fonte dati e lo stesso ID univoco su tutti i canali.

Prospettiva per agenzie e sviluppatori: priorità operative e scelte tecnologiche

Chi gestisce un feed XML tende a concentrare gli sforzi sulla struttura del file, ma il vero collo di bottiglia è quasi sempre la qualità dei dati in ingresso. Un ID stabile e una validazione automatizzata valgono più di qualunque ottimizzazione dello schema XML.

Le API dirette diventano interessanti solo sopra una certa soglia di volume e frequenza di aggiornamento: sotto quella soglia, il costo di sviluppo e manutenzione non si giustifica rispetto a un feed XML ben progettato. La frequenza di aggiornamento va bilanciata con il carico sui server, non impostata al massimo per principio.

Nei contratti con fornitori di gestionali o feed, vale la pena chiedere esplicitamente chi è responsabile in caso di errori di importazione ripetuti e quali strumenti di convalida sono già integrati nella pipeline di esportazione prima della consegna ai portali.

— Marco

Wolk per chi pubblica ogni giorno annunci su più portali

Chi gestisce un feed XML immobiliare passa gran parte del tempo non sullo schema, ma sulla compilazione dei dati che quel feed dovrà trasportare: descrizioni, foto, metadata coerenti per ogni immobile. Wolk riduce quel lavoro a monte, trasformando il sopralluogo vocale in un kit annuncio pronto in circa 15 secondi, con trascrizione interamente on-device e nessun dato vocale caricato altrove.

Wolk

Per un’agenzia con un solo agente attivo, il piano Pro costa 14,99 $ al mese per postazione, oppure 143,99 $ all’anno; per team più grandi, il piano Growth aggiunge strumenti di gestione condivisa e workspace collettivo, con posti aggiuntivi acquistabili da 9,99 a 14,99 $ al mese ciascuno. Le agenzie con esigenze di integrazione CRM più profonda possono valutare il piano Brokerage, pensato per il matching automatico tra richieste e immobili e per la pipeline trattative. Chi vuole provare il flusso senza impegno può partire dal piano gratuito con 3 tour incluso e verificare direttamente quanto tempo risparmia prima di ogni esportazione verso i portali.

Fonti

Per chi implementa o convalida un feed XML immobiliare, questi riferimenti tecnici restano i più diretti da consultare:

Domande frequenti

Cos’è un feed XML immobiliare?

È un file XML accessibile via URL che elenca gli immobili di un’agenzia con campi standardizzati (prezzo, superficie, indirizzo, foto), usato dai portali per importare e aggiornare automaticamente gli annunci. Deve rispettare encoding UTF-8 e contenere identificativi univoci per ogni immobile.

Perché il mio feed viene rifiutato dal portale?

Le cause più frequenti sono encoding non conforme, campi obbligatori mancanti o URL delle immagini irraggiungibili. Validare il file con lo strumento W3C prima dell’invio intercetta gran parte di questi problemi.

Qual è la differenza tra full feed e feed incrementale?

Il full feed contiene sempre l’elenco completo degli immobili attivi, mentre l’incrementale trasmette solo le variazioni. La maggior parte dei portali, incluso Kyero, tratta l’assenza di un annuncio nel full feed come segnale di rimozione automatica.

Quante immagini posso inserire in un annuncio del feed?

Il numero massimo varia da portale a portale, con un tetto massimo di foto per annuncio. Le immagini vanno sempre indicate come URL pubblici raggiungibili, senza protezioni hotlink che blocchino il download da parte del portale.

Wolk può aiutare a preparare i dati per il feed XML?

Wolk genera descrizioni e metadata strutturati partendo dalla trascrizione vocale del sopralluogo, riducendo i campi incompleti che spesso causano scarti nel feed. Il servizio è disponibile con un piano gratuito con 3 tour o con abbonamenti Pro e Growth per agenzie con più operatori.

Raccomandati

← Torna al blog