Documentazione per feed di importazione 2.0.0

Nel documento che segue descriviamo la struttura XML utilizzabile per la sincronizzazione degli annunci immobiliari da fonti esterne nei portali di Immobiliare.it S.p.A.

Questo documento è stato strutturato per suddividere le informazioni per argomenti, in modo da renderne più snella e agevole la consultazione.

Icone Importanti

Abbiamo introdotto alcune convenzioni a beneficio di sintesi.

Icona	Significato	Posizione in pagina
	Annuncio	A sinistra
	Asta	A sinistra
	Immobile all'asta	A sinistra
	Obbligatorio	Di fianco all'XPath
	Deprecato	Sul lato sinistro di una nota
	Link diretto alla sezione della pagina	Di fianco al titolo
	Link di approfondimento	Sul lato destro del paragrafo
	Link a sezione della pagina	Sul lato destro del paragrafo
	Torna alla pagina principale	Sul lato destro del paragrafo
	Risorsa scaricabile	Sul lato destro del paragrafo
	Pagina esterna	Sul lato destro del paragrafo

Formato XML

Immobiliare.it consente di importare automaticamente gli annunci delle agenzie, previo accordo commerciale, da gestionali o franchising.

Le modalità di invio delle informazioni sono approfondite in una pagina dedicata.

Nelle sezioni che seguono sono descritte le informazioni con cui potete integrare gli annunci, consigliamo di validare il feed risultante con lo schema XSD a vostra disposizione per lo sviluppo. La validazione è applicata su ogni annunci in ingresso, se non supera questo passaggio l'annuncio è scartato. E' quindi consigliabile validare il flusso dopo ogni modifica.

Ogni informazione, completa di valori compatibili, è contenuta nello schema XSD. La presente documentazione può quindi essere considerata una traduzione leggibile dello schema stesso.

Formati standard

Ogni volta che è stato necessario usare una specifica unità di grandezza abbiamo utilizzato standard universali e noti, possibilmente applicando specifiche ISO o le direttive W3C sul formato XML.

In quest'ottica, per identificare con sicurezza la posizione che ciascun elemento deve occupare all'interno del feed usiamo la notazione nota come XPath:

/feed/properties/property/building/@IDType

In generale

I nomi dei nodi e degli attributi XML devono essere scritti così come sono riportati, rispettando lettere maiuscole e minuscole. Nel tempo abbiamo cercato di raggruppare le informazioni in gruppi logici, per esempio gli attributi geografici sono organizzati all'interno di un contenitore //location.

Intestazione XML

Ogni chiamata o feed XML deve avere indicata la versione dello standard stesso (1.0), e dalla codifica del documento UTF-8.

<?xml version="1.0" encoding="UTF-8"?>

Numeri

Numeri interi o decimali sono espressi senza separatori delle migliaia. Secondo lo standard XML va usato il punto . come separatore decimale.Il segno è necessario solo per i numeri negativi

-41.8968348

Flag

Parecchi nodi e attributi possono assumere soltanto i valori Vero o Falso (campi di tipo boolean). Per essi i valori ammessi sono

true
false

è importante che si presentino tutti in minuscolo, non è necessario usare CDATA ed è sconsigliato inserire spazi o ritorni a capo prima o dopo questi valori, idealmente:

<price currency="EUR" reserved="false">1000000</price>
...
<workshop>false</workshop>

Il trattamento dei campi boolean è conforme allo standard XML definite da W3C.

w3c

Data e ora

Data e ora (campi di tipo dateTime) sono espresse secondo il formato ISO 8601:

2013-01-30T12:01:07

In altre parole: specificare l'anno in 4 cifre, trattino, mese a 2 cifre, trattino, giorno a 2 cifre, la T maiuscola, 2 cifre per l'ora (00-23), due punti, 2 cifre per i minuti (00-59), due punti, 2 cifre per i secondi (00-59).

Si noti il carattere T come separatore tra data e ora. Non è necessario specificare la Timezone (il fuso orario). Come riferimento rapido vi rimandiamo alla pagina Wikipedia.

Valuta

Sebbene Immobiliare.it preveda soltanto l'Euro come divisa ammessa, è sempre richiesto specificare la valuta secondo lo standard ISO 4217, consistente in tre caratteri maiuscoli.

