Płatności

Przegląd

Moduł płatności pozwala rejestrować płatności za usługi komunalne i prace konserwacyjne. Każda płatność jest powiązana z nieruchomością i może mieć dołączony paragon.

Architektura płatności

Płatności obsługują dwa typy naliczeń: media i czynsz. Każda płatność jest powiązana z jednym typem.

Typy odbiorców

Płatność może być skierowana do jednego z dwóch typów odbiorców:

Konwersja walut

Podczas przeglądania płatności, jeśli waluta płatności różni się od oficjalnej waluty kraju nieruchomości, kwota jest automatycznie wyświetlana w obu walutach:

Konwersja wykorzystuje dzienne kursy wymiany z Narodowego Banku Ukrainy z EUR jako walutą bazową.

Obsługiwane waluty krajów

• 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

Statusy potwierdzenia

Właściciel lub jego agent może ustawić status potwierdzenia płatności:

Widoczność płatności

Kto widzi płatności zależy od roli użytkownika na nieruchomości:

Przesyłanie plików

Możesz dołączyć paragon do płatności. Obsługiwane formaty:

• PDF - dokumenty
• JPG, JPEG, PNG - obrazy
• HEIC - Zdjęcia iPhone (konwertowane do JPG)

Pliki są przechowywane w chmurze S3 z unikalną ścieżką dla każdej płatności.

Połączenie z pokwitowaniami

Płatności są powiązane z rachunkami przez tabelę PaymentAllocation. Wiele płatności można połączyć w jeden rachunek (np. czynsz + media).

REST API

Płatności są dostępne przez REST API z autoryzacją JWT:

GET    /api/v1/payments                              - Moje płatności
GET    /api/v1/properties/{id}/payments              - Płatności nieruchomości
POST   /api/v1/properties/{id}/payments              - Utwórz płatność
GET    /api/v1/properties/{id}/payments/{pid}        - Szczegóły płatności
PUT    /api/v1/properties/{id}/payments/{pid}        - Aktualizuj płatność
DELETE /api/v1/properties/{id}/payments/{pid}        - Usuń płatność
POST   /api/v1/properties/{id}/payments/{pid}/confirm - Potwierdź
POST   /api/v1/properties/{id}/payments/{pid}/reject  - Odrzuć

Przykład żądania utworzenia

Media / wydatki (media)

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

Czynsz (czynsz)

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

Przykładowa odpowiedź

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

Odpowiedź dla płatności czynszu

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

Uwagi dotyczące API

• Pole payment_type wskazuje "expense" lub "rental"
• expense_charge_id łączy płatność z okresem rozliczeniowym
• rental_charge_id łączy płatność z okresem naliczenia czynszu
• expense_charge_id i rental_charge_id wykluczają się wzajemnie
• Użyj payment_type=rental lub payment_type=expense do filtrowania według typu
• Konwersja waluty kraju odbywa się automatycznie na interfejsie użytkownika
• file_url używa bezpiecznych adresów URL podpisanych HMAC z ograniczonym czasem życia

Swagger / OpenAPI

Pełna dokumentacja API z możliwością testowania jest dostępna pod adresem /api/v1/doc