Vai al contenuto principale
LiveAggiornato al 19 novembre 2026

SwissRETS JSON tramite la Supply API

Il tuo software invia ogni annuncio come SwissRETS JSON via HTTP PUT. Homematch lo verifica rispetto allo schema e lo pubblica.

Il profilo

SwissRETS è lo standard svizzero aperto per i dati degli annunci, pubblicato da Qualipool. Il nostro profilo homematch-swissrets-json-2 stabilisce come arrivano i dati via HTTP: SwissRETS 3.6.0 come contenuto, ciò che SwissRETS non prevede in extensions.

Inviare un annuncio

Un PUT per annuncio, con il tuo numero di annuncio come chiave. Un nuovo PUT sostituisce l'annuncio, e publicationState determina se è visibile.

HTTP
PUT https://api-tenant.homematch.ch/api/marketplace/supply/v1/listings/{providerListingKey}

Header

X-Api-Key
La tua chiave di accesso. Ogni agenzia ha la propria.
Idempotency-Key
Unica per invio. Una ripetizione con la stessa chiave viene applicata una sola volta.
X-Provider-Contract
La versione del contratto per cui hai sviluppato, oggi 2.

Contenuto

profileVersion
Sempre homematch-swissrets-json-2.
swissRetsVersion
Sempre 3.6.0.
revision
Il tuo identificativo per questo stato dell'annuncio.
revisionOrdinal
Un numero che cresce a ogni modifica. Uno stato più vecchio non sostituisce uno più recente.
occurredAt
Quando hai modificato l'annuncio (ISO 8601).
publicationState
published o unpublished.
property
Un oggetto di SwissRETS properties[], invariato.
extensions.parties
Chi riceve le richieste: esattamente un inquiry_recipient con e-mail.
extensions.declaredActions
Cosa possono fare gli interessati: oggi un'azione con kind «inquiry».

Cosa serve a un annuncio

  • Un NPA
  • Un prezzo o «prezzo su richiesta»
  • Un titolo o una descrizione
  • Almeno un'immagine
  • Superficie abitabile (areaBwf, altrimenti areaNwf) e locali maggiori di 0, oppure omessi
  • Esattamente un destinatario per le richieste

Cosa leggiamo

Questi campi di SwissRETS properties[] confluiscono nell'annuncio. Gli altri campi li ignoriamo, anche gli allegati logos e landRegisterExtracts.

  • id
  • referenceId
  • visualReferenceId
  • type
  • availability
  • categories
  • address
  • prices
  • characteristics
  • localizations
  • seller
  • bfs
  • externalReference
  • minergieCertification

Inviare l'intero portafoglio

Invece che uno alla volta, puoi inviare l'intero portafoglio in un colpo solo: PUT complete-inventory sostituisce tutti gli annunci del tuo accesso, e ciò che manca viene ritirato.

Errori

Ogni rifiuto è un problem secondo RFC 9457 con un code fisso. I valori non validi arrivano come validation_failed (400) con JSON Pointer. Un annuncio che non può essere pubblicato viene rifiutato con supply_listing_unpublishable (422), e uno già pubblicato resta al suo ultimo stato.

Esempio

listing.json
{
  "profileVersion": "homematch-swissrets-json-2",
  "swissRetsVersion": "3.6.0",
  "revision": "rev-2026-11-19-001",
  "revisionOrdinal": 1001,
  "occurredAt": "2026-11-19T09:00:00Z",
  "publicationState": "published",
  "property": {
    "id": "example-rent-1234",
    "referenceId": "R-1234",
    "visualReferenceId": "1234.01.0012",
    "type": "rent",
    "categories": [
      "apartment"
    ],
    "availability": {
      "state": "active",
      "start": "2027-01-01T00:00:00+01:00"
    },
    "address": {
      "street": "Musterstrasse",
      "streetNumber": "12",
      "postalCode": "8000",
      "locality": "Zürich",
      "countryCode": "CH"
    },
    "prices": {
      "currency": "CHF",
      "rent": {
        "net": 2150,
        "extra": 250,
        "gross": 2400,
        "interval": "month",
        "referring": "all"
      }
    },
    "characteristics": {
      "numberOfRooms": 3.5,
      "areaBwf": 82,
      "floor": 2,
      "hasBalcony": "applies",
      "hasElevator": "applies"
    },
    "localizations": [
      {
        "languageCode": "de",
        "title": "Helle 3½-Zimmer-Wohnung mit Balkon",
        "description": "Ruhige Lage, fünf Minuten zum Bahnhof.",
        "attachments": {
          "images": [
            {
              "url": "https://media.example.invalid/1234/living-room.jpg",
              "mimeType": "image/jpeg"
            }
          ]
        }
      }
    ],
    "seller": {
      "organization": {
        "id": "agency-42",
        "legalName": "Beispiel Immobilien AG",
        "email": "info@example.invalid"
      },
      "contactPerson": {
        "givenName": "Lea",
        "familyName": "Beispiel",
        "email": "lea.beispiel@example.invalid"
      }
    }
  },
  "extensions": {
    "parties": [
      {
        "providerPartyId": "agency-42-inquiries",
        "role": "inquiry_recipient",
        "kind": "organization",
        "profile": {
          "email": "vermietung@example.invalid"
        }
      }
    ],
    "declaredActions": [
      {
        "kind": "inquiry"
      }
    ]
  }
}

Pronto per il test?

Ti diamo accesso al nostro ambiente di test e verifichiamo il tuo collegamento prima che vada online.