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.
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
{
"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.