EUR

Campi specifici

Entrando nei dettagli specifici di un immobile troverete informazioni peculiari di alcune categorie immobiliari. In altre parole troverete dei campi che hanno senso solo per determinati tipi di immobile e non per altri. Questi nodi sono contrassegnati dalle seguenti icone:

Categoria	Prevista	Non prevista
Residenziali
Palazzi / stabili
Garage / posti auto
Terreni
Uffici / coworking
Magazzini
Capannoni
negozi / locali commerciali
Cantieri / nuove costruzioni

Flussi batch (obsoleti)

Per compatibilità con il passato sono supportati flussi batch.

Inserimento o aggiornamento Immobile

Di seguito sono riportate le specifiche dei nodi xml da inviare per descrivere le caratteristiche di un annuncio immobiliare. Laddove non espressamente indicato l'assenza di un elemento o di un attributo in un feed viene interpretato con la volontà di rimuovere la relativa informazione.

//property

Nodo contenitore dell'immobile da pubblicare o aggiornare.

Attributo	Descrizione	Stato
@operation	tipo di operazione richiesta
@ID	id annuncio su immobiliare.it	Opzionale

possibili valori per @operation:

write
archive

Il valore write aggiorna le informazioni dell'immobile. Se l'immobile non viene trovato verrà creato un nuovo annuncio. Il valore archive aggiorna le informazioni dell'immobile e lo archivia.

Per le chiamate REST in Real Time questo nodo ha funzione di radice, quindi ogni chiamta REST può contenere uno e un solo annuncio:

<property ID="12345" operation="write">
  ...
</property>

In modalità Batch è necessario inviare l'intero set di annunci, avremo quindi un numero variabile di nodi property strutturati in questo modo:

<feed>
    <properties>
        <property ID="12345" operation="write">
            ....      
        </property>
        <property ID="54321" operation="write">
            ....      
        </property>
        ...
    </properties>
</feed>

//property/unique-id

id dell'immobile nel gestionale, viene utilizzato per identificare l'annuncio. In accoppiata con l'email dell'agenzia, sotto la responsabilità del mittente, deve risultare univoco.

//property/published-on

data di prima pubblicazione dell'immobile.

//property/date-updated

data di ultimo aggiornamento dell'immobile, deve essere sempre aggiornata dopo ogni modifica all'annuncio.

//property/agent

agenzia che richiede la pubblicazione dell'annuncio

Attributo	Descrizione	Stato
@id	id dell'agenzia su immobiliare.it	Opzionale

Di seguito un 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>

//property/agent/name

nome dell'agenzia che pubblica l'annuncio

//property/agent/email

Username dell'agenzia che pubblica l'annuncio (univoca per agenzia), combinata con //property/unique-id identifica univocamente l'annuncio.

//property/location

Nodo contenitore dei dati geografici dell'immobile

//property/pictures

Contenitore delle immagini dell'immobile.

//property/videos

Contenitore dei video dell'immobile.

//property/estates

Contenitore delle unità abitative in vendita.

//property/reference-code

Codice di riferimento dell'agenzia (max 255 caratteri), è un campo di testo libero a discrezione del cliente. Non è necessario garantirne l'univocità

//property/publish

Stato della visibilità, all'interno del portale Immobiliare.

Per garantire la visibilità su Immobiliare, inviare il nodo Publish. Se lo status è uguale a true, l'annuncio è pubblicato e quindi visibile sul portale Immobiliare. Se lo status è uguale a false, rimane visibile sul gestionale, ma non sul portale Immobiliare.

<publish>
    <portal id="immobiliare.it" status="true" />
</publish>

//property/publish/portal

contenitore delle informazioni relative alle extra-visibilità (l'agenzia deve essere abilitata all'invio). In assenza del noto publish la visibilità dell'annuncio resta inalterata.

Attributo	Descrizione	Stato
@id	l'id del portale per cui si voglione impostare le extra-visibilità
@status	specifica se l'annuncio deve essre pubblicato (true) o deve soltanto essere disponibile sul gestionale (false)

possibili valori per @id:

immobiliare.it

Esempio xml:

<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>

//property/publish/portal/visibilities

