Платежі

Огляд

Модуль платежів дозволяє реєструвати оплати за комунальні послуги та роботу обслуговуючого персоналу. Кожен платіж прив'язаний до об'єкта нерухомості та може мати прикріплену квитанцію.

Архітектура платежів

Платежі підтримують два типи нарахувань: комунальні витрати та оренду. Кожен платіж прив'язаний до одного типу.

Типи одержувачів

Платіж може бути адресований одному з двох типів одержувачів:

Конвертація валют

При перегляді платежу, якщо валюта платежу відрізняється від офіційної валюти країни об'єкта, сума автоматично відображається в обох валютах:

Конвертація використовує щоденні курси обміну від Національного банку України з EUR як базовою валютою.

Підтримувані валюти країн

• UA (Ukraine) → UAH (₴)
• PL (Poland) → PLN (zł)
• MD (Moldova) → MDL (L)
• RO (Romania) → RON (lei)
• CZ (Czech Republic) → CZK (Kč)
• Eurozone countries → EUR (€) - no conversion needed

Статуси підтвердження

Власник або його агент можуть встановити статус підтвердження платежу:

Видимість платежів

Хто бачить платежі залежить від ролі користувача на об'єкті:

Завантаження файлів

До платежу можна прикріпити квитанцію. Підтримувані формати:

• PDF - документи
• JPG, JPEG, PNG - зображення
• HEIC - фото з iPhone (конвертується в JPG)

Файли зберігаються в хмарному сховищі S3 з унікальним шляхом для кожного платежу.

Зв'язок з квитанціями

Платежі прив'язуються до квитанцій через таблицю PaymentAllocation. Кілька платежів можна об'єднати в одну квитанцію (наприклад, оренда + комунальні).

REST API

Платежі доступні через REST API з JWT авторизацією:

GET    /api/v1/payments                              - Мої платежі
GET    /api/v1/properties/{id}/payments              - Платежі об'єкта
POST   /api/v1/properties/{id}/payments              - Створити платіж
GET    /api/v1/properties/{id}/payments/{pid}        - Деталі платежу
PUT    /api/v1/properties/{id}/payments/{pid}        - Оновити платіж
DELETE /api/v1/properties/{id}/payments/{pid}        - Видалити платіж
POST   /api/v1/properties/{id}/payments/{pid}/confirm - Підтвердити
POST   /api/v1/properties/{id}/payments/{pid}/reject  - Відхилити

Приклад запиту на створення

Комунальні / витрати (комунальні)

{
  "payment_date": "2026-01-15",
  "amount": "150.50",
  "currency_id": 1,
  "expense_charge_id": 42,
  "contract_id": 5,
  "payer_user_id": 10,
  "notes": "January electricity payment"
}

Оренда (оренда)

{
  "payment_date": "2026-02-05",
  "amount": "25000.00",
  "currency_id": 3,
  "rental_charge_id": 34,
  "contract_id": 31,
  "payer_user_id": 13,
  "notes": "February rent"
}

Приклад відповіді

{
  "data": {
    "id": 1,
    "payment_type": "expense",
    "property_id": 5,
    "property_name": "Apartment Kyiv",
    "payment_date": "2026-01-15",
    "amount": "1500.00",
    "amount_formatted": "1,500.00 ₴",
    "currency": { "id": 3, "code": "UAH", "symbol": "₴" },
    "expense_type": { "id": 2, "code": "ELECTRICITY", "name_key": "expense_type.electricity" },
    "rental_charge": null,
    "service_provider": { "id": 3, "name": "Kyivenergo" },
    "recipient_user": null,
    "is_active": true,
    "owner_confirmation": "CONFIRMED",
    "has_file": true,
    "file_url": "https://llm.com/file/...",
    "file_name": "receipt.pdf"
  }
}

Відповідь для платежу за оренду

{
  "data": {
    "id": 500,
    "payment_type": "rental",
    "property_id": 5,
    "payment_date": "2026-02-05",
    "amount": "25000.00",
    "currency": { "id": 3, "code": "UAH", "symbol": "₴" },
    "expense_type": null,
    "rental_charge": {
      "id": 34,
      "charge_date": "2026-03-05",
      "period_start": "2026-02-05",
      "period_end": "2026-03-04",
      "rental_days": 28,
      "amount": "25000.00"
    },
    "service_provider": null,
    "is_active": true,
    "owner_confirmation": "CONFIRMED"
  }
}

Примітки API

• Поле payment_type вказує "expense" або "rental"
• expense_charge_id зв'язує платіж з розрахунковим періодом
• rental_charge_id прив'язує платіж до періоду нарахування оренди
• expense_charge_id та rental_charge_id є взаємовиключними
• Використовуйте payment_type=rental або payment_type=expense для фільтрації за типом
• Конвертація валюти країни виконується автоматично на фронтенді
• file_url використовує захищені URL з підписом HMAC та обмеженим терміном дії

Swagger / OpenAPI

Повна документація API з можливістю тестування доступна за адресою /api/v1/doc