Guida alla sincronizzazione degli annunci su Immobiliare.it

Per sincronizzare automaticamente i propri annunci con i portali di Immobiliare.it S.p.A. è necessario creare file XML (feed) seguendo le specifiche descritte in altre pagine della documentazione.

I feed possono essere composti da un unico annuncio ed essere inviati al nostro servizio REST per essere integrati in real-time (scelta consigliata), oppure essere file monolitici da sincronizzare quotidianamente in modalità batch (obsoleto).

Modalità API REST

Basata su servizio REST-XML è la soluzione più efficiente per garantire la sincronizzazione dati con immobiliare.it quasi in tempo reale. Vi sarà fornito, dal nostro team Support, un account da utilizzare per l'autenticazione con il web service e avrete la possibilità di inviare gli aggiornamenti dei annunci in qualsiasi momento e senza limiti (anche per lo stesso annuncio più volte al giorno) attraverso le API di Immobiliare.it. E' previsto un periodo di prova durante il quale saranno fornite le credenziali di un'agenzia di test per permettere un agevole sviluppo del flusso di chiamate.

Autenticazione

L'accesso agli endpoint è disciplinato da autenticazione. Prima dell'attivazione dovrete comunicare gli IP pubblici dei server dai quali partiranno le chiamate REST. Accedete a ogni URL attraverso autenticazione HTTP BASIC. Ogni chiamata dovrà quindi contenere username e password che vi saranno forniti dal team Support. Normalmente è inoltre richiesto un header aggiuntivo chiamato X-IMMO-SOURCE, Anch'esso fornito insieme allo username.

Endpoint

Consultate il file swagger per dettagli e modalità di utilizzo

{···}

Payload in scrittura

Ogni endpoint di scrittura deve essere fornito di uno specifico payload xml, coerente con la relativa sezione dello schema XSD. Lo schema stesso è fornito di annotazione esplicative.

Il documento XML ottenuto va quindi comunicato al nostro entrypoint REST nel corpo di una chiamata PUT.

Per esempio:

PUT /ws/import/immobiliare/property/987654321

Seguono altri dettagli implementativi.

Il documento XML deve rispettare questi requisiti:

deve superare la validazione dello schema XSD
deve adottare la codifica dei caratteri UTF-8

Richieste di rimozione

Contrariamente alla modalità batch, con le API REST è importante comunicare esplicitamente la rimozione degli annunci dalla pubblicità. Per fare questo è necessaria una chiamata http all'endpoint con metodo DELETE avendo cura di specificare, in coda alla URL, l'identificativo numerico del portale (recepibile da /ServiceResponse/idListing, alla fine delle operazioni di scrittura).

Per esempio:

DELETE /ws/import/immobiliare/property/987654321

Risposte degli Endpoint

Nel rispetto dell'architettura REST a ogni richiesta corrisponde, in risposta, uno status HTTP e un oggetto XML chiamato ServiceResponse contenente un ErrorCode e altre informazione utili. Di seguito un esempio. L'ordine dei nodi XML non è garantito:

<ServiceResponse>
	<Result>true</Result>
	<EntityID>as-4fr5</EntityID>
	<EntityOwnerID>67012</EntityOwnerID>
	<RealEstate>someone@some.where</RealEstate>
	<ErrorCode>0</ErrorCode>
	<ErrorMessage>Success</ErrorMessage>
	<idListing>164578906</idListing>
	<lock>false</lock>
	<RequestID>3AA36B26-8771-45C5-9850-26EADEB13129</RequestID>
</ServiceResponse>

Significato dei campi presenti nel messaggio di risposta:

Nome	Tipo	Obbligatorio	Descrizione
Result	Boolean	Yes	Esito della richiesta
EntityID	String	Yes	ID del gestionale
EntityOwnerID	String	Yes	ID dell'agenzia nel gestionale, se disponibile
RealEstate	String	Yes	Username dell'agenzia
ErrorCode	Integer	Yes	Status della richiesta, vedi la lista completa in basso per i valori
ErrorMessage	String	Yes	Messaggio di errore per la richiesta, se disponibile
idListing	Integer	Yes	ID dell'annuncio processato su immobiliare.it
lock	Boolean	Yes	Risorsa bloccata se `true`. L'annuncio è protetto, l'agenzia può modificarlo - o sbloccarlo - solo dal pannello del portale
RequestID	String	Yes	ID della richiesta, univoco
ListingUuid	String	No	UUID dell'annuncio
AgencyUuid	String	No	UUID dell'agenzia
RealtorId	Integer	No	ID dell'agente (sul portale)
RealtorUuid	String	No	UUID dell'agente processato
RealtorExternalId	String	No	ID dell'agente nel gestionale

