Schnittstelle für Maklerprogramme

Grundlagen

• Basisadresse: https://heimtreffer.de/api/v1
• Anmeldung: Kopfzeile Authorization: Bearer <Import-Token>. Das Token erzeugt der Makler im Makler-Bereich.
• Format: JSON, UTF-8, Accept: application/json. Beträge in Euro, Flächen in m².
• Höchstens 240 Aufrufe pro Minute je Token.
• Voraussetzung: Einwilligung des Maklers, im Makler-Bereich oder per POST /einwilligung. Ohne Einwilligung antwortet die Schnittstelle mit 409.

Aufrufe

GET /status	Konto, Einwilligung, Anzahl Objekte online, Einwilligungstext
POST /einwilligung	{"erteilt": true, "name": "Vor- und Nachname"} erteilt, {"erteilt": false} widerruft und nimmt alle übertragenen Objekte offline
PUT /objekte/{objektnummer}	Objekt anlegen oder ändern. Antwort 201 (neu) oder 200, mit Adresse der Anzeige
DELETE /objekte/{objektnummer}	Objekt offline nehmen
GET /objekte	Alle übertragenen Objekte mit Status, zum Abgleich

Beispiel

PUT https://heimtreffer.de/api/v1/objekte/OBJ-00632
Authorization: Bearer ip_…
Content-Type: application/json

{
  "status": "aktiv",
  "vermarktung": "kauf",
  "art": "wohnung",
  "unterart": "Etagenwohnung",
  "titel": "Helle 3-Zimmer-Wohnung mit Balkon",
  "beschreibung": "…",
  "lage": "…",
  "adresse": { "strasse": "Musterweg", "hausnummer": "5", "plz": "60311",
               "ort": "Frankfurt am Main", "stadtteil": "Innenstadt",
               "lat": 50.1109, "lng": 8.6821 },
  "preise": { "kaufpreis": 489000, "hausgeld": 310,
              "provision": "3,57 % inkl. MwSt.", "provisionspflichtig": true },
  "flaechen": { "wohnflaeche": 82.5, "zimmer": 3, "baeder": 1, "etage": 2 },
  "baujahr": 1998,
  "merkmale": ["balkon", "aufzug", "keller", "einbaukueche"],
  "energie": { "art": "Verbrauchsausweis", "kennwert": "98", "traeger": "Gas",
               "klasse": "C", "baujahr": "1998", "gueltig_bis": "2031-05-01" },
  "bilder": [ { "url": "https://crm.example.de/medien/1.jpg", "titel": "Wohnzimmer", "gruppe": "titelbild" },
              { "url": "https://crm.example.de/medien/2.jpg", "gruppe": "grundriss" } ],
  "kontakt": { "name": "Anna Beispiel", "telefon": "069 123456", "email": "anna@example.de" }
}

Felder

• status: aktiv, reserviert, verkauft, vermietet, inaktiv. art: wohnung, haus, grundstueck, buero, einzelhandel, gewerbe, anlage, sonstiges.
• merkmale: balkon, terrasse, garten, aufzug, keller, stellplatz, einbaukueche, barrierefrei, neubau, haustiere, denkmal, moebliert.
• Die genaue Adresse wird nie veröffentlicht. Ohne Koordinaten ermitteln wir die Lage aus der Adresse.
• Bilder werden von den HTTPS-Adressen geladen, nur wenn sich die Liste ändert. Interne Adressen werden abgelehnt, höchstens 15 MB je Bild.
• Fehlen Angaben zum Energieausweis, wird das Objekt trotzdem gespeichert und die Antwort enthält einen Hinweis nach § 87 GEG.

Anfragen zurück ins CRM

Ist im Makler-Bereich eine Webhook-Adresse hinterlegt, kommt jede Anfrage als JSON per POST. Die Kopfzeile X-Portal-Signatur enthält den HMAC-SHA256 des Inhalts.

OpenImmo

Für Programme ohne JSON-Abgleich: OpenImmo-ZIP per POST https://heimtreffer.de/api/openimmo (Feld datei) oder per FTP. Vollübertragung und Teilübertragung, Aktion DELETE.