Realgest API: nuovi dettagli facoltativi

Dettagli facoltativi dell’annuncio — 11 ottobre 2026

Nuovo oggetto dettagli_annuncio in fondo a RG_AddAnnuncio e RG_UpdateAnnuncio. I parametri precedenti restano nello stesso ordine. Sono campi indipendenti, senza deduzioni né valorizzazione massiva. Omissione o nil (oggetto o campo): in inserimento NULL, in aggiornamento conserva. Zero e false sono valori espliciti.

Per cancellare un dato usare azzera_campi, array dei nomi dei nuovi campi da riportare a NULL. Non permette di cancellare campi storici. Non inviare contemporaneamente un valore e il suo nome in azzera_campi. Valori errati, nomi sconosciuti o duplicati: ErrorCode201 senza salvataggio. Stringa vuota non è un comando SOAP di cancellazione. In GUI vuoto/Non noto salva NULL.

Restituiti nell’oggetto dettagli_annuncio da RG_GetAnnuncio, RG_GetAnnunci, vetrina e ricerca. Il WSDL è aggiornato per lettura e scrittura. Scala identifica la scala, non il numero_scale. Numero livelli riguarda l’unità, non i piani dell’edificio. Numero box conta box distinti: un box doppio non implica due box. Il numero terrazzi non modifica terrazzo o superfici balconi/terrazzi. Le presenze nuove non modificano i flag storici.

<dettagli_annuncio>
  <numero_camere_letto>2</numero_camere_letto>
  <numero_terrazzi>0</numero_terrazzi>
  <scala>B</scala>
</dettagli_annuncio>
<!-- Aggiornamento: cancella soltanto scala, conserva gli altri -->
<dettagli_annuncio><azzera_campi><item>scala</item></azzera_campi></dettagli_annuncio>

Manuale pubblico con esempi NuSOAP. Piani fuori/entro fabbricato descrivono l’edificio; piano descrive l’unità. Superficie, mqterreno, giardino e numero_balconi mantengono il contratto precedente.

Tipologie Realgest: estensione del 23 ottobre 2026

Le nuove voci sono disponibili per tutte le agenzie nel gestionale e nei metodi RG_GetTipologieImmobili e RG_GetTipologieImmobiliNetwork. I metodi RG_AddAnnuncio e RG_UpdateAnnuncio le accettano nei parametri esistenti id_tipologia e id_classe; le letture e i filtri degli annunci restituiscono e utilizzano gli stessi ID.

Usare gli ID Realgest della prima colonna. I codici Immobiliare.it V2 sono riferimenti esterni separati. Non inviare il codice del portale come ID Realgest. Nessuna rinomina o riclassificazione degli annunci esistenti: Villa, ID 29, conserva il riferimento alla Villa unifamiliare V2 23; Altro e tutti gli altri ID storici restano disponibili.

Equivalenze mantenute: Casa Indipendente, ID 24, copre Terratetto unifamiliare (V2 21); Stanza/Camera, ID 64, copre Stanza in appartamento (V2 194). Per Studio generico usare Ufficio, ID 39; Studio medico, ID 42, resta specifico quando dichiarato dalla sorgente. La nuova voce Posto barca è distinta dalla voce legacy 6, che rimane invariata.

La struttura SOAP rimane invariata: il catalogo è dinamico e id_tipologia resta un xsd:long, senza una nuova enumerazione XSD chiusa. Per i lookup locali aggiornare anche realgest_anagrafiche.zip, che conserva le tre colonne id_tipologia,id_classe_immobile,nome.

Classi Realgest: 4 = Immobile residenziale; 5 = Immobile commerciale/industriale; 8 = Terreno; 9 = Progetto. Le stanze in ufficio/studio e il coworking appartengono alla classe 5; le stanze in villa/casa indipendente alla classe 4. Le disponibilità V2 in tabella riguardano quella destinazione, non introducono nuovi blocchi nelle API Realgest.

Significato: Villa plurifamiliare comprende le ville con più di due unità familiari; il numero di unità non trasforma un palazzo in villa. Appartamento in villa identifica l’unità, non l’intera villa. La nuova tipologia non edificabile è distinta da Terreno agricolo; la precedente Area agricola o non edificabile, ID 63, rimane invariata. Non determinare la tipologia dal titolo. Una sorgente aggregata o ambigua richiede una scelta verificata, senza inventare dettagli.

