Für Makler / Schnittstelle

Schnittstelle für Maklerprogramme

Für Objektdeck und jedes andere Programm: Objekte per JSON einzeln übertragen, Änderungen sind sofort online. Alternativ OpenImmo per FTP oder HTTP.

Grundlagen

Basisadresse: https://heimziel.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
`GET /projekte`	Neubauprojekte mit Einheiten, kostenlosem Kontingent je Projekt und Adresse der Landingpage
`PUT /projekte/{schluessel}`	Projektdaten für die Landingpage (siehe unten)

Beispiel

PUT https://heimziel.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, zimmer, grundstueck, buero, einzelhandel, gastronomie, gewerbe, anlage, stellplatz, landwirtschaft, sonstiges.
merkmale: balkon, terrasse, garten, aufzug, keller, stellplatz, einbaukueche, barrierefrei, neubau, haustiere, denkmal, moebliert, teilmoebliert, studenten, befristet, pauschalmiete, wlan, gaeste_wc, dachboden, kamin, klima, sauna, pool, wintergarten, loggia, abstellraum, waschkueche, glasfaser, smarthome, ladestation, photovoltaik, rollstuhl, wbs, senioren, einliegerwohnung, ferienhaus, rampe, kran, starkstrom, lastenaufzug, kantine, teekueche, edv, barrierefrei_zugang, gastrokueche, aussenflaeche, provisionsfrei.
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.

Neubauprojekte (Bauträger)

Einheiten eines Projekts schicken Sie wie jedes Objekt, mit dem gleichen Wert im Feld "projekt" (z. B. "Wohnen am Stadtpark"; bei OpenImmo die Gruppenkennung). Daraus entsteht automatisch die Landingpage mit Wohnungsfinder, Verfügbarkeit und Preisliste. Je Projekt sind 20 Einheiten gleichzeitig kostenlos.

Projekttexte setzen Sie optional per PUT /projekte/{schluessel}; schluessel ist der Projektname in Kleinbuchstaben mit Bindestrichen (wohnen-am-stadtpark).

PUT https://heimziel.de/api/v1/projekte/wohnen-am-stadtpark
Authorization: Bearer ip_…
Content-Type: application/json

{"name": "Wohnen am Stadtpark", "untertitel": "24 Eigentumswohnungen, KfW 40",
 "highlights": ["Fußbodenheizung", "Tiefgarage", "Aufzug in alle Etagen"],
 "beschreibung": "…", "lage": "…", "fertigstellung": "Herbst 2027",
 "bautenstand": 45, "bautenstand_text": "Rohbau fertig",
 "video_url": "https://www.youtube.com/watch?v=…", "rundgang_url": "https://…",
 "kontakt": {"name": "Frau Muster", "telefon": "069 123456", "email": "verkauf@beispiel.net", "zeiten": "Mo–Fr 9–18 Uhr"}}

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://heimziel.de/api/openimmo (Feld datei) oder per FTP. Vollübertragung und Teilübertragung, Aktion DELETE.