novembre 2026
API dei portali o feed XML: cosa cambia per la tua agenzia

Con le API dei portali ogni annuncio parte da solo, appena lo salvi, e il portale ti dice subito se l’ha accettato. Con il feed XML in modalità batch, invece, generi ogni giorno un unico file con tutti gli immobili e il portale lo legge quando può. Su Immobiliare.it questa seconda strada è definita obsoleta rispetto al servizio REST-XML real time. Se la tua agenzia pubblica spesso, modifica prezzi e ritira immobili venduti, le API ti fanno risparmiare ore di attesa e parecchie telefonate al supporto. Il feed resta utile per i portali che accettano solo un URL da leggere. Qui sotto trovi come funzionano davvero i due sistemi, cosa serve per attivarli e come scegliere.
In breve
- API REST: invii un annuncio alla volta, quando vuoi, anche più volte al giorno; la rimozione è una chiamata esplicita e l’esito arriva in tempo reale.
- Feed XML batch: un file unico con tutti gli annunci, rigenerato ogni 24 ore; ciò che non è nel file viene cancellato dal portale.
- Tempi: in batch la pubblicazione può richiedere da 1 a 48 ore; via API la sincronizzazione è quasi immediata.
- Errori: in entrambi i casi un annuncio che non supera la validazione XSD viene scartato, ma in batch un solo errore può bloccare l’intero flusso.
- Scelta pratica: API per i portali principali e per volumi alti, feed XML per gli aggregatori che leggono un URL.
Indice
- Due modi di far parlare il gestionale con il portale
- API REST e feed batch a confronto
- Come funziona l’invio tramite API
- Come funziona il feed XML in modalità batch
- Requisiti tecnici e dati obbligatori
- Modifiche, rimozioni, errori e duplicati
- Tempi di pubblicazione e lavoro operativo
- Quanto costa ciascuna modalità
- Come scegliere tra API e feed
- Il nostro punto di vista
- Dal sopralluogo al portale, senza moduli
- Domande frequenti
- Fonti
Due modi di far parlare il gestionale con il portale
In entrambi i casi il contenuto è lo stesso: un documento XML che descrive l’immobile con tipologia, contratto, prezzo, superficie, foto e descrizione. Cambia il modo in cui quel documento arriva al portale.
Il feed XML è un file pubblicato a un indirizzo web. Il portale lo scarica a intervalli regolari, lo confronta con quello che ha già e aggiorna gli annunci. Tu non “spingi” nulla: aspetti che il portale passi a leggere.
Le API sono un canale diretto. Il tuo software apre una connessione autenticata con il server del portale e invia il singolo annuncio, riceve una risposta con l’esito e, se serve, l’identificativo assegnato dal portale. È una conversazione, non una bacheca.
La differenza sembra tecnica, ma per un agente si traduce in tre domande molto concrete: quanto tempo passa tra la modifica e la pubblicazione, cosa succede quando un dato è sbagliato e quanto lavoro ti resta in mano per tenere tutto allineato.
API REST e feed batch a confronto
La documentazione di Immobiliare.it descrive entrambe le modalità, ed è il riferimento più utile in Italia perché copre il portale su cui quasi tutte le agenzie pubblicano.
| Criterio | API REST real time | Feed XML batch |
|---|---|---|
| Unità di invio | Un singolo annuncio per chiamata | Un file monolitico con tutti gli annunci |
| Frequenza | In qualsiasi momento, anche più volte al giorno | Rigenerazione ogni 24 ore |
| Tempo di pubblicazione | Quasi in tempo reale | Da 1 a 48 ore |
| Rimozione | Chiamata DELETE esplicita | Implicita: l’annuncio assente dal file viene eliminato |
| Esito | Risposta immediata con codice di errore | Nessun feedback in tempo reale |
| Impatto di un errore | Scartato solo l’annuncio non valido | Un errore può pregiudicare l’intero flusso |
| Volume | Nessun limite di file | Massimo 10.000 annunci per flusso |
| Stato su Immobiliare.it | Modalità consigliata | Modalità obsoleta |
I dati sulla modalità batch, dal limite dei 10.000 annunci alla latenza di 1-48 ore, sono riportati nelle specifiche della modalità batch di Immobiliare.it.
Come funziona l’invio tramite API
Su Immobiliare.it il flusso REST segue passaggi precisi. Conoscerli ti aiuta a capire cosa fa il tuo software quando premi “pubblica”.
- Scrittura dell’annuncio. Il software prepara un XML conforme allo schema XSD, codificato in UTF-8, e lo invia nel corpo di una chiamata PUT all’endpoint che contiene l’identificativo dell’annuncio, per esempio
PUT /ws/import/immobiliare/property/987654321. - Creazione o aggiornamento. Nel payload il nodo
propertyporta l’attributooperation: con il valorewriteil portale aggiorna l’immobile e, se non lo trova, crea un nuovo annuncio. Conarchivelo archivia. In real time ognipropertyè una singola unità, come spiega la documentazione del formato di importazione. - Risposta del portale. Ogni richiesta restituisce uno status HTTP e un codice di errore. Dopo una scrittura riuscita il portale comunica il proprio identificativo numerico dell’annuncio.
- Modifiche successive. Puoi reinviare l’annuncio quando vuoi. Attenzione alla data di ultimo aggiornamento: se quella salvata sul portale è uguale o più recente di quella che invii, l’annuncio non viene aggiornato.
- Rimozione. Per togliere un immobile venduto serve una chiamata DELETE con l’identificativo numerico del portale nell’URL.
Il vantaggio operativo è evidente: cambi il prezzo alle 10, alle 10 e qualche minuto l’annuncio è aggiornato e sai che è andato a buon fine. Se vuoi approfondire la logica di allineamento con questo portale, abbiamo scritto una guida alla sincronizzazione con Immobiliare.it.
Come funziona il feed XML in modalità batch
Nel batch la logica si rovescia. Non invii annunci, pubblichi uno stato completo del tuo portafoglio. Le regole di Immobiliare.it sono rigide:
- il flusso deve superare la validazione con lo schema XSD;
- deve essere aggiornato e rigenerato ogni 24 ore;
- deve contenere sempre tutti gli annunci di tutte le agenzie integrate;
- non può superare i 10.000 annunci: oltre questa soglia il portale indica di passare al REST real time.
La regola che sorprende di più gli agenti è la cancellazione implicita. Se un immobile non compare nel file, al termine dell’importazione il portale lo elimina. Basta un’esportazione parziale, un filtro sbagliato nel gestionale o un file troncato per veder sparire annunci attivi.
Il principio di un feed quotidiano con rimozione degli annunci non inclusi non è solo italiano: chi lavora con più portali all’estero affronta le stesse scelte, come si vede nel confronto tra realestate.com.au e Domain, dove la presenza su un portale o sull’altro pesa sulla visibilità degli immobili.
Un altro aspetto da tenere presente: la frequenza non dipende solo dal metodo. Anche fuori dal settore immobiliare, il marketplace Chrono24 spiega che l’importazione da API avviene comunque una volta al giorno, quindi non c’è una sincronizzazione continua. Prima di dare per scontato il tempo reale, verifica come ciascun portale pianifica le proprie importazioni.
Requisiti tecnici e dati obbligatori
Le due modalità chiedono preparazione diversa. Ecco cosa serve, portale per portale.
Per le API di Immobiliare.it
Per attivare il collegamento REST servono:
- un account fornito dal team Support del portale;
- autenticazione HTTP BASIC;
- la comunicazione preventiva degli IP pubblici dei server che faranno le chiamate;
- normalmente, l’header
X-IMMO-SOURCEche identifica la fonte; - payload conformi allo schema XSD e codificati in UTF-8;
- un
unique-idper ogni annuncio, associato allo username dell’agenzia.
L’identificativo univoco è il cuore di tutto: è ciò che permette al portale di capire che l’annuncio di oggi è lo stesso di ieri, aggiornato, e non un doppione.
Per un feed XML su un aggregatore
Gli aggregatori lavorano quasi sempre con un link al file. Su Agentiz, per esempio, il feed si inserisce come URL nella pagina Importa dell’area personale e deve rispettare requisiti tecnici precisi:
- nessun codice HTML nei testi e nelle descrizioni;
- annunci di un solo utente e di un solo paese per feed, altrimenti servono feed separati;
- un immobile per ogni annuncio;
- campi obbligatori
deal_type,property_typeedexternal_id; - date
creationeupdatedobbligatorie e reali, non generate automaticamente.
L’ultima regola è più importante di quanto sembri. Se il tuo software aggiorna la data di modifica di tutti gli annunci a ogni esportazione, il portale non può distinguere ciò che è cambiato davvero. Sui requisiti di formato e sulla convalida abbiamo raccolto i dettagli nella guida ai feed XML immobiliari e alla loro convalida.
La mappatura dei campi
Qualunque sia il canale, i tuoi dati vanno mappati sui campi del portale. Chrono24 lo dice chiaramente: anche piccole modifiche nei file di input possono richiedere di adattare la mappatura nel tempo. Nel mondo immobiliare succede quando un portale aggiunge una tipologia, cambia le classi energetiche ammesse o rende obbligatorio un campo. Su come evitare gli errori più comuni trovi indicazioni pratiche nell’articolo su lucchetti e mappature per i portali.
Modifiche, rimozioni, errori e duplicati
Qui si vede la differenza reale tra i due sistemi nella vita di tutti i giorni.
Modifiche. Via API invii solo l’annuncio cambiato. In batch rigeneri tutto il file, anche per una virgola. In entrambi i casi conta la data di aggiornamento: se non avanza, la modifica rischia di essere ignorata.
Rimozioni. Via API la rimozione è un’azione voluta: chiami DELETE e l’annuncio sparisce. In batch è una conseguenza: l’annuncio manca dal file e il portale lo toglie. Il primo sistema protegge da cancellazioni accidentali, il secondo le rende possibili con un semplice errore di esportazione.
Errori di validazione. Immobiliare.it applica lo schema XSD a ogni annuncio in ingresso: se non passa, viene scartato. Il portale consiglia di validare il flusso dopo ogni modifica. Via API lo scarto riguarda il singolo immobile e lo scopri subito dalla risposta. In batch non hai feedback immediato e un singolo errore può compromettere l’intero file, con maggiore dipendenza dal supporto per capire cosa è successo.
Duplicati. Il rimedio è lo stesso ovunque: un identificativo stabile. unique-id su Immobiliare.it, external_id su Agentiz. Se il software cambia l’identificativo, per esempio dopo una migrazione o una reimportazione, il portale vede un immobile nuovo e lo pubblica accanto al vecchio. Per riconoscere e sistemare questi casi c’è la nostra guida agli annunci duplicati sui portali.
Tempi di pubblicazione e lavoro operativo
Pensa a un trilocale a Roma acquisito il lunedì mattina. Con le API, finito il sopralluogo e approvato il testo, l’annuncio può essere online in giornata e, se il proprietario accetta un ribasso il martedì, il nuovo prezzo è visibile poco dopo. Con il feed batch lo stesso immobile entra nel file della notte e può comparire dopo un’ora come dopo due giorni: la finestra di 1-48 ore è quella indicata dal portale.
Nel frattempo i primi contatti vanno ad altri annunci. E quando qualcosa non torna, con il batch devi capire se il problema è nel file, nella validazione o nei tempi del portale, senza un esito immediato da leggere.
Il lavoro operativo cambia di conseguenza:
- con le API controlli gli esiti, correggi l’annuncio scartato e lo reinvii;
- con il feed controlli che il file sia completo ogni giorno, verifichi a distanza di ore cosa è stato pubblicato e contatti il supporto quando l’importazione fallisce.
Per un’agenzia con pochi immobili la differenza è fastidiosa. Per un’agenzia con centinaia di annunci e più agenti che li modificano, diventa una questione di organizzazione.
Quanto costa ciascuna modalità
I portali non pubblicano un listino unico per l’integrazione e i costi dipendono molto dal software che usi. Conviene ragionare per voci, che sono diverse nelle due modalità.
Feed XML. L’attivazione è semplice: serve un URL stabile da cui il portale scarica il file. Il costo vero è la manutenzione: generazione quotidiana, controllo della completezza, convalida XSD, adattamento della mappatura quando i requisiti cambiano, tempo speso con il supporto quando un’importazione si blocca. A questo si aggiunge il carico di elaborazione e di traffico di rete, che Immobiliare.it cita tra gli svantaggi del batch.
API REST. L’attivazione chiede più passaggi: account dal supporto, autenticazione, IP comunicati in anticipo, gestione delle risposte e delle rimozioni. Una volta in funzione, però, il lavoro quotidiano si riduce: invii solo ciò che cambia e sai subito cosa è andato storto.
Per un’agenzia la domanda giusta non è “quanto costa l’API”, ma “chi se ne occupa”. Se il collegamento è gestito dal tuo software, il costo è compreso nell’abbonamento e tu lavori solo sui contenuti. Se lo sviluppi in proprio, metti in conto sviluppo iniziale e aggiornamenti periodici. Sul rapporto tra CRM e portali trovi una panoramica nella guida all’integrazione del CRM con i portali.

