Panoramica del servizio

Convenzioni generali

• Tutti i metodi documentati richiedono admin_api_key.
• Le risposte applicative espongono Success, Error ed ErrorCode. Verificare Success === true prima di usare il payload.
• Gli header SOAPAction negli esempi usano la forma breve, ad esempio SOAPAction: "RG_AddAnnuncio".
• Le tabelle nello ZIP realgest_anagrafiche.zip rappresentano i valori anagrafici da usare per molti campi id_*.
• Per la pubblicazione sui portali usare RG_GetPortali, RG_GetPortaliAnnuncio e RG_SetPortaliAnnuncio. I metodi di esclusione (RG_GetEsclusioneAnnuncio, RG_SetEsclusioneAnnuncio) restano disponibili quando il flusso applicativo lavora per portali esclusi.
• RG_SetPortaliAnnuncio con almeno un portale valido abilita anche l'annuncio al multiinvio generale; con lista vuota o senza portali validi disabilita l'annuncio dal multiinvio.
• Il parametro superficie viene salvato sia nel campo specifico fabbricato sia nel campo generico storico; in lettura viene restituito il primo valore disponibile tra superficie fabbricato, terreno edificabile, terreno agricolo e superficie generica.
• Per annunci di stanze o camere usare id_tipologia=64 (Stanza/Camera) invece della tipologia generica Altro.
• In RG_AddAnnuncio e RG_UpdateAnnuncio, se id_comune, id_provincia o id_regione identificano un territorio collegato a una nazione, id_nazione viene riallineato automaticamente a quella nazione. I valori geografici 0 o stringa vuota vengono salvati come NULL.
• Le coordinate lat e long vengono salvate solo se passate dal chiamante; le API non eseguono geocoding automatico da indirizzo, comune o località.

Autenticazione ed error handling

La chiave amministrativa viene passata come parametro SOAP admin_api_key. Non è prevista nel WSDL un’autenticazione HTTP separata.

if ($response->Success !== true) {
    throw new RuntimeException($response->Error . ' (' . $response->ErrorCode . ')');
}

Metodi principali

