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.