SwissRETS JSON via la Supply API
Ton logiciel envoie chaque annonce en SwissRETS JSON par HTTP PUT. Homematch la vérifie par rapport au schéma et la publie.
Le profil
SwissRETS est le standard suisse ouvert pour les données d’annonces, publié par Qualipool. Notre profil homematch-swissrets-json-2 définit comment les données arrivent par HTTP : SwissRETS 3.6.0 comme contenu, ce que SwissRETS ne connaît pas dans extensions.
Envoyer une annonce
Un PUT par annonce, avec ton propre numéro d’annonce comme clé. Un nouveau PUT remplace l’annonce, et publicationState détermine si elle est visible.
PUT https://api-tenant.homematch.ch/api/marketplace/supply/v1/listings/{providerListingKey}En-têtes
X-Api-Key- Ta clé d’accès. Chaque agence a la sienne.
Idempotency-Key- Unique par envoi. Une répétition avec la même clé n’est appliquée qu’une fois.
X-Provider-Contract- La version du contrat pour laquelle tu as développé, aujourd’hui 2.
Contenu
profileVersion- Toujours homematch-swissrets-json-2.
swissRetsVersion- Toujours 3.6.0.
revision- Ton identifiant pour cet état de l’annonce.
revisionOrdinal- Un nombre qui augmente à chaque modification. Un état plus ancien ne remplace pas un état plus récent.
occurredAt- Quand tu as modifié l’annonce (ISO 8601).
publicationState- published ou unpublished.
property- Un objet de SwissRETS properties[], tel quel.
extensions.parties- Qui reçoit les demandes : exactement un inquiry_recipient avec e-mail.
extensions.declaredActions- Ce que les intéressés peuvent faire : aujourd’hui une action avec kind « inquiry ».
Ce qu’il faut à une annonce
- Un NPA
- Un prix ou « Prix sur demande »
- Un titre ou une description
- Au moins une image
- Surface habitable (areaBwf, sinon areaNwf) et pièces supérieures à 0, ou omises
- Exactement un destinataire pour les demandes
Ce que nous lisons
Ces champs de SwissRETS properties[] alimentent l’annonce. Nous ignorons les autres champs, y compris les pièces jointes logos et landRegisterExtracts.
- id
- referenceId
- visualReferenceId
- type
- availability
- categories
- address
- prices
- characteristics
- localizations
- seller
- bfs
- externalReference
- minergieCertification
Envoyer tout le portefeuille
Au lieu d’envoyer les annonces une à une, tu peux envoyer tout ton portefeuille d’un coup : PUT complete-inventory remplace toutes les annonces de ton accès, et ce qui manque est retiré.
Erreurs
Chaque refus est un problème RFC 9457 avec un code fixe. Les valeurs invalides arrivent en validation_failed (400) avec des pointeurs JSON. Une annonce qui ne peut pas être publiée est refusée avec supply_listing_unpublishable (422), et une annonce déjà publiée reste dans son dernier état.
Exemple
{
"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"
}
]
}
}Prêt à tester ?
Nous te donnons accès à notre environnement de test et vérifions ta connexion avant sa mise en ligne.