Stanza/Camera, ID 64, resta utilizzabile; quando la sorgente identifica una delle nuove stanze specifiche usare il relativo ID della tabella. Il nome della classe restituito dal lookup non è il suo ID numerico: per Add/Update usare id_classe indicato qui.

$params = array('admin_api_key' => $key, 'id' => $id,
  'id_classe' => 4, 'id_tipologia' => 65);
$result = $client->call('WsAction.RG_UpdateAnnuncio', $params);
// Verificare Success ed ErrorCode e rileggere RG_GetAnnuncio.

Riferimento: catalogo ufficiale Immobiliare.it V2, XML e flag verificati il 23 ottobre 2026. Le voci con vendita e affitto ordinari V2 entrambi No sono riservate alle aste in quella destinazione; Progetto (V2 276) ha una classe dedicata e non rappresenta una singola unita. availableForProject indica invece la disponibilita di una tipologia di unita dentro un progetto: non equivale allo stato nuova costruzione. Le API Realgest non aggiungono blocchi editoriali basati su queste disponibilita.

Civico e CAP dell’annuncio — 25 ottobre 2026

civico e cap appartengono al singolo annuncio e sono salvati separatamente in imm_immobili. Sono campi facoltativi, distinti dall’indirizzo dell’agenzia e dal nome della via.

In RG_AddAnnuncio e RG_UpdateAnnuncio inviarli come parametri diretti, accanto a indirizzo: non sono figli di dettagli_annuncio. Ometterli non impedisce la creazione. In modifica, omissione o nil conserva il valore; una stringa vuota esplicita cancella il testo. I due campi sono indipendenti: aggiornare il civico senza CAP non cambia il CAP già salvato.

Sono restituiti come Annuncio.civico e Annuncio.cap da RG_GetAnnuncio, e sui singoli elementi degli elenchi, della vetrina e della ricerca testuale. Quando il valore DB è NULL il contratto SOAP storico può omettere il campo o restituirlo vuoto: il client deve gestire entrambe le rappresentazioni del dato sconosciuto. mostra_ubicazione regola la pubblicazione della posizione e non cancella i dati salvati nell’annuncio.

// Inserimento: civico e CAP sono facoltativi.
$params = array('admin_api_key' => $key, 'id_agenzia' => $agency,
  'riferimento_annuncio' => 'Appartamento in centro',
  'indirizzo' => 'Via Esempio', 'civico' => '12/A', 'cap' => '00100');
$result = $client->call('WsAction.RG_AddAnnuncio', $params);
// Aggiornamento del solo CAP: civico e via restano conservati.
$result = $client->call('WsAction.RG_UpdateAnnuncio', array(
  'admin_api_key' => $key, 'id' => $id, 'cap' => '00101'));
// Verificare Success/ErrorCode e rileggere RG_GetAnnuncio.

Sei dettagli facoltativi — estensione del 23 ottobre 2026

I campi seguenti sono figli di dettagli_annuncio, già previsto in RG_AddAnnuncio e RG_UpdateAnnuncio. Non sono nuovi parametri al primo livello: l'ordine e le firme precedenti restano invariati. Sono restituiti nello stesso oggetto dalle letture del singolo annuncio, dagli elenchi, dalla vetrina e dalla ricerca che già espongono i dettagli.

Omissione e NULL: oggetto o campo omesso/nil non scrive quel dato; in creazione resta NULL, in aggiornamento conserva il valore. Per riportare esplicitamente un campo a NULL usare azzera_campi. Non inviare contemporaneamente un valore e il suo nome nell'elenco di cancellazione. Zero e false sono valori effettivi e vengono conservati. Una stringa vuota non rappresenta NULL nelle API.

Importi: nel SOAP usare il punto decimale, senza valuta o separatori delle migliaia, ad esempio 123.45. Valori negativi, frazioni con più di due cifre, enum diversi e conteggi fuori limite vengono rifiutati senza scritture parziali. Le risposte mantengono la precisione dei centesimi; trattare gli importi come decimali, evitando arrotondamenti binari nel client.