La sezione seguente si concentra sui metodi utili per consultare e sincronizzare annunci, lookup territoriali/tipologici e pubblicazione sui portali.

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_GetAnnunci"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_GetAnnunci>
        <admin_api_key>API_KEY</admin_api_key>
        <id_agenzia>0</id_agenzia>
        <data_inserimento>2026-05-21</data_inserimento>
        <id_tipo_offerta>0</id_tipo_offerta>
        <id_classe>0</id_classe>
        <id_tipologia>0</id_tipologia>
        <id_comune>0</id_comune>
        <prezzo_min>100000</prezzo_min>
        <prezzo_max>300000</prezzo_max>
        <solo_con_foto>false</solo_con_foto>
        <start>0</start>
        <limit>0</limit>
        <ordinamento>data_inserimento</ordinamento>
        <ordinamento_verso>DESC</ordinamento_verso>
    </ws:WsAction.RG_GetAnnunci>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_GetAnnuncio"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_GetAnnuncio>
        <admin_api_key>API_KEY</admin_api_key>
        <id>0</id>
        <id_agenzia>0</id_agenzia>
    </ws:WsAction.RG_GetAnnuncio>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_GetTipologieImmobili"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_GetTipologieImmobili>
        <admin_api_key>API_KEY</admin_api_key>
        <id_agenzia>0</id_agenzia>
    </ws:WsAction.RG_GetTipologieImmobili>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_GetTipologieOfferta"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_GetTipologieOfferta>
        <admin_api_key>API_KEY</admin_api_key>
        <id_agenzia>0</id_agenzia>
    </ws:WsAction.RG_GetTipologieOfferta>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_GetComune"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_GetComune>
        <admin_api_key>API_KEY</admin_api_key>
        <term>Roma</term>
        <id_agenzia>0</id_agenzia>
    </ws:WsAction.RG_GetComune>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_GetZone"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_GetZone>
        <admin_api_key>API_KEY</admin_api_key>
        <term>Roma</term>
        <idcomune>0</idcomune>
        <selected></selected>
    </ws:WsAction.RG_GetZone>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_AddAnnuncio"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_AddAnnuncio>
        <admin_api_key>API_KEY</admin_api_key>
        <id_agenzia>0</id_agenzia>
        <riferimento_annuncio>Luminoso trilocale zona centrale</riferimento_annuncio>
        <codice_immobile>IMM-001</codice_immobile>
        <id_orig>1234</id_orig>
        <id_tipo_offerta>0</id_tipo_offerta>
        <id_classe>0</id_classe>
        <id_tipologia>0</id_tipologia>
        <id_classe_energetica>0</id_classe_energetica>
        <ipe></ipe>
        <id_categoria_catastale>0</id_categoria_catastale>
        <id_nazione>0</id_nazione>
        <id_regione>0</id_regione>
        <id_provincia>0</id_provincia>
        <id_comune>0</id_comune>
        <id_area>0</id_area>
        <localita></localita>
        <indirizzo>Via Roma</indirizzo>
        <civico>1</civico>
        <cap>00100</cap>
        <lat>41.9028</lat>
        <long>12.4964</long>
        <mostra_ubicazione>true</mostra_ubicazione>
        <descrizione>Descrizione immobile</descrizione>
        <costi_condominiali></costi_condominiali>
        <data_inserimento>2026-06-10</data_inserimento>
        <data_incarico>2026-06-10</data_incarico>
        <data_fine_incarico></data_fine_incarico>
        <visualizza_prezzo>true</visualizza_prezzo>
        <attivo>true</attivo>
        <id_tipologia_disponibilita>0</id_tipologia_disponibilita>
        <id_riscaldamento>0</id_riscaldamento>
        <locali>3</locali>
        <servizi>1</servizi>
        <id_box>0</id_box>
        <id_cucina>0</id_cucina>
        <id_condizione>0</id_condizione>
        <id_condizione_esterno>0</id_condizione_esterno>
        <piani_fuori_fabbricato></piani_fuori_fabbricato>
        <id_piano>0</id_piano>
        <piano></piano>
        <giardino>false</giardino>
        <terrazzo>false</terrazzo>
        <balcone>false</balcone>
        <ascensore>false</ascensore>
        <cantina>false</cantina>
        <aria_condizionata>false</aria_condizionata>
        <climatizzazione>false</climatizzazione>
        <anno_costruzione>0</anno_costruzione>
        <anno_ristrutturazione>0</anno_ristrutturazione>
        <arredato>false</arredato>
        <prezzo>100000</prezzo>
        <superficie>80</superficie>
        <escludi_tutti_i_portali>false</escludi_tutti_i_portali>
        <immagini>
          <item>
            <url>https://www.example.com/foto1.jpg</url>
            <title>Foto principale</title>
            <principale>true</principale>
          </item>
          <item>
            <url>https://www.example.com/foto2.jpg</url>
            <title>Seconda foto</title>
            <principale>false</principale>
          </item>
        </immagini>
        <planimetria>https://www.example.com/planimetria.pdf</planimetria>
