Immobilienobjekte

Überblick

Immobilienobjekte, die Benutzer verwalten können. Jedes Objekt hat Name, Beschreibung, Farbe, Typ und Adresse, integriert mit Nova Poshta API.

Land

Jedes Objekt ist mit einem Land verknüpft. Dies bestimmt Adressformat, Standardwährung und andere regionale Einstellungen.

• Land ist ein Pflichtfeld beim Erstellen oder Bearbeiten eines Objekts
• Adressformat hängt vom gewählten Land ab (Nova Poshta API für Ukraine)
• Land wird in Objektkarten, Listen und Detailseiten angezeigt

Beispielantwort

{
  "id": 1,
  "name": "My Apartment",
  "country": {
    "id": 1,
    "code": "UA",
    "name_key": "country.ua"
  },
  "property_type": {...},
  "address": {...}
}

Benutzerrollen

Jedes Objekt kann mehrere Benutzer mit verschiedenen Rollen haben:

Benutzerverwaltung

Der Objekteigentümer (PROPERTY_LANDLORD) kann andere Benutzer hinzufügen und entfernen:

• Benutzer hinzufügen: Suche nach E-Mail oder Telefon. Ergebnis wird nur angezeigt, wenn genau 1 Benutzer gefunden wurde (Datenschutz).
• Eine Rolle pro Objekt: Jeder Benutzer kann nur eine Rolle innerhalb eines Objekts haben.
• PROPERTY_LANDLORD kann nicht manuell hinzugefügt werden: Diese Rolle wird automatisch bei Objekterstellung zugewiesen.
• Eigentümer kann nicht gelöscht werden: Zum Ändern des Eigentümers ist Administration erforderlich.

REST API

Alle API-Endpunkte erfordern JWT-Authentifizierung.

Service-Layer-Hinweis

Objekte-API

GET    /api/v1/properties          # List user's properties
POST   /api/v1/properties          # Create property (user becomes PROPERTY_LANDLORD)
GET    /api/v1/properties/{id}     # Property details
PUT    /api/v1/properties/{id}     # Update (LANDLORD/LANDLORD_AGENT)
DELETE /api/v1/properties/{id}     # Delete (LANDLORD only)

Objektbenutzer-API

GET    /api/v1/properties/{id}/users              # List property users
POST   /api/v1/properties/{id}/users              # Add user
DELETE /api/v1/properties/{id}/users/{userId}     # Remove user
GET    /api/v1/properties/{id}/search-user?q=...  # Search user
GET    /api/v1/properties/{id}/available-roles    # Available roles

Beschreibungen (Übersetzungen) API

GET    /api/v1/properties/{id}/descriptions              # List description translations
POST   /api/v1/properties/{id}/descriptions              # Create/update translation (locale + description)
POST   /api/v1/properties/{id}/descriptions/translate    # AI translate to target locale

KI-Funktionen API

POST   /api/v1/properties/generate-description    # Generate description via Grok AI (from form data)
POST   /api/v1/geo/geocode                        # Geocode address to lat/lng (public)

Nova Poshta Adressen-API

GET /api/v1/nova-poshta/areas                    # List areas (oblasts)
GET /api/v1/nova-poshta/cities?area_ref=...      # Cities in area
GET /api/v1/nova-poshta/streets?city_ref=...&search=... # Search streets (min 1 char)
GET /api/v1/nova-poshta/search-by-zip?zip=...    # Find city by postal code (5 digits)

Beispiel: Benutzer hinzufügen

POST /api/v1/properties/019fe131-6b2a-7c41-9d8e-3f5a2c7b1e04/users
Content-Type: application/json
Authorization: Bearer <token>

{
  "user_id": "019fe131-7a3d-7e52-8c19-4b6d3e9f2a15",
  "role_id": 12
}

Beispielantwort

{
  "message": "User added successfully",
  "data": {
    "id": 3,
    "user_id": "019fe131-7a3d-7e52-8c19-4b6d3e9f2a15",
    "email": "[email protected]",
    "name": "John Smith",
    "role": {
      "id": 12,
      "code": "PROPERTY_TENANT",
      "name_key": "role.property_tenant"
    },
    "created_at": "2026-01-05T14:30:00+00:00"
  }
}

Beispiel: Objektantwort

{
  "id": 1,
  "name": "My Apartment",
  "description": "Apartment in the city center",
  "color": "var(--color-primary)",
  "property_type": {
    "id": 2,
    "code": "APARTMENT",
    "name_key": "property_type.apartment.name"
  },
  "address": {
    "area_ref": "71508128-9b87-11de-822f-000c2965ae0e",
    "area_name": "Kyiv Oblast",
    "city_ref": "e221d627-391c-11dd-90d9-001a92567626",
    "city_name": "Kyiv",
    "street_ref": "18e2ffc8-d68d-11e3-9937-003048d2b473",
    "street_name": "Khreschatyk",
    "building_number": "1A",
    "apartment_number": "42",
    "full_address": "Kyiv Oblast, Kyiv, Khreschatyk, bld. 1A, apt. 42"
  },
  "living_area": "45.50",
  "total_area": "57.80",
  "latitude": "50.4500336",
  "longitude": "30.5241361",
  "descriptions": [
    {"locale": "en", "description": "<p>Spacious apartment in the city center...</p>"},
    {"locale": "de", "description": "<p>Geräumige Wohnung im Stadtzentrum...</p>"}
  ],
  "user_role": "PROPERTY_LANDLORD",
  "users": [
    {
      "id": 1,
      "user_id": "019fe131-7a3d-7e52-8c19-4b6d3e9f2a15",
      "email": "[email protected]",
      "name": "Property Owner",
      "role": {"id": 10, "code": "PROPERTY_LANDLORD", "name_key": "role.property_landlord"},
      "created_at": "2026-01-05T12:00:00+00:00"
    }
  ],
  "created_at": "2026-01-05T12:00:00+00:00",
  "updated_at": "2026-01-05T14:30:00+00:00"
}