I campi storici costi_condominiali, ascensore, numero_ascensori, piani_fuori_fabbricato, piani_entro_fabbricato e barriere_architettoniche non sono sostituiti o convertiti. Nessuna deduzione dal titolo o dalla descrizione, nessun aggiornamento massivo dei record esistenti. video_360 resta il parametro preesistente per il tour esterno.

Esempio di aggiornamento

<dettagli_annuncio>
  <rendita_catastale>850.25</rendita_catastale>
  <spese_condominiali_importo>0.00</spese_condominiali_importo>
  <spese_condominiali_periodicita>mensile</spese_condominiali_periodicita>
  <numero_piani_totali>4</numero_piani_totali>
  <numero_ascensori_fabbricato>0</numero_ascensori_fabbricato>
  <accessibile_disabili>false</accessibile_disabili>
</dettagli_annuncio>
<!-- Per rendere sconosciuta la sola rendita, in una chiamata successiva: -->
<dettagli_annuncio>
  <azzera_campi><item>rendita_catastale</item></azzera_campi>
</dettagli_annuncio>

$params = array('admin_api_key' => $key, 'id' => $id,
  'dettagli_annuncio' => array(
    'rendita_catastale' => '850.25',
    'spese_condominiali_importo' => '0.00',
    'spese_condominiali_periodicita' => 'mensile',
    'numero_piani_totali' => 4,
    'numero_ascensori_fabbricato' => 0,
    'accessibile_disabili' => false));
$result = $client->call('WsAction.RG_UpdateAnnuncio', $params);
// Verificare Success ed ErrorCode: HTTP 200 da solo non prova il salvataggio.
// In creazione: RG_AddAnnuncio con id_agenzia e riferimento_annuncio.

Classe catastale e certificazione energetica — 28 ottobre 2026

Due campi facoltativi del blocco dettagli_annuncio in RG_AddAnnuncio e RG_UpdateAnnuncio, restituiti anche da RG_GetAnnuncio e dalle letture di elenchi, vetrina e ricerca. Le firme e le posizioni dei parametri precedenti sono conservate. Aggiornare la copia locale del WSDL per utilizzare i nuovi figli.

Facoltativi: se non sono inviati, non producono errori. In aggiornamento, omissione o xsi:nil="true" conserva il dato salvato. In creazione la classe catastale resta NULL; il flag mantiene il default storico false, che non costituisce una nuova verifica dell’immobile.

Cancellazione: per rendere sconosciuta la classe catastale usare azzera_campi con classe_catastale. Per togliere lo stato certificato inviare certificato_energetico=false. Il flag storico non ammette NULL nel database: non inserirlo in azzera_campi. Questa richiesta e valori non validi sono rifiutati con Success=false e ErrorCode=201, senza scritture parziali. Gli altri campi non sono modificati automaticamente.

<dettagli_annuncio>
  <classe_catastale>3</classe_catastale>
  <certificato_energetico>true</certificato_energetico>
</dettagli_annuncio>
<!-- In una chiamata successiva: classe sconosciuta, certificazione in attesa. -->
<dettagli_annuncio>
  <certificato_energetico>false</certificato_energetico>
  <azzera_campi><item>classe_catastale</item></azzera_campi>
</dettagli_annuncio>

$result = $client->call('WsAction.RG_UpdateAnnuncio', array(
  'admin_api_key' => $key, 'id' => $id,
  'dettagli_annuncio' => array(
    'classe_catastale' => '3', 'certificato_energetico' => true)));
// Verificare Success/ErrorCode, poi rileggere RG_GetAnnuncio.
// Una vecchia chiamata priva di dettagli_annuncio continua a funzionare.

Immobiliare.it: nel suo tracciato energy-class/@certified è un booleano, mentre @value identifica la classe energetica e @scale distingue APE e IPE. Il PDF è un allegato separato, riservato al CRM del portale; non è richiesto per valorizzare il flag. Specifica energetica e FAQ ufficiali, consultate il 28 ottobre 2026. L’esposizione Realgest non certifica da sola l’invio del campo da parte del connettore.