contenitore delle extra-visibilità specifiche di un portale (vengono scalate, se diponibili, dal plafond dell'agenzia).

//property/publish/portal/visibilities/visibility

specifica una singola extra-visibilità da aggiungere o rimuovere

Attributo	Descrizione	Stato
@op	specifica il tipo di operazione richiesta per una specifica extra-visibilità (default: active)

possibili valori per @op:

active
remove

possibili valori per il nodo:

basic
premium
top
showcase
star

//property/transactions

contenitore delle informazioni relative a prezzo e tipo di contratto (vendita o affitto)

Di seguito un esempio:

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

//property/transactions/transaction

Attributo	Descrizione	Stato
@type	specifica il contratto (affitto o vendita) con cui viene proposto l'immobile
@on-redeem	affitto con riscatto
@ownership	modello di contratto
@ownership-quota	quota proprietà

possibili valori per @type:

S (sale - vendita)
R (rent - affitto)

possibili valori per @ownership:

intera proprietà
nuda proprietà
parziale proprietà
usufrutto
multiproprietà
diritto di superficie

@ownership-quota rappresenta la quota di proprietà ed è un campo di testo libero.

//property/transactions/transaction/price

prezzo dell'immobile

Attributo	Descrizione	Stato
@currency	valuta (passare 'EUR')
@reserved	specifica se il prezzo è riservato, se `true` il prezzo sarà nascosto

//property/building

contenitore delle informazioni relative alla tipologia dell'immobile

Attributo	Descrizione	Stato
@IDType	id della tipologia dell'immobile

L'elenco dei possibili valori, e la spiegazione di ciascuno, è disponibile qui

<building IDType="14" />

//property/building/status

stato dell'immobile.

Possibili valori:

in costruzione
nuovo
abitabile
ottimo
buono
ristrutturato
da ristrutturare
discreto
nd

//property/building/class

classe dell'immobile.

Possibili valori:

di lusso
signorile
medio
economico

//property/features

Questo contenitore è destinato alle caratteristiche descrittive principali dell'immobile.

//property/extra-features

Contenitore destinato a caratteristiche più specifiche dell'immobile.

//property/extended

Estensione delle caratteristiche dell'immobile.

//property/documents

Contenitore dei documenti dell'immobile.

//property/blueprints

Contenitore delle planimetrie dell'immobile.

//property/raw-360s

Nodo contenitori delle immagini sferiche dell'annuncio.

//property/registrar-data/section

dati catastali: sezione

//property/registrar-data/sheet

dati catastali: foglio

//property/registrar-data/parcel

dati catastali: particella

//property/registrar-data/sub-parcel

dati catastali: subparticella

//property/registrar-data/sub

dati catastali: subalterno

//property/registrar-data/sub-2nd

dati catastali: subalterno 2

//property/registrar-data/attached

dati catastali: graffato

//property/registrar-data/revenue

dati catastali: Rendita catastale. Valore decimale espresso in Euro.

Inserimento o aggiornamento Asta

Di seguito riportiamo le specifiche dei vari nodi xml da inviare per impostare le varie caratteristiche di un'asta. Laddove non espressamente indicato l'assenza di un elemento o di un attributo in un feed viene interpretato con la volontà di rimuovere la relativa informazione.

//auction

Nodo contenitore degli elementi di tipo asta da pubblicare o aggiornare

Attributo	Descrizione	Stato
@operation	tipo di operazione richiesta
@ID	id annuncio su immobiliare.it
@source-type	Motivazione dell'asta
@type	Tipo di procedura

possibili valori per @operation:

write
archive

Il valore write aggiorna le informazioni dell'asta. Se l'asta non viene trovata verrà creato un nuovo annuncio. Il valore archive aggiorna le informazioni dell'asta e la archivia.

possibili valori per @source-type:

giudiziaria
altra vendita

possibili valori per @type:

accordo di ristrutturazione
amministrazione giudiziaria mp
amministrazione straordinaria
appalto
causa civile
composizione crisi da sovraindebitamento
concordato fallimentare
concordato preventivo
divisione giudiziale
eredità giacente
esecuzione immobiliare
esecuzione penale
fallimento
liquidazione coatta
liquidazione volontaria-giudiziale
misura di prevenzione
procedura esattoriale
procedura concorsuale
scioglimento per atto d'autorità
sequestro preventivo
usucapione
vendita immobiliare
volontaria giurisdizione
giudiziaria
altra vendita

Per le chiamate REST in Real Time questo nodo ha funzione di radice, quindi ogni chiamata REST può contenere una e una sola asta:

<auction ID="12345" operation="write">
  ...
</auction>

In modalità Batch è necessario inviare l'intero set di aste, avremo quindi un numero variabile di nodi auction strutturati in questo modo:

<feed>
    <auctions>
        <auction ID="12345" operation="write">
            ....      
        </auction>
        <auction ID="54321" operation="write">
            ....      
        </auction>
        ...
    </auctions>
</feed>

//auction/unique-id

Identificativo dell'asta nel gestionale, viene utilizzato per identificare l'asta. In accoppiata con l'email dell'agenzia, sotto la responsabilità del mittente, deve risultare univoco.

//auction/reference-code

Codice di riferimento dell'agenzia (max 255 caratteri), è un campo di testo libero a discrezione del cliente. Non è necessario garantirne l'univocità.

//auction/published-on

data di prima pubblicazione dell'asta

//auction/date-updated

data di ultimo aggiornamento dell'asta, deve essere sempre aggiornata dopo ogni modifica all'annuncio.

//auction/agent

agenzia che richiede la pubblicazione dell'annuncio

Attributo	Descrizione	Stato
@id	id dell'agenzia su immobiliare.it

Di seguito un esempio:

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

//auction/descriptions/description

decrizione dell'asta

Attributo	Descrizione	Stato
@language	lingua della descrizione

//auction/descriptions/description/title

titolo dell'annuncio (max 255 caratteri)

//auction/descriptions/description/content

testo della descrizione

//auction/starting-price

Prezzo di partenza dell'asta

Attributo	Descrizione	Stato
@currency	valuta (passare 'EUR')
@reserved	specifica se il prezzo è riservato, se `true` il prezzo sarà nascosto

//auction/minimum-bid

Rialzo minimo

Attributo	Descrizione	Stato
@currency	valuta (passare 'EUR')
@reserved	specifica se il prezzo è riservato, se `true` il prezzo sarà nascosto

//auction/minimum-bid-challenge

Rialzo minimo gara

Attributo	Descrizione	Stato
@currency	valuta (passare 'EUR')
@reserved	specifica se il prezzo è riservato, se `true` il prezzo sarà nascosto

//auction/success-price

Offerta minima

Attributo	Descrizione	Stato
@currency	valuta (passare 'EUR')
@reserved	specifica se il prezzo è riservato, se `true` il prezzo sarà nascosto

//auction/court

Tribunale di riferimento per l'asta

Attributo	Descrizione	Stato
@name	nome del tribunale
@type	tipo del tribunale. Possibili valori sono 'court' e 'other'

//auction/reference

Estremi del procedimento giudiziario

Attributo	Descrizione	Stato
@year	anno del procedimento
@number	numero del procedimento

//auction/actors

Contenitore delle informazioni relativi agli attori del procedimento giudiziario

//auction/actors/actor

Attore dell'asta giudiziaria

Attributo	Descrizione	Stato
@type	Tipo di attore
@ID	id dell'attore

possibili valori per @type:

giudice
delegato
professionista delegato
delegato alla vendita
custode
creditore
richiedente
referente
curatore
curatore fallimentare
geometra
controparte istituzionale
firmatario
ctu
avvocato
commissario
commissario straordinario
commissario giudiziale
commissario liquidatore
liquidatore
liquidatore giudiziale
soggetto specializzato alla vendita
persona autorizzata alla vendita
istituto vendite giudiziarie
commissionario
amministratore di sostegno
tutore
gestore per la liquidazione
legale della parte
pignorante con procedure de formalizzate
ufficiale giudiziario
altro soggetto

//auction/actors/actor/name

Nome dell'attore

//auction/actors/actor/lastname

Cognome dell'attore

//auction/actors/actor/tax-code

Codice fiscale dell'attore

//auction/actors/actor/phone

Telefono fisso dell'attore

//auction/actors/actor/mobile

Telefono cellulare dell'attore

//auction/actors/actor/email

Email dell'attore

//auction/actors/actor/fax

Fax dell'attore

//auction/actors/actor/selling-operations

Indica se l'attore è abilitato al'operazione di vendita (flag true o false)

//auction/actors/actor/estate-journey

Indica se l'attore è abilitato alla visita del bene (flag true o false)

//auction/notes

Note riguardanti l'asta giudiziaria

//auction/lot-number

Numero del lotto d'asta

//auction/selling-place

Contenitore della geografia, per l'indirizzo del luogo di vendita.

//auction/depot-conditions

Informazioni sul deposito cauzionale

//auction/depot-out-of-date

Termine presentazione

//auction/depot-bills

Deposito conto spese, in Euro (EUR). Può contenere valori decimali.

//auction/real-value

Valore dell'immobile da perizia, in Euro (EUR). Può contenere valori decimali.

//auction/ransom

Valore della cauzione, in Euro (EUR). Può contenere valori decimali.

//auction/ransom-bill

Spese cauzione, in Euro (EUR). Può contenere valori decimali.

//auction/practice

description

//auction/show-place

Luogo di presentazione dell'asta

//auction/reference-info

Informazioni sul referente dell'asta

//auction/events

Nodo contenitore degli eventi legati all'asta. E' il calendario con le date in cui sono previste le aste.

//auction/events/event

Singolo evento legato all'asta

Attributo	Descrizione	Stato
@type	Tipo di evento
@status	Stato dell'evento
@mode	modalità di svolgimento dell'evento

possibili valori per @type:

a trattativa privata
asincrona
asta privata
atto pubblico notarile
con incanto
gara informale
invito a manifestare interesse
invito a offrire
licitazione privata
mezzo commissionario
tramite commissionario
offerta segreta
senza incanto
senza incanto - seguito aumento di un quinto
sollecitazione di locazione
udienza di assegnazione
vendita competitiva
competitiva
vendita da definire
vendita online
vendita competitiva

possibili valori per @status:

partecipabile
non più partecipabile
asta deserta
sospesa

possibili valori per @mode:

presso il venditore
sincrona telematica
sincrona mista
asincrona telematica

//auction/events/event/date

Data di svolgimento dell'evento

//auction/events/event/starting-price

Prezzo base

Attributo	Descrizione	Stato
@currency	valuta (passare 'EUR')
@reserved	specifica se il prezzo è riservato, se `true` il prezzo sarà nascosto

//auction/documents

Contenitore dei documenti dell'asta.

//auction/raw-360s

Nodo contenitori delle immagini sferiche dell'annuncio.

//auction/publish/portal

contenitore delle informazioni relative alle extra-visibilità (l'agenzia deve essere abilitata all'invio). In assenza del nodo publish la visibilità dell'annuncio resta inalterata.

Attributo	Descrizione	Stato
@id	l'id del portale per cui si vogliono impostare le extra-visibilità
@status	specifica se inserire l'annuncio in immobiliare (true) o solo in Getrix (false)

possibili valori per @id:

immobiliare.it

Esempio xml:

<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>

//auction/publish/portal/visibilities

contenitore delle extra-visibilità specifiche di un portale

//auction/publish/portal/visibilities/visibility

specifica una singola extra-visibilità che si vuole aggiungere o rimuovere

Attributo	Descrizione	Stato
@op	specifica il tipo di operazione richiesta per una specifica extra-visibilità (default: active)

possibili valori per @op:

active
remove

possibili valori per il nodo:

basic
premium
top
showcase
star

//auction/estates

Nodo contenitore degli immobili dell'asta

//auction/register

Informazioni di registro dell'asta (lookup). Possibili valori:

esecuzioni civili immobiliari
esecuzioni civili mobiliari
volontaria giurisdizione
contenzioso civile
liquidazione volontaria - giudiziale
esecuzione coattiva per inadempimento compratore
cose depositate
pegno non possessorio
esecuzioni esattoriali immobiliari
esecuzioni esattoriali mobiliari

//auction/legal-category

Categoria legale degli immobili. Possibili valori:

immobile residenziale
immobile commerciale
immobile industriale
impianto sportivo
altra categoria

//auction/legal-fee

Tipo di contribuzione. Possibili valori:

free
scheduled-in-debt
acquitted

//auction/links

Contenitore di link relativi all'asta

//auction/links/link

Descrizione del link

Attributo	Descrizione	Stato
@url	url relativa al link da mostrare