Mehrsprachige Beschreibungen

Objektbeschreibungen können in mehrere Sprachen übersetzt werden. Die Hauptbeschreibung wird in Property gespeichert, Übersetzungen in PropertyDescription.

• Entität: PropertyDescription (property_id + locale + HTML description)
• Unterstützte Sprachen: uk, en, ru, pl, de
• KI-Übersetzung: Grok AI übersetzt HTML-Beschreibung unter Beibehaltung der Tags. Verfügbar über API und im Formular.
• Formular-UX: Übersetzungseditoren erscheinen wenn die Hauptbeschreibung 20+ Zeichen hat. Jede Sprache hat einen WYSIWYG-Editor + KI-Übersetzungsbutton.

Beispiel Übersetzung speichern

POST /api/v1/properties/1/descriptions
Content-Type: application/json
Authorization: Bearer <token>

{
  "locale": "en",
  "description": "<p>Spacious apartment in the city center with a great view.</p>"
}

Beispiel KI-Übersetzung

POST /api/v1/properties/1/descriptions/translate
Content-Type: application/json
Authorization: Bearer <token>

{
  "target_locale": "de",
  "source_html": "<p>Простора квартира в центрі міста.</p>"
}

// Response:
{
  "html": "<p>Geräumige Wohnung im Stadtzentrum.</p>",
  "locale": "de"
}

Objektcharakteristiken

Jedes Immobilienobjekt kann zusätzliche Charakteristiken haben: Anzahl der Zimmer, Etage, Gebäudetyp usw. Diese Werte werden in PropertyDataValue gespeichert und mit PropertyDataType verknüpft.

Datenstruktur

• PropertyDataType: Definiert Charakteristiktyp (Code, Name, Datentyp, Gruppe, Maßeinheit, Icon)
• PropertyDataValue: Speichert tatsächlichen Wert für Kombination Objekt + Datentyp

Datentypgruppen

Wertetypen

Objektcharakteristiken-API

GET    /api/v1/properties/{id}/data-values           # List all values
GET    /api/v1/properties/{id}/data-values/grouped    # Values grouped by category
GET    /api/v1/properties/{id}/data-values/{code}     # Get single value by code
POST   /api/v1/properties/{id}/data-values            # Set/update a value
PUT    /api/v1/properties/{id}/data-values/batch      # Batch update multiple values
DELETE /api/v1/properties/{id}/data-values/{code}     # Delete a value

Datentypen-API (Referenz)

GET /api/v1/property-data-types                  # List all active types
GET /api/v1/property-data-types/grouped          # Types grouped by category
GET /api/v1/property-data-types/{code}           # Get type by code
GET /api/v1/property-data-types/meta/groups      # List available groups
GET /api/v1/property-data-types/meta/data-types  # List available data types

Beispiel: Wert festlegen

POST /api/v1/properties/1/data-values
Content-Type: application/json
Authorization: Bearer <token>

{
  "code": "ROOM_COUNT",
  "value": "3"
}

Beispielantwort

{
  "message": "Value set successfully",
  "data": {
    "id": 42,
    "code": "ROOM_COUNT",
    "name_key": "property_data_type.room_count.name",
    "data_type": "int",
    "group_code": "apartment",
    "value": "3",
    "formatted_value": "3",
    "unit": null,
    "icon_url": "https://s3.example.com/property_data_type/room_count.svg",
    "created_at": "2026-01-17T12:00:00",
    "updated_at": "2026-01-17T12:00:00"
  }
}

Beispiel: Stapelaktualisierung

PUT /api/v1/properties/1/data-values/batch
Content-Type: application/json
Authorization: Bearer <token>

{
  "values": {
    "ROOM_COUNT": "3",
    "FLOOR_NUMBER": "5",
    "HAS_BALCONY": "1",
    "BUILDING_TYPE": "brick",
    "WINDOW_VIEW": "park",
    "APARTMENT_CONDITION": ""
  }
}

Beispielantwort

{
  "message": "Values updated successfully",
  "updated": 5,
  "removed": 1,
  "errors": []
}

UI-Integration

Objektcharakteristiken werden angezeigt in:

• Objektformular: Ausklappbarer Bereich mit gruppierten Feldern zur Werteingabe
• Objektansichtsseite: Gruppierte Anzeige aller festgelegten Werte mit Icons
• Objektliste: Vorschau der Icons der ersten 8 Werte in Objektkarten

Validierung

Werte werden entsprechend ihrem Datentyp validiert:

• bool: Muss 0, 1, true, false, yes oder no sein
• int: Muss eine Ganzzahl im definierten min/max-Bereich sein (z.B. ROOM_COUNT: 1-30)
• float: Muss eine Zahl im definierten min/max-Bereich sein (z.B. CEILING_HEIGHT: 1.5-10.0)
• string: Muss erlaubten Werten entsprechen, wenn definiert (z.B. BUILDING_TYPE: panel, brick, monolith usw.)

Swagger / OpenAPI

Vollständige API-Dokumentation ist in Swagger UI verfügbar: /api/v1/doc

• 03. Properties / Data Values - CRUD API für Objektcharakteristiken
• 05. References / Property Data Types - Referenzdaten der Charakteristiktypen