IPE decimale — 14 novembre 2026

Il parametro diretto ipe di RG_AddAnnuncio e RG_UpdateAnnuncio e il campo Annuncio.ipe di RG_GetAnnuncio e degli elementi di RG_GetAnnunci sono dichiarati xsd:decimal nel WSDL aggiornato. Il campo conserva il significato di indice di prestazione energetica, distinto dalla classe e dal flag di certificazione.

Usare il punto come separatore dei decimali: 125.50. Anche un intero come 125 o zero 0 è valido. Non inviare 125,50, separatori delle migliaia, unità di misura, testo, stringhe vuote o notazione esponenziale. I valori non validi restituiscono Success=false e ErrorCode=201 senza salvare alcun campo dell’annuncio.

• Parametro omesso o xsi:nil="true": in creazione il dato resta NULL; in aggiornamento si conserva quello già salvato. nil non è un comando di cancellazione.
• 0 è un valore esplicito e viene salvato, distinto da NULL.
• Lo storage esistente mantiene due decimali; eventuali cifre ulteriori vengono arrotondate a due decimali dal database. Il massimo assoluto memorizzabile è 99999999.99. Non sono stati ricalcolati o convertiti gli annunci esistenti.
• In lettura il dato è un decimale; se sconosciuto il campo può essere omesso oppure restituito nil; non dipendere dal numero di zeri finali (125.5 e 125.50 rappresentano lo stesso valore).
• Le vecchie chiamate che inviano una stringa numerica con il punto restano accettate. Aggiornare la cache WSDL e rigenerare gli eventuali client tipizzati per acquisire il nuovo tipo; le firme mantengono lo stesso ordine dei parametri.

// Parametro diretto, fuori da dettagli_annuncio.
$params = array('admin_api_key' => $key, 'id' => $id, 'ipe' => 125.50);
$result = $client->call('WsAction.RG_UpdateAnnuncio', $params);
// Verificare Success/ErrorCode, poi rileggere RG_GetAnnuncio.
// Equivalente XML: <ipe xsi:type="xsd:decimal">125.50</ipe>
// Se sconosciuto: omettere ipe oppure usare <ipe xsi:nil="true" />.

Portali TOP e Portali Base — 31 ottobre 2026

TOP: Immobiliare.it, Idealista, Subito.it e Wikicasa conservano le quattro selezioni indipendenti già esistenti. Tutti gli altri portali immobiliari sono riuniti nel gruppo Portali Base, identificato nelle API dal nome invariato portali_secondari; non si scelgono più singolarmente per annuncio.

portali_secondari è un parametro diretto xsd:boolean, in fondo a RG_AddAnnuncio e RG_UpdateAnnuncio, dopo dettagli_annuncio. Restituito da RG_GetAnnuncio, RG_GetAnnunci, RG_GetAnnunciVetrina e RG_GetAnnunciFromString.

Il flag seleziona il gruppo per il singolo annuncio. Restano valide l’abilitazione generale del MultiInvio, le configurazioni dell’agenzia e gli eventuali requisiti dei portali: il flag non attiva contratti o credenziali e non certifica la pubblicazione.

Compatibilità degli elenchi precedenti: RG_SetPortaliAnnuncio e RG_SetEsclusioneAnnuncio continuano a gestire le scelte TOP. Gli eventuali ID di secondari presenti nei vecchi elenchi non cambiano la selezione collettiva; per escludere o includere i secondari usare RG_UpdateAnnuncio(portali_secondari=false/true). Le letture degli elenchi restano disponibili nel formato precedente. RG_SetPortaliAnnuncio mantiene anche il suo comportamento storico sull’abilitazione generale.

In creazione il precedente escludi_tutti_i_portali=true continua a escludere tutti i portali e imposta il gruppo a falso. Inviarlo insieme a portali_secondari=true esplicito è contraddittorio: la richiesta viene rifiutata con ErrorCode=201. Se il flag collettivo è omesso, le chiamate precedenti restano valide.

Migrazione iniziale autorizzata: gruppo attivato su tutti gli annunci esistenti e precedenti esclusioni individuali dei secondari superate. Selezioni TOP, stato attivo degli immobili, configurazioni delle agenzie e interruttore generale conservati.