</ws:WsAction.RG_AddAnnuncio>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_UpdateAnnuncio"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_UpdateAnnuncio>
        <admin_api_key>API_KEY</admin_api_key>
        <id>12345</id>
        <riferimento_annuncio>Luminoso trilocale zona centrale</riferimento_annuncio>
        <codice_immobile>IMM-001</codice_immobile>
        <id_tipo_offerta>0</id_tipo_offerta>
        <id_classe>0</id_classe>
        <id_tipologia>0</id_tipologia>
        <id_classe_energetica>0</id_classe_energetica>
        <ipe></ipe>
        <id_categoria_catastale>0</id_categoria_catastale>
        <id_nazione>0</id_nazione>
        <id_regione>0</id_regione>
        <id_provincia>0</id_provincia>
        <id_comune>0</id_comune>
        <id_area>0</id_area>
        <localita></localita>
        <indirizzo>Via Roma</indirizzo>
        <civico>1</civico>
        <cap>00100</cap>
        <lat>41.9028</lat>
        <long>12.4964</long>
        <mostra_ubicazione>true</mostra_ubicazione>
        <descrizione>Descrizione immobile</descrizione>
        <costi_condominiali></costi_condominiali>
        <data_inserimento>2026-06-10</data_inserimento>
        <data_incarico>2026-06-10</data_incarico>
        <data_fine_incarico></data_fine_incarico>
        <visualizza_prezzo>true</visualizza_prezzo>
        <attivo>true</attivo>
        <id_tipologia_disponibilita>0</id_tipologia_disponibilita>
        <id_riscaldamento>0</id_riscaldamento>
        <locali>3</locali>
        <servizi>1</servizi>
        <id_box>0</id_box>
        <id_cucina>0</id_cucina>
        <id_condizione>0</id_condizione>
        <id_condizione_esterno>0</id_condizione_esterno>
        <piani_fuori_fabbricato></piani_fuori_fabbricato>
        <id_piano>0</id_piano>
        <piano></piano>
        <giardino>false</giardino>
        <terrazzo>false</terrazzo>
        <balcone>false</balcone>
        <ascensore>false</ascensore>
        <cantina>false</cantina>
        <aria_condizionata>false</aria_condizionata>
        <climatizzazione>false</climatizzazione>
        <anno_costruzione>0</anno_costruzione>
        <anno_ristrutturazione>0</anno_ristrutturazione>
        <arredato>false</arredato>
        <prezzo>100000</prezzo>
        <superficie>80</superficie>
        <immagini>
          <item>
            <url>https://www.example.com/foto1.jpg</url>
            <title>Foto principale</title>
            <principale>true</principale>
          </item>
          <item>
            <url>https://www.example.com/foto2.jpg</url>
            <title>Seconda foto</title>
            <principale>false</principale>
          </item>
        </immagini>
        <planimetria>https://www.example.com/planimetria.pdf</planimetria>
        <id_orig>1234</id_orig>
    </ws:WsAction.RG_UpdateAnnuncio>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_GetPortali"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_GetPortali>
        <admin_api_key>API_KEY</admin_api_key>
    </ws:WsAction.RG_GetPortali>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_GetPortaliAnnuncio"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_GetPortaliAnnuncio>
        <admin_api_key>API_KEY</admin_api_key>
        <id>0</id>
    </ws:WsAction.RG_GetPortaliAnnuncio>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_SetPortaliAnnuncio"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_SetPortaliAnnuncio>
        <admin_api_key>API_KEY</admin_api_key>
        <id>0</id>
        <id_portali>
          <item>1</item>
          <item>2</item>
        </id_portali>
    </ws:WsAction.RG_SetPortaliAnnuncio>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_SetEsclusioneAnnuncio"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_SetEsclusioneAnnuncio>
        <admin_api_key>API_KEY</admin_api_key>
        <id>0</id>
        <id_portali>
          <item>1</item>
          <item>2</item>
        </id_portali>
    </ws:WsAction.RG_SetEsclusioneAnnuncio>
  </soapenv:Body>
</soapenv:Envelope>

POST /ws/index.php HTTP/1.1
Host: software.realgest.it
Content-Type: text/xml; charset=utf-8
SOAPAction: "RG_GetEsclusioneAnnuncio"

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ws="https://software.realgest.it/ws/">
  <soapenv:Body>
    <ws:WsAction.RG_GetEsclusioneAnnuncio>
        <admin_api_key>API_KEY</admin_api_key>
        <id>0</id>
    </ws:WsAction.RG_GetEsclusioneAnnuncio>
  </soapenv:Body>
</soapenv:Envelope>

Tipi dati e campi annuncio

Il tipo RG_Annuncio contiene il dettaglio dell’immobile restituito da RG_GetAnnuncio e dagli elenchi annunci. Di seguito i campi più rilevanti per l’integrazione.

Tipi per immagini e planimetria in inserimento/aggiornamento

Nei metodi RG_AddAnnuncio e RG_UpdateAnnuncio, le immagini sono inviate con RG_ImmaginiArray. La planimetria catastale è esposta nella firma dei metodi come campo planimetria di tipo string.

Tabelle anagrafiche da realgest_anagrafiche.zip

