Aller au contenu principal
En ligneÉtat au 19 novembre 2026

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.

HTTP
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

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"
      }
    ]
  }
}

Prêt à tester ?

Nous te donnons accès à notre environnement de test et vérifions ta connexion avant sa mise en ligne.