<!-- parametro diretto di RG_UpdateAnnuncio: include i secondari -->
<portali_secondari>true</portali_secondari>
<!-- esclude i secondari, senza cambiare i quattro TOP -->
<portali_secondari>0</portali_secondari>

Per verificare subito il valore salvato usare RG_GetAnnuncio. La ricerca testuale conserva la sua cache preesistente. WSDL aggiornato.

Incarico in esclusiva

Il campo dettagli_annuncio.mandato_esclusiva dichiara se l’agenzia ha l’incarico in esclusiva per l’immobile. È distinto dal tipo di mediazione, dalla condivisione MLS, dalle date dell’incarico e dalla selezione dei portali: nessuno di questi dati viene cambiato automaticamente.

Scrittura SOAP: figlio facoltativo e nillable di RG_DettagliAnnuncioInput, usato dal parametro dettagli_annuncio già presente in RG_AddAnnuncio e RG_UpdateAnnuncio. Non è un nuovo parametro al primo livello. Le firme precedenti e l’ordine dei parametri rimangono validi.

• Inserimento senza il campo: il valore resta NULL.
• Aggiornamento senza il campo, senza l’oggetto dettagli oppure con xsi:nil="true": conserva il dato salvato.
• false è un valore esplicito e salva “No”; non significa omissione.
• Per tornare a NULL, inviare dettagli_annuncio.azzera_campi = ['mandato_esclusiva']. Non inviare contemporaneamente un valore e la richiesta di cancellazione.
• I valori non validi, come 2, -1 o il testo si, sono rifiutati con Success=false, ErrorCode=201, senza salvataggi parziali.

Lettura: restituito come booleano o NULL in Annuncio.dettagli_annuncio.mandato_esclusiva da RG_GetAnnuncio e nei singoli elementi di RG_GetAnnunci, RG_GetAnnunciVetrina e RG_GetAnnunciFromString. Nessuna valorizzazione massiva degli annunci esistenti e nessuna deduzione da descrizioni o altri flag.

// Incarico esclusivo: integrare questo oggetto nei normali dati di inserimento.
$nuovo['dettagli_annuncio']['mandato_esclusiva'] = true;
$result = $client->call('WsAction.RG_AddAnnuncio', $nuovo);

// Aggiornamento esplicito a NON esclusivo.
$result = $client->call('WsAction.RG_UpdateAnnuncio', array(
  'admin_api_key' => $key, 'id' => $id,
  'dettagli_annuncio' => array('mandato_esclusiva' => false)));

// Rimozione dell’informazione: torna a NULL / Non indicato.
$result = $client->call('WsAction.RG_UpdateAnnuncio', array(
  'admin_api_key' => $key, 'id' => $id,
  'dettagli_annuncio' => array('azzera_campi' => array('mandato_esclusiva'))));

// Rileggere e verificare Success/ErrorCode prima di considerare completato l’aggiornamento.
$result = $client->call('WsAction.RG_GetAnnuncio', array(
  'admin_api_key' => $key, 'id' => $id));

Il riferimento w accanto al campo indica il contributo alla qualità su WikiCasa, verificato nella schermata del suo gestionale. Non rende l’esclusiva obbligatoria e non certifica l’invio del dato: il collegamento nei connettori dei portali va verificato separatamente. Dichiarare “Sì” soltanto quando l’incarico è realmente esclusivo.

Qualità, requisiti dello score e pubblicazione sui portali

Riferimenti verificati il 28 ottobre 2026. Q indica un fattore di qualità documentato; P indica un requisito di pubblicazione; C indica una condizione che dipende da tipologia, contratto o contenuti inviati. Un campo può avere più ruoli. Non esiste un elenco unico di campi sempre obbligatori per lo score dei tre portali. Un dettaglio facoltativo può dare punti senza essere necessario per pubblicare; un campo tecnico obbligatorio può non avere un punteggio autonomo.

Le tabelle indicano quali informazioni Realgest possono alimentare i fattori. Non attestano che ogni connettore le trasmetta già. I nomi nel gruppo dettagli_annuncio sono figli dell’oggetto SOAP, non parametri diretti. Le voci indicate come GUI sono dati del gestionale: non inviarne arbitrariamente il nome come nuovo parametro SOAP.