L'esito di ogni richiesta è composta da uno STATUS HTTP standard e da un ErrorCode che approfondisce l'origine dell'errore:

ErrorCode	Nome	Descrizione
0	SUCCESS	Operazione terminata con successo
330	OFFLINE_RE	Agenzia Offline
400	BAD_REQUEST	Feed non validato oppure dati incompatibili o errati.
401	WRONG_STATUS	Annuncio rifiutato per un problema di status (solitamente relativo all'agenzia)
403	LOCKED	Risorsa protetta
404	NOT_FOUND	Risorsa non trovata
409	ID_MISMATCH	Errore nel formato degli ID
422	AGENCY_PHONE_NUMBER_NOT_UPDATABLE	solo agenzie tentativo di aggiornare un numero di telefono associato a un servizio esterno
440	MISSING_FIELD	Campo obbligatorio assente
445	MISSING_REALTOR	Solo agenti Impossibile trovare l'agente
450	MISSING_RE	Impossibile trovare l'agenzia
455	UNRESOLVED_TYPOLOGY	Solo annuncio Tipologia immobiliare non trovata o non associabile
460	MISSING_GEO	Informazioni geografiche non coerenti
470	BAD_JAXB_REQUEST	Validazione XSD fallita
480	UNKNOWN_CMD	Attributo `@operation` sconosciuto
500	GENERIC_ERROR	Errore generico

Modalità Batch

Feed XML monolitico è la soluzione storica per sincronizzare gli annunci da fonti esterne.Se dovete lavorare su un vecchio flusso batch, o non avete modo di realizzare un servizio real-time, vi sarà fornito un account FTP dal nostro team Support nel quale caricare quotidianamente tutti gli annunci pubblicabili dalle vostre agenzie.

L'operazione di rimozione di un annuncio è implicita. In altre parole: gli annunci non protetti e non presenti nel flusso verranno rimossi alla fine dell'importazione giornaliera.

Caratteristiche richieste per il feed:

il feed deve essere conforme alla sintassi xml e valido secondo lo schema xsd come nel link sotto riportato;
il feed deve rispettare la codifica UTF-8;
il feed deve essere compresso in formato zip o gzip (preferito);
deve essere caricato un solo file xml, chiamato feed.xml.gz o feed.xml.zip;

Carico utile

Il carico utile è identico sia in real-time che in modalità batch, condividono infatti lo stesso schema XSD.

Affronteremo alcune discriminanti critiche senza scendere nei dettagli. Per la documentazione puntuale dei nodi rimandiamo al documento completo, ricordando che anche le annotazioni presenti nel XSD possono aiutarvi nello sviluppo.

Gli esempi che seguono sono applicati a un oggetto property oppure sono frammenti XML dello stesso.

Identificativi

Per sincronizzare una risorsa è necessario identificarla univocamente. Per farlo è possibile adottare un approccio tra quelli disponibili:

Entità	XPath	Descrizione	Obbligatorio
Listing	//property/unique-id	Usato per identificare l'annuncio in accoppiata con lo username (email) dell'agenzia	Yes
Company	//property/agent/email	Username dell'agenzia	Yes
Realtor	//property/agent/realtors/realtor/id	Identificativo dell'agente sul portale	No

Per esempio:

<property operation="write">
  <unique-id><![CDATA[123456]]></unique-id>
  ...
  <agent>
    <office-name><![CDATA[Agenzia Test]]></office-name>
    <email>agency-email@example.com</email>
  </agent>
  ...
</property>

Data di ultima modifica

Il campo last-updated è fondamentale per valutare l'effettiva necessità di aggiornare un annuncio. Se la data sul nostro DB è maggiore o uguale a quella presente nel feed non aggiorneremo l'annuncio. Questo approccio ci consente di contenere il carico operativo dei processi di importazione e non è negoziabile.

Tutte le date devono essere inviate nel formato ISO-DATE-TIME, ecco un esempio:

<property operation="write">
  ...
  <date-updated>2019-10-10T12:00:12</date-updated>
  ...
</property>

Tipologia immobiliare

Ogni immobile deve avere una tipologia immobiliare associata. La tipologia viene trasmessa in forma di identificativo numerico come nell'esempio:

<building IDType="14" />

Potete accedere alla lista dettagliata delle tipologie supportate. Ricordate anche che esistono regole per cui alcune tipologie non sono sempre applicabili (es. una stanza in vendita).

Prezzo e tipo di contratto

Ogni annuncio deve aver un contratto R (Affitto) o S (Vendita), l'elemento //trasanction/@type è obbligatorio.

In //transaction/price, potete definire il prezzo di vendita, che può essere nascosto associando il valore true all'attributo //transaction/price/@reserved.

<transactions>
    <transaction type="S">
      <price currency="EUR" reserved="false">140000</price>
    </transaction>
</transactions>

Si noti anche l'attributo //transaction/price/@currency. Attualmente supportiamo solo la valuta Euro (EUR).

Geografia

Ogni immobile deve essere localizzato geograficamente. Il sistema migliore è definirne le coordinate geografiche (latitudine e longitudine). Accoppiandole al codice della nazione e all'indirizzo.

In assenza di coordinate geografiche diventa fondamentale definire la città. L'attributo //location/city/@code contiene il codice ISTAT del comune.

  <location>
    <country-code>IT</country-code>
    <administrative-area>Marche</administrative-area>
    <sub-administrative-area>Ancona</sub-administrative-area>
    <city code="042021">Jesi</city>
    <locality map="exact">
      <postal-code>60035</postal-code>
      <latitude>43.5176</latitude>
      <longitude>13.2506</longitude>
      <thoroughfare display="yes"><![CDATA[Via Marconi, 292]]></thoroughfare>
    </locality>
  </location>

Grazie all'attributo //location/locality/@map è anche possibile offuscare la posizione geografica esatta.

Media

Ogni annuncio può essere corredato di un set di immagini, planimetrie, documenti e virtual tour. Ogni media deve essere accessibile attraverso una URL esterna, è possibile definire l'ordine in cui mostrare i media con l'attributo @position come in questo esempio:

  <pictures>
    <picture position="1" url="http://s3-eu-central-1.amazonaws.com/1053424_thumb_109-2012-454_1053424.jpg"/>
    <picture position="2" url="http://s3-eu-central-1.amazonaws.com/1053425_thumb_109-2012-454_1053425.jpg"/>
    <picture position="3" url="http://s3-eu-central-1.amazonaws.com/1053426_thumb_109-2012-454_1053426.jpg"/>
    <picture position="4" url="http://s3-eu-central-1.amazonaws.com/1053427_thumb_109-2012-454_1053427.jpg"/>
    <picture position="5" url="http://s3-eu-central-1.amazonaws.com/1053428_thumb_109-2012-454_1053428.jpg"/>
  </pictures>

Le immagini devono avere una dimensione massima di 5 242 880 byte (5,2 Mb circa).

Le immagini e gli altri media sono delegati a un sistema di download asincrono. Anche con risposta positiva a una chiamata del sistema Real-time l'aggiornamento dei media è soggetto a un'attesa di alcuni minuti.

E' bene che i server che ospitano le immagini accettino chiamate HEAD, questo sistema viene usato per verificare che sia davvero necessario aggiornare una risorsa.

Premium e Extra-Visibilità

E' possibile controllare da flusso le extra-visibilità di un annuncio. Per farlo è necessario adottare il nodo //publish come segue:

<publish>
    <portal id="immobiliare.it" status="true">
      <visibilities>
        <visibility op="active">premium</visibility>
        <visibility op="active">top</visibility>
        <visibility op="remove">showcase</visibility>
      </visibilities>
    </portal>
  </publish>

Nell'esempio si chiede di attivare le visibilità premium e top, se attiva sarà anche revocata la visibilità star.

Richieste di questo genere possono essere ignorate se l'agenzia non ha i permessi per impostare le extra-visibilità oppure se ha esaurito il plafond disponibile.

Chiamate prive del nodo //publish, o con un contenuto parziale, lasciano inalterata la situazione in essere.

Modalità API REST
Modalità Batch
Carico utile