Come scegliere tra API e feed
Usa questi criteri, nell’ordine:
- Cosa accetta il portale. Su Immobiliare.it la scelta è già indicata: REST real time. Molti aggregatori accettano solo un URL di feed. Spesso userai entrambi.
- Volume di annunci. Oltre 10.000 annunci in un flusso, su Immobiliare.it il batch non è più un’opzione.
- Frequenza delle modifiche. Se cambi prezzi, foto e disponibilità ogni settimana, la latenza del batch pesa sui contatti.
- Rischio di cancellazioni. Se più persone esportano o filtrano il portafoglio, la rimozione implicita del batch è un rischio concreto.
- Controllo degli errori. Se vuoi sapere subito quale annuncio è stato scartato e perché, ti serve la risposta immediata delle API.
Qualunque canale scegli, la qualità dei dati di partenza decide il risultato: un annuncio completo, con testi puliti e senza HTML, supera la validazione al primo invio. Per adattare lo stesso immobile alle regole di ogni portale abbiamo descritto il metodo delle varianti annuncio per portali.
Il nostro punto di vista
Il dibattito tra API e feed XML si concentra di solito sul canale. Noi guardiamo a monte: la maggior parte degli scarti, dei ritardi e dei duplicati nasce prima, quando i dati dell’immobile vengono raccolti di fretta, ricopiati da appunti e incollati in un modulo.
Per questo abbiamo costruito Wolk partendo dal sopralluogo. Cammini, descrivi ogni ambiente a voce mentre scatti le foto e in circa 15 secondi ottieni il kit annuncio: testo pronto per i portali, script per il video social e SMS per il cliente. La trascrizione avviene interamente sul dispositivo, quindi nessun dato vocale viene caricato: la privacy del proprietario e della tua agenzia resta sotto controllo fin dal primo minuto.
Da lì il dato pulito segue il suo percorso: varianti di testo per ogni portale, bozza modificabile prima della pubblicazione, CRM con matching tra richieste e immobili e sincronizzazione con i portali. Un buon canale di pubblicazione rende al massimo quando riceve un annuncio già completo e coerente.
Marco
Dal sopralluogo al portale, senza moduli
Se vuoi arrivare alla pubblicazione con annunci completi e già adattati a ogni portale, Wolk unisce in un’unica piattaforma la creazione del kit annuncio e il CRM con sincronizzazione verso i portali immobiliari. Il piano Free ti permette di provarlo su 3 tour; il piano Pro costa 14,99 USD al mese per postazione oppure 143,99 USD all’anno, e per le agenzie con più agenti c’è il piano Growth, con prezzi che crescono in base agli utenti.

