REST-API: Projekte
Neubauprojekte in der Form von OpenImmo 2.0 lesen und schreiben. Zwei Ids, das Recht `projects`, Quittungen und die Mitglieder, die von uns sind.
Zuletzt aktualisiert:
Ein Projekt unter /v1/projects ist ein Neubauprojekt des Büros: eine Adresse, ein Name, ein Bauabschnitt und die Kennzahlen seiner Einheiten. Es hat die Form des Projekts in OpenImmo 2.0. Namen, Verschachtelung und erlaubte Werte sind die des Standards. Die Einheiten eines Projekts sind Inserate; diese Seite beschreibt das Projekt selbst.
| Operation | Was sie tut |
|---|---|
GET /v1/projects | die externen Ids der Projekte, neueste zuerst, seitenweise |
GET /v1/projects/{externalProjectId} | ein Projekt, mit einem ETag |
POST /v1/projects | legt ein Projekt an |
PUT /v1/projects/{externalProjectId} | ändert es; mit createIfMissing=true legt es eine unbekannte Id an |
DELETE /v1/projects/{externalProjectId} | entfernt ein Projekt ohne Einheiten |
POST /v1/projects/{externalProjectId}/units | legt bis zu 500 Einheiten an |
POST /v1/projects/{externalProjectId}/assign | macht vorhandene Inserate zu Einheiten |
POST /v1/projects/{externalProjectId}/unassign | löst Einheiten wieder aus dem Projekt |
POST /v1/listings/{externalListingId}/unit-status | setzt den Stand einer Einheit |
Zwei Ids
| Id | Wessen | Wo |
|---|---|---|
externalProjectId | deine | im Pfad jedes Aufrufs, im Rumpf als metadata.source.offererMarketingKey |
projectId | unsere | in Antworten und Ereignissen; sie geht im Pfad immer |
Eine Referenz folgt der Regel der Inserate: 1 bis 128 Buchstaben, Ziffern, Punkte, Unterstriche oder Bindestriche. Sie ist unter den Projekten des Büros eindeutig (reference_already_exists). Ein Projekt ohne Referenz hat seine projectId als externe Id.
Das Recht projects
projects ist eine eigene Ressource unter den Rechten eines Keys, und ein Key hat sie nur, wenn er sie verlangt: Sie ist none, bis sie beim Anlegen des Keys in der App gewählt wird. Ein Key von davor hat sie nicht. Lesen braucht read, Schreiben write; ohne sie antwortet jede Operation mit 403 und insufficient_permissions. Ein Test-Key arbeitet im Testbüro wie ein Live-Key im echten Büro und ändert nur erfundene Daten.
Schreiben wie ein Inserat
| Was | Wie bei Inseraten |
|---|---|
Idempotency-Key | eine Wiederholung mit demselben Key und Rumpf liefert dieselbe Quittung und legt ein Projekt an |
ETag und If-Match | GET trägt den Tag; PUT mit einem veralteten Tag antwortet 412 |
| Seiten | limit, nextPageToken, updatedSince, neueste zuerst |
| Fehler | Problem Details mit code und errors[].name, das das Mitglied nennt |
| Antwort eines Schreibens | 202 mit einer Quittung: requestId, projectId, externalProjectId, warnings |
PUT | führt zusammen: ein Mitglied, das der Rumpf nicht nennt, bleibt; createIfMissing=true legt an |
Was gespeichert wird
Die Mitglieder eines Projekts stehen einmal auf der Seite der Inseratsmitglieder. So passen sie zum Projekt in der App:
data.texts.headlineist der Name des Projekts und beim Anlegen Pflicht.description,areaundfeaturessind Beschreibung, Lagetext und Ausstattungstext.data.locationist die Adresse, gelesen und geschrieben wie die Lage eines Inserats. Das Land ist immer Deutschland.data.distributionTypeistBUYoderRENT.BUY_RENTwird abgelehnt.data.program.projectStatusist der Bauabschnitt:CONSTRUCTION_STARTheißt im Bau,PROJECT_ENDEDfertig.data.deliveryDateist die geplante Fertigstellung, bis 60 Zeichen.data.unitsträgt Kennzahlen, die Athaus aus den Einheiten zählt:numberOfUnits,priceFrom,priceTo,livingSpaceFrom,livingSpaceTo,soldOutPercentage. Geschrieben wird nur die Käuferprovision:provisionType,provisionPercentundprovisionIsVatIncluded.data.estateTypeist immerNEW_BUILD_PROJECT;NEW_HOME_PROJECTwird angenommen und als Neubauprojekt gespeichert.
Ein Mitglied, das der Standard hat und Athaus nicht speichert (links, contact, structure, estateSubType, die Kennzahlen von units oben), wird angenommen und mit einer Warnung FIELD_IGNORED beantwortet; nichts fällt stillschweigend weg.
Mitglieder, die von uns sind
| Mitglied | Wo | Bedeutung |
|---|---|---|
status | Anfrage und Antwort | der Name eines Projektstatus des Büros, etwa Vertrieb; ohne ihn beginnt ein neues Projekt im ersten Status |
projectId | Antwort | die Id, die Athaus dem Projekt gab |
createdAt, updatedAt | Antwort | wann das Projekt angelegt und zuletzt geändert wurde |
projects | in der Id-Liste | eine Übersicht je Projekt: projectId, externalProjectId, status, updatedAt |
Einheiten
Eine Einheit ist ein Inserat mit einem Projekt, keine zweite Ressource. Sie hat alle Operationen und Mitglieder eines Inserats, und projectId zeigt an, zu welchem Projekt sie gehört. projectId ist nur zu lesen: Es steht in der Antwort von GET /v1/listings/{externalListingId}, bei einem Inserat ohne Projekt fehlt es. GET /v1/projects/{externalProjectId} nennt die Einheiten in assignedListings (ein Mitglied von uns, nicht von OpenImmo). Ein Projekt hat höchstens 1000 Einheiten, so bleiben diese Liste und das Projekt in jedem Ereignis begrenzt: Ein Anlegen oder Zuordnen, das darüber hinausginge, ist 409 project_unit_limit_exceeded und ändert nichts. Die Einheitsnummer ist data.location.unit des Inserats und im Projekt eindeutig, Groß- und Kleinschreibung zählen nicht. Eine angelegte Einheit führt die Adresszeile ihres Projekts.
Einheiten anlegen
POST /v1/projects/{externalProjectId}/units legt bis zu 500 Einheiten in einem Aufruf an. Der Aufruf gilt ganz oder gar nicht: Wird auch nur eine Einheit abgelehnt, entsteht keine, und errors nennt jede abgelehnte mit ihrer Stelle im Rumpf. Die Einheit übernimmt Adresse, Texte, Energiedaten und Provision vom Projekt; ändern lässt sie sich danach mit den Operationen der Inserate. Anlegen veröffentlicht nichts.
curl -X POST "https://api.athaus.ai/v1/projects/PRJ-7/units" \
-H "Authorization: Bearer ath_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"units": [
{ "externalListingId": "PRJ-7-WE-1", "unit": "WE 1", "building": "A", "floor": 1, "rooms": 3, "livingSpace": 78.5, "price": 429000 },
{ "externalListingId": "PRJ-7-WE-2", "unit": "WE 2", "building": "A", "floor": 2, "rooms": 2, "livingSpace": 54, "price": 319000, "status": "option" }
]
}'Die Antwort ist 202 mit einer Quittung, die listings in der Reihenfolge des Rumpfs nennt. Diese Mitglieder einer Einheit sind von uns, nicht von OpenImmo:
| Mitglied | Bedeutung |
|---|---|
unit | Pflicht, die Einheitsnummer, bis 40 Zeichen |
externalListingId | deine Referenz des Inserats, wie metadata.source.offererMarketingKey |
building, floor, rooms, livingSpace, price | Haus, Etage, Zimmer, Wohnfläche in m², Preis in Euro (bei Miete die Kaltmiete im Monat) |
status | free (ohne Angabe), option, reserved, sold oder rented |
Was abgelehnt wird, und womit:
| Fall | Antwort |
|---|---|
| Einheitsnummer im Projekt schon vergeben | 409 unit_already_exists, errors nennt units[n].unit |
| Einheitsnummer im Rumpf doppelt | 400, errors nennt die zweite Stelle |
| Referenz gehört schon einem Inserat | 409 reference_already_exists, errors nennt units[n].externalListingId |
Stand passt nicht zur Vermarktungsart (sold im Mietprojekt, rented im Kaufprojekt) | 409 unit_status_invalid |
| Mehr Einheiten, als der Tarif Inserate erlaubt | 403 plan_required |
| mehr als 500 Einheiten | 400 |
| das Projekt hätte mehr als 1000 Einheiten | 409 project_unit_limit_exceeded |
Eine Wiederholung mit demselben Idempotency-Key liefert die erste Antwort noch einmal. Dieselben Einheiten mit einem neuen Key legen kein zweites Set an: Der Aufruf antwortet 409 (reference_already_exists, wenn die Einheiten Referenzen nennen, sonst unit_already_exists), und errors nennt die vorhandenen Einheiten.
Zuordnen und lösen
POST /v1/projects/{externalProjectId}/assign macht vorhandene Inserate zu Einheiten, bis zu 500 ganz oder gar nicht. Der Rumpf ist { "externalListingIds": [...] }. Jedes Inserat behält seine Daten; seine data.location.unit ist die Einheitsnummer, muss gesetzt und im Projekt eindeutig sein. Ein Inserat ohne Einheitsnummer ist 400, eine vergebene Nummer 409 unit_already_exists, jeweils mit externalListingIds[n] in errors. Eine Einheit eines anderen Projekts wird abgelehnt (400): Löse sie dort zuerst mit unassign. Passt der Einheitenstand eines Inserats nicht zum Projekt (eine gelöste sold-Einheit in ein Mietprojekt), ist es 409 unit_status_invalid. Ein Inserat, das schon Einheit dieses Projekts ist, bleibt, wie es ist; eine Wiederholung ändert nichts. Hätte das Projekt danach mehr als 1000 Einheiten, ist es 409 project_unit_limit_exceeded.
POST /v1/projects/{externalProjectId}/unassign löst Einheiten wieder: Sie bleiben als gewöhnliche Inserate mit allen Daten und tragen den Adressschlüssel ihrer eigenen Anschrift. Hält ein anderes Inserat diese Anschrift, ist es 409 address_already_exists. Das Inserat behält seinen Zustand: Eine reservierte oder verkaufte Einheit bleibt reserviert oder abgeschlossen, ein pausiertes bleibt pausiert; unit.status_updated kommt nicht, weil das Inserat keine Einheit mehr ist. Ein Inserat, das keine Einheit dieses Projekts ist, ist 400.
Beide Operationen antworten 202 mit einer Quittung, die die listings nennt, und senden project.updated.
Stand einer Einheit
POST /v1/listings/{externalListingId}/unit-status setzt den Stand einer Einheit, wie die Knöpfe der Einheitenliste in der App. Der Rumpf ist { "status": "reserved" }; die Antwort ist 200 mit dem Inserat. Jeder Stand außer free nimmt ein laufendes Inserat vom Markt (status wird paused); reserved, sold und rented setzen auch den Zustand reserved oder closed des Inserats. Derselbe Stand noch einmal ändert nichts. Ein Inserat, das keine Einheit ist, ist 409 listing_not_unit; ein Stand, der nicht zum Projekt passt, 409 unit_status_invalid. Es braucht write auf listings.
Löschen
DELETE /v1/projects/{externalProjectId} entfernt ein Projekt ohne Einheiten und antwortet 202 mit einer Quittung; If-Match gilt wie bei PUT. Hat das Projekt Einheiten, ist es 409 project_not_empty: Löse sie mit unassign oder lösche ihre Inserate zuerst. Die Inserate eines Projekts verschwinden nie mit ihm.
Ereignisse
project.created und project.updated sind Ereignisse und Webhooks. data.object ist das Projekt, wie GET es liefert, mit id, projectId und externalProjectId obenauf. Ein entferntes Projekt ist { object: "project", id, deleted: true }. Ein Key sieht sie mit read auf projects.
unit.status_updated kommt, wenn sich der Stand einer Einheit ändert. data.object ist die Einheit: { object: "unit", id, externalListingId, projectId, externalProjectId, unit, status, previousStatus }, mit der listingId als id. So erkennt ein Empfänger eine Einheit an der Art des Ereignisses und am projectId, das auch das Inserat beim Lesen trägt; ein Inserat ohne Projekt löst dieses Ereignis nie aus.
Testmodus
Das Testbüro hat ein erfundenes Beispielprojekt, TEST-PROJEKT-1, mit drei Einheiten (TEST-PROJEKT-1-WE-1 bis -WE-3). POST /v1/test/reset entfernt die Projekte des Testbüros samt ihren Einheiten und stellt das Beispielprojekt wieder her. Ein Test-Key veröffentlicht nie: Die Einheiten laufen in keinem Portal und auf keiner öffentlichen Neubauseite.
Weiter lesen
REST-API: Inserate in der Form von OpenImmo 2.0
Inserate lesen und schreiben in der Form von OpenImmo 2.0. Zwei Ids, Entwürfe, Quittungen, Hinweise und jedes Mitglied eines Inserats.
REST-API: Schreiben und Idempotenz
Inserate und Kontakte anlegen, ändern und löschen. Merge Patch, Idempotency-Key für sichere Wiederholungen, ETag und If-Match gegen Überschreiben.
REST-API Referenz
Jede Operation von /v1 mit Parametern, Antwort und Beispiel, aus dem Vertrag der API erzeugt.