Zum Inhalt springen

Bald geht's los: Suche & Bewerbung starten am 30. September 2026. Richte schon jetzt dein Profil ein.

WOHNO

API-Changelog

Chronologische, additive Historie der WOHNO-REST-API: jede neue Ressource, jeder Endpoint und Scope, Welle für Welle.

Dieses Changelog verfolgt jede Änderung an der WOHNO-REST-API (/api/v1). Die API ist als v1 versioniert und entwickelt sich additiv weiter — neue Felder, Endpoints und Scopes brechen niemals bestehende Integrationen. Die Regeln dahinter (Deprecation-Fenster, DTO-Versionierung) findest du in der Versionierung & Deprecation-Policy.

Jeder Eintrag listet das Datum, die Welle, mit der er ausgeliefert wurde, die neuen Endpoints und die neuen Scopes. Sofern nicht anders vermerkt, ist jede Änderung rein additiv.

Verfügbarkeit: Jede Operation unten ist allgemein verfügbar (GA) und in der API-Referenz sichtbar — kein Feature-Flag gatet die Daten-Fläche der API. Zwei Freischalt-Gates stehen ihr aber vorgelagert: (1) das Erstellen von API-Keys (POST /api/v1/api-keys) ist in Closed Beta — solange deine Organisation dafür nicht freigeschaltet ist, liefert die Key-Erstellung 403 BETA_NOT_ENABLED, und sie erfordert zusätzlich einen kostenpflichtigen Plan (siehe Quickstart); (2) vor dem öffentlichen Marktplatz-Launch liefern die marktplatz-bezogenen Daten-Endpoints (Listings-Reads, Discovery, Applications, Termin-Anlegen/-Ändern/-Stornieren/-Buchen, Matching) 403 LAUNCH_PENDING. Die übrigen nicht-marktplatz-bezogenen Endpoints (Webhooks, Members, Usage, Analytics, WBS, Listings-Write sowie das Lesen und Löschen der eigenen Keys) sind schon jetzt verfügbar. Ressourcenspezifische Gates gelten weiterhin, wo vermerkt (Secret-Key-Scopes, das Applications-Consent-Gate, der Premium-Plan für Matching).

2026-08 — Booking-AuthZ: signierter Booking-Intent

Breaking (nur Publishable Keys)

  • POST /api/v1/appointments/{id}/book: Publishable (pk_) Keys können nicht mehr per Body-user_id buchen. Statt der unauthentifizierten User-ID ist jetzt ein von WOHNO ausgestelltes, signiertes booking_intent Pflicht (an die eingeloggte Seeker-Session und genau diesen Slot gebunden, TTL 10 Minuten, single-use — best-effort; bei Redis-Ausfall fail-open, Primärschutz bleiben Signatur + TTL + aid-Bind). Ohne validen Intent → 403 BOOKING_INTENT_REQUIRED; ungültig/abgelaufen/wiederverwendet → 403 BOOKING_INTENT_INVALID; Intent- Prüfung serverseitig nicht konfiguriert → 503 BOOKING_INTENT_UNAVAILABLE.
  • Secret (sk_) Keys: Kern-Flow unverändert, zwei Detail-Änderungen. Server-to-Server-Buchung per user_id für Bewerber der eigenen Organisation funktioniert unverändert (Applicant-Gate + Audit-Log bleiben aktiv). Neu: (1) der Validierungs-Fehlertext bei fehlendem user_id lautet jetzt „Required for secret keys without booking_intent"; (2) ein mitgesendetes booking_intent-Feld wird jetzt ausgewertet und gewinnt über user_id (vorher wurde ein unbekanntes Feld ignoriert).
  • Die 200-Antwort für pk-Buchungen liefert für notes jetzt null (interne Vermieter-Notizen werden nicht mehr ausgeliefert; das Feld bleibt für Schema-Stabilität vorhanden); sk-Antworten sind byte-identisch. Hinweis: die Lese-Endpunkte (GET Liste/Detail mit appointments:read) liefern notes derzeit unverändert — eine Härtung des pk-Lese-Pfads folgt separat.