Scopri piani e funzioni su Wolk, il kit annuncio dal sopralluogo, oppure guarda la soluzione Brokerage con CRM se gestisci un team.
Domande frequenti
Il feed XML batch funziona ancora su Immobiliare.it?
La documentazione del portale lo descrive ancora, con regole precise come la rigenerazione ogni 24 ore e il limite di 10.000 annunci. Lo stesso portale però lo considera obsoleto e indica il REST real time come modalità di riferimento. Se stai impostando un’integrazione nuova, conviene partire dalle API.
Perché un annuncio sparisce dal portale senza che io lo abbia cancellato?
Con il feed batch ogni immobile assente dal file viene eliminato al termine dell’importazione. Basta un’esportazione incompleta o un filtro sbagliato. Controlla che il file contenga sempre tutti gli annunci attivi.
Perché la mia modifica di prezzo non compare?
Su Immobiliare.it, se la data di ultimo aggiornamento sul portale è uguale o più recente di quella che invii, l’annuncio non viene aggiornato. Verifica che il software aggiorni la data a ogni modifica reale. Se l’annuncio non supera la validazione XSD, viene invece scartato.
Le API garantiscono sempre la pubblicazione in tempo reale?
Dipende dal portale. Immobiliare.it accetta invii in qualsiasi momento con sincronizzazione quasi immediata, mentre altri sistemi importano anche i dati via API con una frequenza fissa, per esempio una volta al giorno. Controlla la documentazione di ciascun portale.
Come evito i doppioni quando cambio gestionale?
Mantieni gli stessi identificativi univoci degli annunci, come unique-id o external_id. Se cambiano, il portale tratta l’immobile come nuovo e lo pubblica accanto al vecchio.
Fonti
- Immobiliare.it: guida alla sincronizzazione degli annunci
- Immobiliare.it: documentazione per feed di importazione
- Immobiliare.it: specifiche della modalità batch
- Agentiz: requisiti tecnici per feed XML
- Chrono24: documentazione sistema di importazione
- realestate.com.au e Domain a confronto