AthausDoku

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.

OperationWas sie tut
GET /v1/projectsdie externen Ids der Projekte, neueste zuerst, seitenweise
GET /v1/projects/{externalProjectId}ein Projekt, mit einem ETag
POST /v1/projectslegt 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}/unitslegt bis zu 500 Einheiten an
POST /v1/projects/{externalProjectId}/assignmacht vorhandene Inserate zu Einheiten
POST /v1/projects/{externalProjectId}/unassignlöst Einheiten wieder aus dem Projekt
POST /v1/listings/{externalListingId}/unit-statussetzt den Stand einer Einheit

Zwei Ids

IdWessenWo
externalProjectIddeineim Pfad jedes Aufrufs, im Rumpf als metadata.source.offererMarketingKey
projectIdunserein 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.

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

WasWie bei Inseraten
Idempotency-Keyeine Wiederholung mit demselben Key und Rumpf liefert dieselbe Quittung und legt ein Projekt an
ETag und If-MatchGET trägt den Tag; PUT mit einem veralteten Tag antwortet 412
Seitenlimit, nextPageToken, updatedSince, neueste zuerst
FehlerProblem Details mit code und errors[].name, das das Mitglied nennt
Antwort eines Schreibens202 mit einer Quittung: requestId, projectId, externalProjectId, warnings
PUTfü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.headline ist der Name des Projekts und beim Anlegen Pflicht. description, area und features sind Beschreibung, Lagetext und Ausstattungstext.
  • data.location ist die Adresse, gelesen und geschrieben wie die Lage eines Inserats. Das Land ist immer Deutschland.
  • data.distributionType ist BUY oder RENT. BUY_RENT wird abgelehnt.
  • data.program.projectStatus ist der Bauabschnitt: CONSTRUCTION_START heißt im Bau, PROJECT_ENDED fertig.
  • data.deliveryDate ist die geplante Fertigstellung, bis 60 Zeichen.
  • data.units trägt Kennzahlen, die Athaus aus den Einheiten zählt: numberOfUnits, priceFrom, priceTo, livingSpaceFrom, livingSpaceTo, soldOutPercentage. Geschrieben wird nur die Käuferprovision: provisionType, provisionPercent und provisionIsVatIncluded.
  • data.estateType ist immer NEW_BUILD_PROJECT; NEW_HOME_PROJECT wird 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

MitgliedWoBedeutung
statusAnfrage und Antwortder Name eines Projektstatus des Büros, etwa Vertrieb; ohne ihn beginnt ein neues Projekt im ersten Status
projectIdAntwortdie Id, die Athaus dem Projekt gab
createdAt, updatedAtAntwortwann das Projekt angelegt und zuletzt geändert wurde
projectsin der Id-Listeeine Ü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:

MitgliedBedeutung
unitPflicht, die Einheitsnummer, bis 40 Zeichen
externalListingIddeine Referenz des Inserats, wie metadata.source.offererMarketingKey
building, floor, rooms, livingSpace, priceHaus, Etage, Zimmer, Wohnfläche in m², Preis in Euro (bei Miete die Kaltmiete im Monat)
statusfree (ohne Angabe), option, reserved, sold oder rented

Was abgelehnt wird, und womit:

FallAntwort
Einheitsnummer im Projekt schon vergeben409 unit_already_exists, errors nennt units[n].unit
Einheitsnummer im Rumpf doppelt400, errors nennt die zweite Stelle
Referenz gehört schon einem Inserat409 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 erlaubt403 plan_required
mehr als 500 Einheiten400
das Projekt hätte mehr als 1000 Einheiten409 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

Auf dieser Seite