Об'єкти нерухомості

Огляд

Об'єкти нерухомості, якими користувачі можуть керувати. Кожен об'єкт має назву, опис, колір, тип та адресу, інтегровану з 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 - Довідкові дані типів характеристик