Indice: Immobiliare.it · WikiCasa · idealista · Requisiti obbligatori e condizionali.

Immobiliare.it: campi che contribuiscono allo score

Le guide ufficiali distinguono completezza, acquisizione e qualità. I fattori seguenti sono Q; le condizioni riportate non diventano nuovi obblighi delle API Realgest.

Fonti: qualità Immobiliare.it, guida di pubblicazione, FAQ tecniche, FotoPlan e documenti energetici. Non viene ricostruita una formula o attribuito un peso a ogni singolo campo.

WikiCasa: campi che contribuiscono allo score

La schermata di qualità del gestionale WikiCasa fornita al progetto mostra i fattori Q seguenti. È una rilevazione su un annuncio: non dimostra una formula universale per tutte le tipologie. I corrispondenti REST sono stati confrontati con la documentazione ufficiale archiviata.

La voce di qualità relativa al canale webservice/manuale osservata nella schermata non è un attributo dell’immobile da inventare o un nuovo parametro SOAP. I dettagli dei requisiti REST sono nelle regole di validazione e nei campi minimi.

idealista: campi che contribuiscono allo score

Secondo la guida ufficiale idealista, la qualità è calcolata sugli annunci pubblicati e fattori/pesi variano per tipologia. Foto, planimetria, video e tour sono fattori distinti; la lista non li rende tutti obbligatori per pubblicare. Non applicare le soglie di Immobiliare.it a idealista.

Quali dati sono obbligatori e quali servono allo score

Per lo score: per ottenere il beneficio di un fattore occorre soddisfare le sue condizioni documentate, come le soglie fotografiche/testuali sopra indicate. Questo non significa che tutti i fattori debbano essere presenti per accettare o pubblicare l’annuncio. Le condizioni non documentate rimangono da verificare sul portale; non sono presentate come regole certe.

Per idealista i requisiti tecnici qui riassunti provengono dallo schema ufficiale del feed v6 archiviato; non vanno sostituiti con le firme della diversa API REST. Eventuali limiti o servizi aggiuntivi dell’account vanno verificati separatamente. Nello schema, minItems si applica quando un array è presente: non prova da solo che il campo sia obbligatorio.

API Realgest: questi riferimenti documentali non introducono nuovi blocchi, nuovi campi obbligatori o correzioni automatiche. Prezzo zero rimane rappresentabile nelle API Realgest anche quando una destinazione lo rifiuta. Non inventare bagni, locali, superfici, coordinate, dotazioni o incarichi esclusivi. Verificare separatamente esito del salvataggio, esito del connettore e pubblicazione sul portale.

Qualità degli annunci sui portali immobiliari

Una scheda completa, corretta e corredata da contenuti utili favorisce una buona presentazione sui portali. Lo score viene però calcolato da ciascuna destinazione: fattori, pesi e disponibilità dipendono dal portale e dalla tipologia. Non esiste una percentuale universale garantita da Realgest. Le indicazioni seguenti sono raccomandazioni editoriali, distinte dalla validità tecnica delle chiamate API.

Questa guida non introduce controlli di qualità nel codice API, blocchi al salvataggio, obblighi su campi facoltativi o modifiche ai mapper. La descrizione corta, l'assenza di un media o un dato sconosciuto non diventano per questo nuovi errori delle API. Restano valide le verifiche tecniche dei tipi e delle autorizzazioni.

Come leggere lo score: completezza della scheda, corretta acquisizione dei dati e punteggio restituito dal portale sono verifiche diverse. L'indice gestionale Realgest comprende anche informazioni interne: non va equiparato a uno score esterno. Qualità, visibilità commerciale e posizione nelle ricerche non sono la stessa misura; nessuna compilazione garantisce un determinato posizionamento.

Riferimenti ufficiali consultati il 23 ottobre 2026: criteri di qualità Immobiliare.it, fattori di qualità idealista, indicazioni Wikicasa su completezza e contenuti. Sono fonti distinte: le raccomandazioni di questa guida non ne uniformano algoritmi o soglie.