Объекты недвижимости

Обзор

Объекты недвижимости, которыми пользователи могут управлять. Каждый объект имеет название, описание, цвет, тип и адрес, интегрированный с API Новая Почта.

Страна

Каждый объект привязан к стране. Это определяет формат адреса, валюту по умолчанию и другие региональные настройки.

• Страна является обязательным полем при создании или редактировании объекта
• Формат адреса зависит от выбранной страны (Nova Poshta API для Украины)
• Страна отображается в карточках объектов, списках и на страницах деталей

Пример ответа

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

Роли пользователей

Каждый объект может иметь несколько пользователей с разными ролями:

Управление пользователями

Владелец объекта (PROPERTY_LANDLORD) может добавлять и удалять других пользователей:

• Добавление пользователей: Поиск по email или телефону. Результат показывается только если найден ровно 1 пользователь (защита приватности).
• Одна роль на объект: Каждый пользователь может иметь только одну роль в рамках одного объекта.
• PROPERTY_LANDLORD нельзя добавить вручную: Эта роль назначается автоматически при создании объекта.
• Владельца нельзя удалить: Для смены владельца требуется администрирование.

REST API

Все API эндпоинты требуют JWT аутентификации.

Примечание уровня сервиса

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)

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

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

AI функции

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)

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)

Пример: Добавление пользователя

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
}

Пример ответа

{
  "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"
  }
}

Пример: Ответ объекта

{
  "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"
}

Мультиязычные описания

Описания объектов можно переводить на несколько языков. Основное описание хранится в Property, переводы — в PropertyDescription (один на язык).

• Сущность: PropertyDescription (property_id + locale + HTML description)
• Поддерживаемые языки: uk, en, ru, pl, de
• AI перевод: Grok AI переводит HTML-описание сохраняя теги. Доступно через API и в форме объекта.
• UX формы: Редакторы перевода появляются когда основное описание имеет 20+ символов. Каждый язык имеет WYSIWYG редактор + кнопку AI перевода.

Пример сохранения перевода

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>"
}

Пример AI перевода

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"
}

Характеристики объекта

Каждый объект недвижимости может иметь дополнительные характеристики: количество комнат, этаж, тип дома и т.д. Эти значения хранятся в PropertyDataValue и связаны с PropertyDataType.

Структура данных

• PropertyDataType: Определяет тип характеристики (код, название, тип данных, группа, единица измерения, иконка)
• PropertyDataValue: Хранит фактическое значение для комбинации объект + тип данных

Группы типов данных

Типы значений

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

API типов данных (справочник)

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

Пример: Установить значение

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

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

Пример ответа

{
  "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"
  }
}

Пример: Массовое обновление

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": ""
  }
}

Пример ответа

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

Интеграция в интерфейс

Характеристики объекта отображаются в:

• Форма объекта: Раскрывающаяся секция с группированными полями для ввода значений
• Страница просмотра объекта: Группированный вывод всех установленных значений с иконками
• Список объектов: Предпросмотр иконок первых 8 значений в карточках объектов

Валидация

Значения валидируются в соответствии с их типом данных:

• bool: Должно быть 0, 1, true, false, yes или no
• int: Должно быть целым числом в пределах определённого диапазона min/max (напр., ROOM_COUNT: 1-30)
• float: Должно быть числом в пределах определённого диапазона min/max (напр., CEILING_HEIGHT: 1.5-10.0)
• string: Должно соответствовать допустимым значениям, если они определены (напр., BUILDING_TYPE: panel, brick, monolith и т.д.)

Swagger / OpenAPI

Полная документация API доступна в Swagger UI: /api/v1/doc

• 03. Properties / Data Values - CRUD API характеристик объекта
• 05. References / Property Data Types - Справочные данные типов характеристик