Платежи

Обзор

Модуль платежей позволяет регистрировать оплаты за коммунальные услуги и работу обслуживающего персонала. Каждый платёж привязан к объекту недвижимости и может иметь прикреплённую квитанцию.

Архитектура платежей

Платежи поддерживают два типа начислений: коммунальные расходы и аренду. Каждый платёж привязан к одному типу.

Типы получателей

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

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

При просмотре платежа, если валюта платежа отличается от официальной валюты страны объекта, сумма автоматически отображается в обеих валютах:

Конвертация использует ежедневные курсы обмена от Национального банка Украины с 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