Hinweise

  • Die Intent-Ausstellung ist first-party-only (eingeloggte WOHNO-Session). Eine Standalone-Ausstellung für Dritt-Origins existiert noch nicht — der pk-Booking-Pfad ist bis dahin faktisch inaktiv (Roadmap: User-Authentifizierung auf der REST-API).
  • Sicherheitsbegründete Ausnahme von der Nur-additiv-Regel (schließt die dokumentierte Impersonations-Lücke P55-04). Zum Zeitpunkt der Änderung gab es keinen bekannten pk-Konsumenten (Closed Beta); der Breaking-Entscheid liegt sichtbar beim Maintainer am Merge.

2026-06 — Owner-Zuweisung für Inserate

Breaking

  • Quota-Enforcement ist jetzt GA (default-on, kein Flag mehr). Bisher lief das Requests-Kontingent nur im Tracking-Modus (informative X-Quota-*-Header, kein Blocken). Ab dieser Welle erzwingt withApiAuth das Plan-Monatslimit unbedingt: Überschreitung liefert einen harten 429 QUOTA_EXCEEDED (mit Retry-After-Header); ebenso werden webhook_deliveries über Limit blockiert (Delivery failed, Event webhook.failed mit error: "quota_exceeded"). Nur erfolgreiche Requests kosten — ein 4xx/5xx-Response erstattet die verbrauchte Einheit automatisch. Bei nicht erreichbarem Quota-Backend (Redis) läuft der Request weiterhin durch (fail-open). embed_impressions bleiben reines Tracking (kein 429). Details siehe Quotas.

Hinzugefügt

  • POST /api/v1/listings akzeptiert ein optionales owner_email-Feld. Es weist das neue Inserat diesem Team-Mitglied zu (statt dem Ersteller des API-Keys), sofern die E-Mail zu einem Mitglied derselben Organisation gehört (Rolle owner, admin oder member). Wirkt nur beim Create; wird bei external_ref-Upsert und PATCH ignoriert.

Hinweise

  • Rein additiv — ohne owner_email bleibt das bisherige Verhalten (der Key-Ersteller wird Owner).
  • Eine unbekannte E-Mail und ein Nicht-Mitglied liefern dieselbe 403 FORBIDDEN — das Feld kann nicht zur Enumeration von WOHNO-Konten genutzt werden.
  • Verwendung siehe Inserate aus deinem CRM synchronisieren.

2026-05 — Analytics & Usage (Welle 5)

Hinzugefügt

  • GET /api/v1/usage — Quota- und Usage-Self-Service für die eigene Organisation. Scope usage:read (nur Secret Keys). GA (nur eigene Daten).
  • GET /api/v1/analytics/listings/{id} — aggregierte Inserats-Analytics (org-isoliert, keine PII). Scope analytics:read (nur Secret Keys). GA.

Hinweise

  • Beide Endpoints sind ausschließlich Secret-Key (sk_) und von Publishable Keys ausgeschlossen.
  • Additiv: keine Änderungen an bestehenden Endpoints oder Antwort-Formen.

2026-04 — Utility & Discovery (Welle 4)

Hinzugefügt

  • POST /api/v1/wbs/check — zustandsloser WBS-(Wohnberechtigungsschein-) Eignungs-Schnellcheck. Scope wbs:check, Publishable-Key erlaubt (browser-sicher). GA.
  • GET /api/v1/discovery/listings — diskrete, organisationsübergreifende Inserats-Discovery mit ETag-Unterstützung. Scope discovery:read, Publishable-Key erlaubt. GA — liefert 403 LAUNCH_PENDING bis zum öffentlichen Marktplatz-Launch.
  • POST /api/v1/matching/score — Matching-Score as a Service (Premium). Scope matching:score (nur Secret Keys), nur aggregierte Ausgabe. GA — liefert 403 LAUNCH_PENDING bis zum öffentlichen Marktplatz-Launch.