Le tabelle anagrafiche servono per alimentare i campi id_* in inserimento e ricerca. Possono essere importate localmente e aggiornate quando viene distribuita una nuova versione dello ZIP.

Mapping rapido

Esempio client PHP

Esempio minimo con SoapClient. In produzione aggiungere timeout, logging, validazione input e gestione retry solo per errori transitori.

<?php
$wsdl = 'https://software.realgest.it/ws/index.php?wsdl';
$apiKey = 'INSERIRE_API_KEY';

$client = new SoapClient($wsdl, [
    'trace' => true,
    'exceptions' => true,
    'cache_wsdl' => WSDL_CACHE_NONE,
    'encoding' => 'UTF-8',
]);

try {
    $response = $client->__soapCall('RG_GetAnnunci', [[
        'admin_api_key' => $apiKey,
        'id_agenzia' => 0,
        'data_inserimento' => '',
        'id_tipo_offerta' => 0,
        'id_classe' => 0,
        'id_tipologia' => 0,
        'id_nazione' => 0,
        'id_regione' => 0,
        'id_provincia' => 0,
        'id_comune' => 0,
        'id_area' => 0,
        'prezzo_min' => 0,
        'prezzo_max' => 0,
        'superficie_min' => 0,
        'superficie_max' => 0,
        'locali_min' => 0,
        'locali_max' => 0,
        'servizi_min' => 0,
        'servizi_max' => 0,
        'id_classe_energetica' => 0,
        'id_tipologia_disponibilita' => 0,
        'id_categoria_catastale' => 0,
        'id_riscaldamento' => 0,
        'terrazzo' => false,
        'balcone' => false,
        'ascensore' => false,
        'giardino' => false,
        'cantina' => false,
        'id_box' => 0,
        'id_cucina' => 0,
        'aria_condizionata' => false,
        'climatizzazione' => false,
        'arredato' => false,
        'attivo' => true,
        'data_incarico' => '',
        'solo_con_foto' => false,
        'start' => 0,
        'limit' => 20,
        'ordinamento' => 'data_inserimento',
        'ordinamento_verso' => 'DESC',
    ]]);

    if (!$response->Success) {
        throw new RuntimeException($response->Error . ' (' . $response->ErrorCode . ')');
    }

    foreach ($response->Annunci as $annuncio) {
        // Elaborare o sincronizzare l’annuncio
    }
} catch (SoapFault $e) {
    error_log($e->getMessage());
    error_log($client->__getLastRequest());
    throw $e;
}

Esempio payload per inserimento/aggiornamento annuncio

Per RG_AddAnnuncio e RG_UpdateAnnuncio passare i campi nella stessa sequenza della firma WSDL; nell’aggiornamento usare anche l’ID Realgest dell’annuncio. In RG_UpdateAnnuncio il campo id_orig è disponibile come ultimo parametro opzionale.

$payload = [
    'admin_api_key' => $apiKey,
    'id_agenzia' => 0, // solo RG_AddAnnuncio
    'riferimento_annuncio' => 'Luminoso trilocale zona centrale',
    'codice_immobile' => 'IMM-001',
    'id_orig' => '1234', // in RG_UpdateAnnuncio va passato in coda
    // ... altri campi immobile previsti dal WSDL ...
    'prezzo' => 100000,
    'superficie' => 80,
    'escludi_tutti_i_portali' => false, // solo RG_AddAnnuncio
    'immagini' => [
        [
            'url' => 'https://www.example.com/foto1.jpg',
            'title' => 'Foto principale',
            'principale' => true,
        ],
    ],
    'planimetria' => 'https://www.example.com/planimetria.pdf',
];

$response = $client->__soapCall('RG_AddAnnuncio', [$payload]);

$updatePayload = $payload;
$updateIdOrig = $updatePayload['id_orig'];
unset($updatePayload['id_agenzia'], $updatePayload['escludi_tutti_i_portali']);
$updatePayload = ['admin_api_key' => $apiKey, 'id' => 12345] + array_slice($updatePayload, 1, null, true);
$updatePayload['id_orig'] = $updateIdOrig;
$response = $client->__soapCall('RG_UpdateAnnuncio', [$updatePayload]);

Checklist integrazione