Dokumentacja | Dokumentacja API

Przegląd

Rachunek grupuje jedną lub więcej płatności i opłat w jeden potwierdzalny dokument. Kwota rachunku jest automatycznie obliczana jako suma wszystkich powiązanych alokacji. Kwotę każdej alokacji można zmienić w miejscu, automatycznie tworząc zapisy korekt z dostawcami.

Automatyczna kwota

Kwota rachunku = suma wszystkich powiązanych płatności + opłat + jednorazowych wydatków. Bez ręcznego wprowadzania — wszystko obliczane automatycznie.

Korekty w miejscu

Zmień kwotę dowolnej alokacji bezpośrednio na stronie rachunku. System automatycznie utworzy korektę z dostawcą usług.

Jednorazowe wydatki

Dodaj jednorazowe wydatki (naprawy, usługi) bezpośrednio z rachunku. System automatycznie utworzy obciążenie + płatność + alokację.

Dwustronne potwierdzenie

Zarówno właściciel, jak i najemca muszą potwierdzić pokwitowanie niezależnie dla pełnej walidacji.

Obsługa wielu walut

Pokwitowania automatycznie konwertują się na walutę kraju nieruchomości, gdy różni się od waluty pokwitowania.

Załącznik dokumentu

Dołącz skan potwierdzenia bankowego lub paragonu w formacie PDF, JPG, PNG lub HEIC.

Architektura

Rachunki łączą się z płatnościami poprzez alokacje. Gdy kwota alokacji różni się od oryginalnej płatności, automatycznie tworzone jest powiązanie korekty i korekta z dostawcą.

Receipt Automatyczna suma, notatki, potwierdzenia

↕

PaymentAllocation Łączy rachunek ↔ płatność z edytowalną kwotą

↙ ↘

Payment Oryginalna płatność od najemcy

AdjustmentLink oryginał → skorygowana kwota, różnica

↓

ServiceProviderAdjustment Korekta salda z dostawcą usług

Proces korekty

Gdy zmieniasz kwotę alokacji na stronie rachunku:

1

Edycja kwoty

Kliknij ikonę ołówka obok kwoty płatności. Wprowadź nową kwotę w walucie nieruchomości.

2

Utworzenie powiązania korekty

System tworzy ReceiptAdjustmentLink przechowujący: kwotę oryginalną, skorygowaną i różnicę. Jedno powiązanie na alokację.

3

Korekta z dostawcą

Jeśli płatność jest powiązana z wydatkiem z dostawcą (Payment → ExpenseCharge → PropertyExpense → ExpenseProvider), ServiceProviderAdjustment jest tworzony/aktualizowany automatycznie. Automatyczne potwierdzenie od strony twórcy.

4

Automatyczne czyszczenie

Jeśli skorygowana kwota = oryginalna (różnica = 0), powiązanie korekty i korekta z dostawcą są automatycznie usuwane.

Przypadek bez dostawcy: Opłaty czynszowe i zwykłe płatności nie mają dostawcy usług. W tym przypadku tworzony jest tylko AdjustmentLink (bez ServiceProviderAdjustment).

Potwierdzenie i zasady edycji

Rachunki używają dwustronnego systemu potwierdzenia, który kontroluje uprawnienia do edycji:

Nie potwierdzone

Domyślnie. Żadna strona nie potwierdziła. Pełna edycja dostępna.

Potwierdzone

Jedna strona potwierdziła. Potwierdzona strona może odwołać. Druga strona może edytować.

W pełni potwierdzone

Obie strony potwierdziły. Rachunek zablokowany — bez edycji, bez dołączania/odłączania płatności, bez zmian dokumentów.

Zasada blokady: Gdy DRUGA strona potwierdzi, edycja jest dla Ciebie zablokowana. Przykład: jeśli najemca potwierdzi, wynajmujący nie może już zmieniać kwot, dołączać płatności ani przesyłać dokumentów. Pozostają tylko przyciski potwierdzenia/odwołania.

Połączenie z płatnościami

Na stronie rachunku możesz dołączyć istniejące płatności lub utworzyć nowe jednorazowe wydatki:

Dołącz istniejącą płatność

Wybierz z dostępnych płatności/opłat na liście. Kwota jest automatycznie wypełniana w walucie nieruchomości. Możesz ją zmienić, aby utworzyć korektę.

Dodaj jednorazowy wydatek

Wprowadź nazwę i kwotę. System utworzy: ExpenseCharge (typ ONE_TIME) → Payment → Allocation. Wymagane oba pola.

Odłącz płatność

Usuń płatność z rachunku. To również automatycznie usuwa powiązanie korekty i korektę z dostawcą.

Dowiedz się więcej: Aby uzyskać szczegółowe informacje o płatnościach, zobacz Płatności.

Edycja w miejscu

Strona podglądu rachunku obsługuje edycję w miejscu bez przechodzenia do osobnego formularza:

Notatki (WYSIWYG)

Kliknij ikonę ołówka, aby otworzyć edytor tekstu (Summernote). Obsługuje pogrubienie, kursywę, listy i linki. Zapisuje przez AJAX bez przeładowania strony.

Kwoty płatności

Kliknij ikonę ołówka obok kwoty płatności, aby ją zmienić. Zapisuje przez AJAX. Automatycznie tworzy/aktualizuje/usuwa korekty.

Przesyłanie dokumentu

Przeciągnij lub wybierz plik. Obsługuje JPG, PNG, PDF, HEIC (maks. 20 MB). Dokumenty synchronizują się automatycznie z Google Drive.

Zasady widoczności

Rola	Może zobaczyć
LANDLORD / AGENT	Wszystkie pokwitowania dla posiadanych nieruchomości
TENANT / AGENT	Pokwitowania związane z ich umowami i płatnościami

REST API

Dostęp do pokwitowań przez REST API (wymaga uwierzytelniania JWT):

GET    /api/v1/receipts                              - Lista moich pokwitowań
GET    /api/v1/properties/{id}/receipts              - Lista pokwitowań nieruchomości
GET    /api/v1/properties/{id}/receipts/{rid}        - Pobierz szczegóły pokwitowania

Pełna dokumentacja API z interaktywnym testowaniem jest dostępna w Swagger UI: /api/v1/doc