# REST-API: Projekte

Adresse: https://docs.athaus.ai/api/v1/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.

Typ: Referenz
Zuletzt aktualisiert: 2026-11-17

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](https://www.openimmo.de). 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 [#two-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` [#right]

`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 [#writing]

| 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 [#members]

Die Mitglieder eines Projekts stehen einmal auf der [Seite der Inseratsmitglieder](/api/v1/referenz#projects). 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 [#own]

| 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 [#units]

Eine Einheit ist ein Inserat mit einem Projekt, keine zweite Ressource. Sie hat alle Operationen und Mitglieder eines [Inserats](/api/v1/inserate), 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 [#create-units]

`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.

```bash
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 [#assign]

`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 [#unit-status]

`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]

`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 [#events]

`project.created` und `project.updated` sind [Ereignisse](/api/v1/ereignisse) und [Webhooks](/api/v1/webhooks#events). `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 [#test]

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.