Hinweise

  • Nur additiv. wbs:check und discovery:read sind die ersten Publishable- (pk_-)Scopes seit den Read-Endpoints; matching:score bleibt sk_-only.

2026-03 — Applications / Bewerbungen (Welle 3)

Status: GA · PII-kritisch. Diese Ressource verarbeitet Bewerber-PII. Sie ist allgemein verfügbar und in der öffentlichen Referenz, aber der Zugang ist consent-gegatet: der Consent api_applicant_access_enabled einer Organisation muss gesetzt sein, sonst scheitert jeder Call fail-closed mit 403 CONSENT_REQUIRED. Vor dem öffentlichen Marktplatz-Launch liefern diese Endpoints zusätzlich 403 LAUNCH_PENDING.

Hinzugefügt

  • GET /api/v1/listings/{id}/applications — Bewerbungen für ein Inserat auflisten. Scope applications:read (nur Secret Keys).
  • GET /api/v1/applications/{id} — eine einzelne Bewerbung lesen (reduziertes, whitelistetes DTO). Scope applications:read (nur Secret Keys).
  • PATCH /api/v1/applications/{id} — Bewerbungs-Status / -Tags aktualisieren. Scope applications:write (nur Secret Keys).

Hinweise

  • Nur Secret-Key (sk_); der Zugang ist consent-gegatet (403 CONSENT_REQUIRED, wenn api_applicant_access_enabled nicht gesetzt ist).
  • Reduziertes ApplicationPublicDto und Audit-Logging pro Lesezugriff schützen die Bewerber-PII.
  • Additiv: keine Änderungen an bestehenden Endpoints.

2026-02 — Listings-Write & Syndication (Welle 2)

Hinzugefügt

  • POST /api/v1/listings — Inserat erstellen / upserten (unterstützt external_ref und Idempotency-Key). Scope listings:write (nur Secret Keys).
  • PATCH /api/v1/listings/{id} — ein Inserat aktualisieren. Scope listings:write.
  • DELETE /api/v1/listings/{id} — ein Inserat löschen. Scope listings:delete.
  • POST / DELETE /api/v1/listings/{id}/images — Bild-Upload und -Entfernung per Signed-URL. Scope listings:write.

Hinweise

  • Die zuvor nur lesende Listings-Ressource erhielt Schreiboperationen — additiv, die bestehenden GET-Endpoints und der listings:read-Scope bleiben unverändert.
  • Write-Endpoints akzeptieren einen Idempotency-Key-Header, sodass wiederholte Bulk-Writes sicher sind. GA.

2026-01 — Webhooks, API-Keys & Members (Welle 1)

Hinzugefügt

  • POST /api/v1/webhooks, GET/PATCH/DELETE /api/v1/webhooks/{id} — Webhook-Subscriptions verwalten (die Delivery-Pipeline, HMAC-Signierung und Event-Typen existierten bereits). Scopes webhooks:read / webhooks:write.
  • GET /api/v1/webhooks/{id}/deliveries und POST .../deliveries/{deliveryId}/redeliver — Delivery-Log + Re-Delivery.
  • GET/POST /api/v1/api-keys, GET/DELETE /api/v1/api-keys/{id} — die eigenen API-Keys programmatisch verwalten. Scopes api-keys:read / api-keys:write.
  • GET/POST /api/v1/organizations/{id}/members und PATCH/DELETE /api/v1/organizations/{id}/members/{userId} — Team-Mitglieder verwalten. Scopes members:read / members:write.

Hinweise

  • Alle Endpoints der Welle 1 sind ausschließlich Secret-Key (sk_) und von Publishable Keys ausgeschlossen. GA.
  • Diese Scopes (webhooks:*, api-keys:*, members:*) waren zuvor definiert, hatten aber keine Endpoints; diese Welle hat sie aktiviert. Nur additiv.