Pubblicare da gestionale

Come funziona

1. Ci chiedi le credenziali per l'agenzia: username, password e, se vuoi, gli indirizzi IP da cui partiranno le chiamate.
2. Per ogni immobile in affitto mandi una PUT con il tuo identificativo interno nell'URL. La stessa chiamata ripetuta aggiorna l'annuncio, non lo duplica.
3. Quando l'immobile esce dal mercato mandi una DELETE, oppure la stessa PUT con operation="archive".

Endpoint

Autenticazione

HTTP Basic su ogni chiamata, più l'header X-SC-SOURCE con il nome del gestionale. Se ci comunichi gli IP dei tuoi server, le chiamate da altri indirizzi vengono rifiutate. Corpo e risposta sono XML in UTF-8.

Esempio di payload

Ogni nodo supportato compare qui: quello che non ti serve puoi ometterlo.

<?xml version="1.0" encoding="UTF-8"?>
<property operation="write" xmlns:sc="urn:spottedcasa:feed:1.0">
  <unique-id>ABC-123</unique-id>
  <last-modified>2026-07-30T09:15:00</last-modified>
  <agent>
    <office-name>Agenzia Esempio</office-name>
    <email>agenzia@example.it</email>
  </agent>
  <location>
    <latitude>45.0703</latitude>
    <longitude>7.6869</longitude>
    <city istat="001272">Torino</city>
    <address>Via Roma</address>
    <street-number>10</street-number>
    <zipcode>10121</zipcode>
    <district>Centro</district>
    <hide-address>true</hide-address>
  </location>
  <transactions>
    <transaction type="R">
      <price currency="EUR">650</price>
      <condo-fees>50</condo-fees>
      <condo-fees-included>false</condo-fees-included>
      <utilities-included>false</utilities-included>
      <utilities-monthly-cost>60</utilities-monthly-cost>
      <deposit-months>2</deposit-months>
      <flat-rate-tax>true</flat-rate-tax>
      <contract-type>university_students</contract-type>
      <available-from>2026-09-01</available-from>
      <min-stay-months>10</min-stay-months>
      <max-stay-months>12</max-stay-months>
    </transaction>
  </transactions>
  <descriptions>
    <description language="it">
      <title>Bilocale luminoso in centro</title>
      <text>Appartamento ristrutturato a due passi dal Politecnico.</text>
    </description>
  </descriptions>
  <features>
    <surface>55</surface>
    <rooms>2</rooms>
    <bathrooms>1</bathrooms>
    <floor>3</floor>
    <total-floors>5</total-floors>
    <furnished>furnished</furnished>
    <heating>independent</heating>
    <energy-class>C</energy-class>
    <condition>renovated</condition>
    <build-year>1970</build-year>
  </features>
  <pictures>
    <picture position="1" url="https://esempio.it/foto/1.jpg"/>
  </pictures>
  <sc:extension>
    <sc:room-type>single</sc:room-type>
    <sc:bed-type>double</sc:bed-type>
    <sc:bathroom-type>ensuite</sc:bathroom-type>
    <sc:current-flatmates>2</sc:current-flatmates>
    <sc:gender-preference>any</sc:gender-preference>
    <sc:pet-friendly>true</sc:pet-friendly>
    <sc:smokers-allowed>false</sc:smokers-allowed>
    <sc:couples-allowed>true</sc:couples-allowed>
    <sc:tenant-min-age>18</sc:tenant-min-age>
    <sc:tenant-max-age>35</sc:tenant-max-age>
  </sc:extension>
</property>

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse>
  <Result>true</Result>
  <ErrorCode>0</ErrorCode>
  <idListing>1234</idListing>
  <RequestID>9f1c8f0e-6f5a-4a1b-9a1e-2b6f5d3c7a10</RequestID>
</ServiceResponse>

Cosa non può mancare

• transactions/transaction/@type valorizzato a R: accettiamo solo affitti, gli immobili in vendita vengono rifiutati.
• location/city/@istat con il codice ISTAT del comune, e il prezzo mensile in euro.
• last-modified: se non è più recente dell'ultima sincronizzazione, saltiamo la scrittura e rispondiamo comunque ok.

Campi SpottedCasa

SpottedCasa è un portale di affitti per studenti: stanze, coinquilini, regole di convivenza. Nessun tracciato di portale prevede questi campi, quindi vivono in un nostro namespace opzionale (urn:spottedcasa:feed:1.0). Senza il nodo sc:room-type l'annuncio è un appartamento intero.

Codici di errore

Foto

Le immagini indicate in pictures vengono scaricate subito dopo la risposta, quindi compaiono sull'annuncio qualche minuto dopo. Massimo 20 foto per annuncio, 8 MB ciascuna, in JPEG, PNG, WebP o AVIF.

Contatti verso il gestionale

Chiama /ws/export/requests con il parametro since per riportare nel tuo CRM i contatti arrivati sugli annunci dell'agenzia. La risposta contiene nome, messaggio e il link alla conversazione: la trattativa prosegue sulla piattaforma, dove l'agenzia risponde con il proprio account.

Chiedere le credenziali

Scrivici indicando agenzia, partita IVA e gestionale usato: apriamo un'utenza di prova per sviluppare l'integrazione e poi quella definitiva.