# REST-API: Schreiben und Idempotenz

Adresse: https://docs.athaus.ai/api/v1/schreiben

> Inserate und Kontakte anlegen, ändern und löschen. Merge Patch, Idempotency-Key für sichere Wiederholungen, ETag und If-Match gegen Überschreiben.

Typ: Anleitung
Zuletzt aktualisiert: 2026-11-16

Mit `POST`, `PATCH`, `PUT` und `DELETE` schreibt dein System `listings` und `contacts` im Büro. Der API-Key braucht den Scope `propose` und die Stufe `write` auf der Ressource ([Scopes und Stufen](/api/v1/anmeldung#scopes)). Ein Key mit nur dem Scope `read` bekommt `403` und `insufficient_permissions`; es wird nichts geschrieben.

Was du schreibst, wird im Büro und in der Historie des Eintrags unter dem Namen des Keys festgehalten. Eine Änderung über die API fließt nie in ein angebundenes CRM zurück.

## Anlegen und ändern [#anlegen-und-ändern]

* `POST` legt an. Ein Kontakt antwortet `201` mit dem Objekt. Ein Inserat antwortet `202` mit einer Quittung ([Inserate](/api/v1/inserate#ein-inserat-anlegen)). Ein POST ändert nie, was es schon gibt: Eine E-Mail-Adresse, eine Adresse samt Wohnung oder eine Referenz, die das Büro schon hat, ist `409`.
* `PATCH` ändert als Merge Patch (RFC 7396): Ein fehlendes Mitglied bleibt, `null` leert es, ein Wert ersetzt es, eine Liste ersetzt die Liste. Was sich nicht leeren lässt, nimmt kein `null`.
* `PUT /v1/listings/{externalListingId}` verlangt einen vollständigen Rumpf und ändert das Inserat dann wie `PATCH`: Was der Rumpf nicht nennt, bleibt, `null` leert es. Eine unbekannte Id ist `404`; mit `createIfMissing=true` legt `PUT` sie an.
* Ein Mitglied, das die API nicht kennt, ist `400`, und `errors[].name` nennt es. Nichts wird stillschweigend verworfen.
* Der Rumpf ist JSON (`Content-Type: application/json`, sonst `415`) und höchstens 512 KB (`413`). Die eine Ausnahme ist `POST /v1/medias`: Dort ist der Rumpf die Datei, höchstens 25 MB ([Fotos und Dokumente](/api/v1/inserate#media)).

## Löschen [#löschen]

Ein `DELETE` auf einen Kontakt antwortet `200` mit `{ "object": "contact", "id": "...", "deleted": true }`. Ein `DELETE` auf ein Inserat antwortet `202` mit einer Quittung. Ein Inserat mit anstehenden Besichtigungen ist `409` (`upcoming_viewings_exist`): Löschen würde die Besichtigungen absagen, und das verlässt das Haus. Auch ein veröffentlichtes Inserat und ein laufender Maklervertrag halten das Löschen auf (`listing_active`, `brokerage_agreement_active`).

## Wiederholen, ohne doppelt zu schreiben [#wiederholen-ohne-doppelt-zu-schreiben]

Schicke bei jedem `POST` den Kopf `Idempotency-Key` mit einem Zufallswert (zum Beispiel eine UUID, 1 bis 255 Zeichen). `PUT` und `DELETE` nehmen ihn auch.

| Fall                                                       | Antwort                                                                |
| ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| Gleicher Key, gleicher Rumpf, die erste Anfrage ist fertig | dieselbe Antwort noch einmal, mit dem Kopf `Idempotent-Replayed: true` |
| Gleicher Key, anderer Rumpf                                | `422`, `idempotency_key_reused`                                        |
| Die erste Anfrage läuft noch                               | `409`, `idempotency_key_in_use`, mit `Retry-After`                     |
| Die erste Anfrage brach mitten in der Arbeit ab            | `409`, `idempotency_outcome_unknown`                                   |

Gespeichert werden nur Erfolge, 24 Stunden lang, getrennt nach API-Key und Operation. Nach einem Fehler ist der Key wieder frei. Bei `idempotency_outcome_unknown` weiß niemand, ob etwas geschrieben wurde: Sieh nach, was da ist, und wiederhole mit einem neuen Key.

Der Kopf ist hier optional. Bei Operationen, die das Büro verlassen, ist er Pflicht ([Was das Büro verlässt](/api/v1/hinausgehen)).

## Nicht überschreiben: ETag und If-Match [#bedingt-schreiben]

Eine Person kann in der App etwas ändern, während dein System noch mit dem alten Stand arbeitet. Mit `If-Match` ändert oder löscht dein System nur, wenn der Stand noch der ist, den es gelesen hat.

* Jede einzelne Ressource trägt den Kopf `ETag`: bei `GET` und in der Antwort auf `POST`, `PATCH` und `PUT`. Er ändert sich mit jeder Änderung, die die API zeigt, auch mit einer, die eine Person in der App machte. Listen haben keinen. Behandle den Wert als undurchsichtig und schick ihn unverändert zurück, mit seinen Anführungszeichen.
* `PATCH`, `PUT` und `DELETE` nehmen `If-Match`. Steht der aktuelle `ETag` in der Liste (mehrere, durch Kommas getrennt), läuft die Änderung. Sonst antwortet die API `412` mit `precondition_failed`, und es wird nichts geschrieben. `If-Match: *` heißt: nur wenn das Objekt existiert. Ein schwacher Wert (`W/"..."`) passt nie.
* Prüfung und Änderung sind ein Schritt: Zwei Anfragen mit demselben `ETag` zur selben Zeit ändern nicht beide, eine bekommt `412`.
* Der Kopf ist optional. Ohne ihn schreibt die API ohne Prüfung.
* Bei `PUT` auf ein Inserat ändert `If-Match` nur. `If-None-Match: *` legt nur an (`412`, wenn es schon existiert).
* Bei `GET` antwortet `If-None-Match` mit dem aktuellen `ETag` mit `304` ohne Rumpf. Die Anfrage zählt gegen die Grenze fürs Lesen.

```bash
# 1. Lesen und den ETag merken
curl -si https://api.athaus.ai/v1/contacts/$ID -H "Authorization: Bearer $KEY" | grep -i '^etag'
# etag: "V1StGXR8_Z5jdHi6B-myTg"
```

```bash
# 2. Nur ändern, wenn sich nichts geändert hat
curl -s -X PATCH https://api.athaus.ai/v1/contacts/$ID \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H 'If-Match: "V1StGXR8_Z5jdHi6B-myTg"' \
  -d '{"phone": null, "city": "Potsdam"}'
```

Hat sich der Stand inzwischen geändert, antwortet die API:

```json
{
  "type": "https://docs.athaus.ai/en/api/errors#precondition_failed",
  "title": "The condition of the request (If-Match or If-None-Match) does not hold for the current state of the resource, and nothing was written. Read the resource again, apply your change to the new state, and retry with the new ETag.",
  "status": 412,
  "detail": "The resource has changed since you read it.",
  "instance": "req_0f3a9c2b7d4e41a8b6c15e9d3a7f2b04",
  "errorSource": "headers",
  "code": "precondition_failed"
}
```

Lies das Objekt neu, wende deine Änderung auf den neuen Stand an und wiederhole mit dem neuen `ETag`. Ein nicht lesbarer Kopf ist `400` mit `errorSource` `headers`.

## Grenzen [#grenzen]

Schreiben hat einen eigenen Eimer: 2 Anfragen pro Sekunde, ein Stoß von 60, getrennt vom Lesen ([Grenzen](/api/v1/limits)).
