Zahlungen

Überblick

Das Zahlungsmodul ermöglicht die Erfassung von Zahlungen für Nebenkosten und Wartungspersonal. Jede Zahlung ist mit einem Objekt verknüpft und kann eine angehängte Quittung haben.

Zahlungsarchitektur

Zahlungen unterstützen zwei Arten von Gebühren: Nebenkosten und Miete. Jede Zahlung ist mit genau einem Typ verknüpft.

Empfängertypen

Eine Zahlung kann an einen von zwei Empfängertypen adressiert sein:

Währungsumrechnung

Beim Anzeigen einer Zahlung wird der Betrag automatisch in beiden Währungen angezeigt, wenn die Zahlungswährung von der offiziellen Landeswährung der Immobilie abweicht:

Die Umrechnung verwendet tägliche Wechselkurse der Nationalbank der Ukraine mit EUR als Basiswährung.

Unterstützte Landeswährungen

• 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

Bestätigungsstatus

Eigentümer oder sein Vertreter kann den Bestätigungsstatus der Zahlung festlegen:

Zahlungssichtbarkeit

Wer Zahlungen sieht, hängt von der Benutzerrolle im Objekt ab:

Dateien hochladen

Zur Zahlung kann eine Quittung angehängt werden. Unterstützte Formate:

• PDF - Dokumente
• JPG, JPEG, PNG - Bilder
• HEIC - Fotos vom iPhone (wird in JPG konvertiert)

Dateien werden in S3-Cloud-Speicher mit eindeutigem Pfad für jede Zahlung gespeichert.

Verknüpfung mit Quittungen

Zahlungen werden über die PaymentAllocation-Tabelle mit Quittungen verknüpft. Mehrere Zahlungen können zu einer Quittung zusammengefasst werden (z.B. Miete + Nebenkosten).

REST API

Zahlungen sind über REST API mit JWT-Autorisierung verfügbar:

GET    /api/v1/payments                              - Meine Zahlungen
GET    /api/v1/properties/{id}/payments              - Objektzahlungen
POST   /api/v1/properties/{id}/payments              - Zahlung erstellen
GET    /api/v1/properties/{id}/payments/{pid}        - Zahlungsdetails
PUT    /api/v1/properties/{id}/payments/{pid}        - Zahlung aktualisieren
DELETE /api/v1/properties/{id}/payments/{pid}        - Zahlung löschen
POST   /api/v1/properties/{id}/payments/{pid}/confirm - Bestätigen
POST   /api/v1/properties/{id}/payments/{pid}/reject  - Ablehnen

Beispiel für Erstellungsanfrage

Nebenkosten / Ausgaben (Nebenkosten)

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

Miete (Miete)

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

Beispielantwort

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

Antwort für Mietzahlung

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

• Feld payment_type zeigt "expense" oder "rental" an
• expense_charge_id verknüpft Zahlung mit einem Abrechnungszeitraum
• rental_charge_id verknüpft Zahlung mit einem Mietzeitraum
• expense_charge_id und rental_charge_id schließen sich gegenseitig aus
• Verwenden Sie payment_type=rental oder payment_type=expense zum Filtern nach Typ
• Die Währungsumrechnung des Landes erfolgt automatisch auf dem Frontend
• file_url verwendet HMAC-signierte sichere URLs mit begrenzter Lebensdauer

Swagger / OpenAPI

Vollständige API-Dokumentation mit Testmöglichkeit verfügbar unter /api/v1/doc