Mea culpa! Pola jednak są udokumentowane!

Ale to i tak wymaga drobnej poprawki w dokumentacji, ponieważ:
- w spisie treści brakuje odpowiedniego odnośnika, a sekcja jest na końcu i nie ma nagłówka, przez co trudno ją znaleźć
- umiejscowienie tego opisu w dokumencie jest nieintuicyjne - t.j. najpierw są opisy zapytań typu "GET" i absolutny brak opisu odpowiedzi, po czym znajdują się opisy mutacji, operacji które coś modyfikują, następnie jakieś losowe rzeczy i nagle w środku dokumentu 'out of the blue' jest opis 'pola faktury'
-

Dzień dobry,

Dokumentacja jest nieaktualna i/lub niekompletna.

Przykładowo, w dokumentacji pole "kind" ma nastepujace wartosci:
```
"vat" - faktura VAT
"proforma" - faktura Proforma
"bill" - rachunek
"receipt" - paragon
"advance" - faktura zaliczkowa
"final" - faktura końcowa
"correction" - faktura korekta
"vat_mp" - faktura MP
"invoice_other" - inna faktura
"vat_margin" - faktura marża
"kp" - kasa przyjmie
"kw" - kasa wyda
"estimate" - zamówienie
"vat_mp" - faktura MP
"vat_rr" - faktura RR
"correction_note" - nota korygująca
"accounting_note" - nota księgowa
"client_order" - własny dokument nieksięgowy
"dw" - dowód wewnętrzny
"wnt" - Wewnątrzwspólnotowe Nabycie Towarów
"wdt" - Wewnątrzwspólnotowa Dostawa Towarów
"import_service" - import usług
"import_service_eu" - import usług z UE
"import_products" - import towarów - procedura uproszczona
"export_products" - eksport towarów
```

a w odpowiedzi otrzymałem wartość "kind":"canceled"

Dzien dobry,

Kolejny przyklad brakow w dokumentacji:

fakturownia zwraca odpowiedz z wypelnionym polem o nazwie "exchange_rate" (jako pole faktury). W dokumentacji nie ma mowy o takim polu (ctrl+f pokazuje 0 wynikow).

Dodatkowo API zwraca tez bardzo podobne pola, np. "exchange_currency_rate", ktore jest opisane w dokumentacji, ale w naszym przypadku to pole nie zawiera zadnych wartosciowych danych. Zauwazylem tez takie pola jak "exchange_rate_den" czy "exchange_currency_rate_den" - rowniez nieopisane w dokumetacji.

Taka usluga, jaka Panstwo oferuja, wymaga aby klienci mieli dostep do dokladnej, rzetelnej oraz aktualnej dokumentacji. Bardzo bym prosil o przyjrzenie sie tej dokumentacji i poprawienie jej. Z gory dziekuje

Dzien dobry,

Dziekuje za zainteresowanie problemem!

Przy okazji chcialbym zapytac jak dostac sie do informacji w kontekscie faktur korygujacych. T.j. w interfejsie UI na Waszej stronie, mozna znalezc informacje ze dana faktura koryguje inna fakture (ktora + odnosnik do tej faktury) oraz z drugiej strony, ze dana faktura zostala skorygowana przez inna fakture (ktora + odnosnik).

Jak moge dostac sie do tej informacji (odpowiednie ID faktury itd.) z poziomu API?

Dziekuje!

A w druga strone? T.j. majac fakture, skad wziac informacje, ze zostala ona skorygowana i przez ktora fakture?

Ale UI na Waszej stronie wyswietla, ze dana faktura zostala skorygowana przez inna i mozna kliknac w odnosnik i zobaczyc te fakture. Czyli taka informacja musi byc gdzies dostepa

Rozumiem. A istnieje szansa, zeby te dane pojawily sie w API?

Szkoda. Ale dziekuje za odpowiedzi!

Milego weekendu

Dzien dobry,

Czy identyfikator faktury jest uniknalny na poziomie calej fakturowni, czy tylko na poziomie "namespace'u"? T.j. jesli mam konta firmaA.fakturownia.pl, firmaB.fakturownia.pl to czy moge zakladac, ze ID nie beda sie powtarzac?

Dzien dobry,

Chcialbym zapytac o endpoint odpowiedzialny za aktualizacje platnosci w systemie. Czy aktualizujac platnosc, moge w argumencie podac liste polaczonych faktur (t.j. ich id-kow) i czy wtedy kwoty zostana odpowiednio przeliczone? Czy w takim przypadku lepiej jest usunac platnosc i dodac jeszcze raz?

Dzien dobry,

Wydaje mi sie, ze znalazlem blad w systemie Fakturownia. Kiedy odlaczymy platnosc od faktury, t.j. np. podam w aktualizacji wartosc `"invoice_ids": []`, to wtedy faktura(y), ktora wczesniej byla podpieta nie zostaje zaktualizowana i mamy rozjechany stan. Wyglada to w ten sposob, ze platnosc nie ma zadnego polaczenia, ale status faktury jest ustawiony na "oplacono"

Dzien dobry,

Dziekuje za odpowiedz. Poniekad bylbym w stanie to zrozumiec, jednak

po pierwsze - nawet jesli projektakt tak to sobie wymyslil, no to ja nie wiem czy takie zachowanie jest zachowaniem oczekiwanym przez klientow. Ja bym np. oczekiwal ze faktura przestanie byc w tej sytuacji oplacona. Jesli tak ma faktycznie byc, to oczekiwalbym zeby chociaz zostalo to skomentowane w dokumentacji, tak aby uzytkownik byl ostrzezony ze zachowanie jest takie a nie inne.

A po drugie, takie zachowanie jest zwyczajnie nie spojne - jesli zamiast odlaczyc platnosc od faktury, ja usune calkowicie platnosc z systemu, to wtedy status faktury juz sie jednak resetuje i nie jest ona 'oplacona'. -- W ramach komentarza: moglbym zamiast aktualizowac platnosc, to kazdorazowo ja usuwac i dodawac ponownie - i tak zreszta w tym momencie robie - jednak to ma jedna bardzo duza wade - taka operacja nie jest atomowa

Podbijam.

I chcialbym zwrocic uwage na pewien scenariusz: mam w systemie (niekoniecznie bezposrednio na Fakturownii) nowy przelew przychodzacy. Oznaczam ten przelew jako oplacenie faktury A (podlaczenie platnosci dzieje sie poprzez API Fakturownii). Okazuje sie, ze z jakiegos powodu to byl blad - to mogla byc zwykla ludzka pomylka przy "mapowaniu" na fakture albo tzw. "missclick". Faktura A otrzymala status "oplacona" tylko z tego jednego powodu, ze zostala do niej podpieta platnosc. Uzytkownik orientuje sie, ze zle polaczyl przelew i "odpina" ten przelew od faktury A i wyklikuje, zeby jednak ten przelew to byl platnoscia za fakture B. Faktura B otrzymuje status "oplacona". Jednak faktura A nadal jest oplacona, bo projektakt tak to sobie wymyslil i jest to rzekomo "zamierzone działanie programu". Przeciez to nie ma zadnego sensu. Odlaczam platnosc - status faktury musi zostac przeliczony.

Dzien dobry,

Nie, nie zgadzam sie - jest to blad. I probuje Pan ten blad usilnie zamiesc pod dywan. Dlaczego? Czy scenariusz powyzej to na prawde, nie przekonuje Pana, ze tak nie powinno byc?

Czy jest mi Pan w stanie przedstawic bardziej merytoryczne wytlumaczenie, dlaczego tak wlasnie ma byc? T.j. nie interesuje mnie, to ze "teraz tak jest". Interesuje mnie pytanie DLACZEGO. Bo poki co to wyglada bardziej leniwosc i niechec do zmiany tego, mimo ze jest zle.

Przepraszam, czy ja rozmawiam z robotem?

Nie zgadzam się. To, co Panowie opisują, nie jest "celowym działaniem", ale ewidentnym błędem projektowym lub, co bardziej prawdopodobne, zaniechaniem implementacyjnym.

Argumentacja, którą otrzymałem, jest jedynie obroną istniejącego stanu i wymuszonego obejścia problemu (workaround), a nie logicznym uzasadnieniem, dlaczego tak powinno być.

Oto kluczowe argumenty, dlaczego jest to błąd i jak prowadzi to do desynchronizacji danych w moim systemie:

1. Fundamentalna niespójność logiki systemowej (Aktualizacja vs. Usunięcie)

To jest najmocniejszy dowód na błąd, na który już zresztą zwróciłem uwagę:

Akcja A (Gdy usuwam płatność): Kiedy wywołuję DELETE /banking/payments/ID_PLATNOSCI.

Rezultat: Państwa system wie, że musi zaktualizować statusy faktur, które były powiązane z tą płatnością (i ustawia je np. na "nieopłacona"). Działa poprawnie.

Akcja B (Gdy aktualizuję płatność): Kiedy wywołuję PATCH /banking/payments/ID_PLATNOSCI z danymi {"invoice_ids": []}.

Rezultat: Państwa system nie aktualizuje statusów tych samych faktur.

Przecież z punktu widzenia faktury rezultat biznesowy obu tych akcji jest identyczny: przestała być z nią powiązana dana płatność. Fakt, że Państwa system reaguje na te dwa zdarzenia w zupełnie inny sposób, jest dla mnie definicją niespójności i błędu w implementacji. Operacja PATCH najwyraźniej nie uruchamia tych samych mechanizmów (triggerów/callbacków), co operacja DELETE, mimo że obie modyfikują ten sam stan powiązań.

2. Naruszenie integralności danych i zasady "Jednego Źródła Prawdy" (Single Source of Truth)

Wasze obecne działanie w API pozwala na desynchronizację danych.

W systemie fakturowym, z którym chcę się integrować, oczekuję, że status faktury ("opłacona", "częściowo opłacona", "nieopłacona") jest stanem pochodnym (derived state), a nie niezależną daną.

Źródłem prawdy (Single Source of Truth) o stanie opłacenia faktury powinna być dla mnie suma wartości aktualnie powiązanych z nią płatności.

Logika powinna być prosta: Status Faktury = Funkcja(Suma Powiązanych Płatności, Wartość Faktury).

Państwa API pozwala na absurdalną i logicznie niemożliwą sytuację, która jest definicją desynchronizacji danych:

Przykład Desynchronizacji, który u mnie występuje:

Faktura nr 1/2025.wartosc_brutto = 1000.00 PLN

Faktura nr 1/2025.powiazane_platnosci = [] (ponieważ odpiąłem je przez PATCH)

Faktura nr 1/2025.status = "opłacono"

Taki stan jest wewnętrznie sprzeczny. System pozwala na istnienie niepoprawnych danych. Mówienie mi, że to ja (jako klient API) mam to naprawić ręcznie kolejnym żądaniem, jest zrzuceniem na mnie odpowiedzialności za utrzymanie spójności waszej bazy danych. To dla mnie fundamentalny błąd projektowy.

3. Błędna obsługa scenariusza "ludzkiej pomyłki" (Mój przykład)

Scenariusz, który opisałem (2025-10-23 13:50), doskonale ilustruje, jak ta wada projektowa zawodzi w realnym świecie. Pozwolę sobie go powtórzyć:

Błąd: Omyłkowo łączę Płatność P1 z Fakturą A (PATCH /payments/P1 z "invoice_ids": [A]).

Stan: Faktura A ma status "opłacona". (OK)

Korekta: Zauważam błąd. Chcę to naprawić. "Odpinam" P1 od A i "podpinam" P1 do właściwej Faktury B (PATCH /payments/P1 z "invoice_ids": [B]).

Stan po korekcie (NIESPÓJNY):

Faktura B otrzymuje status "opłacona". (Poprawnie)

Faktura A nadal ma status "opłacona". (Niepoprawnie!)

W tym momencie Państwa system aktywnie przechowuje błędne informacje (Faktura A jest "opłacona", mimo braku płatności). Sugestia Pana Tomasza, że muszę teraz pamiętać, aby wysłać trzecią operację (ręczna aktualizacja statusu Faktury A), jest dla mnie obroną złego projektu i przerzucaniem na mnie odpowiedzialności za błędy systemu.

4. Błędne koło argumentacji ("Tak samo działa w UI")

Argument, że "jest ono identycznie działające z poziomu API jak również UI", niczego nie dowodzi.

To tylko potwierdza, że ten błąd logiczny istnieje w obu interfejsach (prawdopodobnie UI korzysta z tego samego wadliwego endpointu API). Fakt, że użytkownik w UI musi wykonać dwa kliki (najpierw odpiąć płatność, a potem ręcznie zmienić status faktury), jest dla mnie obejściem (workaround) problemu, a nie pożądaną funkcjonalnością.

Podsumowanie

Traktuję odpowiedź "celowe działanie" i zamknięcie wątku przez p. Michała jako próbę uniknięcia przyznania się do wady projektowej.

Oczekuję, że prawidłowe, atomowe działanie systemu będzie polegać na tym, że każda zmiana w obiekcie banking_payment, która modyfikuje atrybut invoice_ids, automatycznie uruchomi mechanizm przeliczania statusów dla wszystkich faktur, których dotyczyła ta zmiana (zarówno tych odpinanych, jak i podpinanych).

Wymaganie ode mnie, jako klienta API, wysyłania drugiego, a czasem trzeciego żądania, aby "posprzątać" stan bazy danych po wykonaniu jednej logicznej operacji (jaką jest przeniesienie płatności), jest zaprzeczeniem dobrych praktyk projektowania API.

Dlaczego zatem, w momencie calkowitego usuniecia platnosci z systemu, w takiej sytuacji juz nagle status faktury zostaje zmieniony?

Szanowny Panie Piotrze,

Dziękuję za obszerną odpowiedź. Niestety, z przykrością muszę stwierdzić, że jest ona całkowicie chybiona, opiera się na fundamentalnie błędnym założeniu i w żaden sposób nie odnosi się do sedna zgłaszanego przeze mnie problemu.

Cała Pańska argumentacja ("aspekty księgowe", "obieg księgowy", "ustawa o VAT") byłaby słuszna, gdybym ja próbował edytować treść faktury – na przykład jej pozycje, daty sprzedaży, dane nabywcy czy stawki VAT – po jej wystawieniu.

Tymczasem ja nie edytuję faktury. Ja edytuję inny, oddzielny obiekt systemowy, jakim jest banking_payment (Płatność).

Status płatności ("opłacona" / "nieopłacona") nie jest niezmienną treścią dokumentu podatkowego, jak np. data sprzedaży. Jest to dynamiczna metadana, która musi odzwierciedlać rzeczywisty stan powiązań tej faktury z płatnościami. Utrzymywanie w systemie fałszywego statusu "opłacona" dla faktury, która w rzeczywistości nie ma żadnych powiązanych płatności, jest właśnie zaprzeczeniem logiki księgowej, która wymaga rzetelnego odwzorowania stanu faktycznego. Protekcjonalne odsyłanie mnie do ustawy o VAT jest tu całkowicie nie na miejscu.

Co jednak najważniejsze – w całej swojej wyczerpującej odpowiedzi ani razu nie odniósł się Pan do mojego kluczowego argumentu, który doszczętnie obala całą Pańską tezę.

Pozwolę sobie zadać to pytanie po raz trzeci, licząc, że tym razem zostanie ono zauważone:

PYTANIE: Dlaczego operacja DELETE /payments/ID (całkowite usunięcie płatności) POPRAWNIE i automatycznie aktualizuje status powiązanej faktury (np. na "nieopłacona"), natomiast operacja PATCH /payments/ID (z invoice_ids: [], czyli odpięcie płatności) już tego NIE ROBI?

Przecież z punktu widzenia faktury rezultat biznesowy jest ten sam – traci ona powiązanie z płatnością.

Fakt, że Państwa system potrafi automatycznie zaktualizować status (co dzieje się przy DELETE), dowodzi ponad wszelką wątpliwość, że:

Nie ma żadnych "księgowych" ani "prawnych" przeciwwskazań do takiej automatycznej aktualizacji. (Tym samym Pański główny argument o "obiegu księgowym" upada).

Implementacja Państwa API jest po prostu niespójna i wadliwa. Logika, która istnieje dla operacji DELETE, nie została zaimplementowana dla operacji PATCH.

Proszę zatem przestać bronić tego ewidentnego błędu technicznego "aspektami księgowymi", które nie mają tu żadnego zastosowania, i odnieść się merytorycznie do tej fundamentalnej NIESPÓJNOŚCI w logice Państwa API.

Wbrew Pańskiej nadziei, temat nie jest wyczerpany, dopóki nie otrzymam merytorycznej odpowiedzi na powyższe pytanie.

Z poważaniem

Szanowny Panie Piotrze,

Dziękuję za tę odpowiedź.

Chciałbym podkreślić, że naprawdę nie mam zamiaru się z Państwem kłócić. Nie mam w tym ani celu, ani interesu. Szukam po prostu pragmatycznego rozwiązania mojego problemu.

Czy możemy w takim razie dojść do kompromisu?

Zostawmy ten nieszczęsny endpoint PATCH /payments/{id} w takiej formie, w jakiej jest – skoro upierają się Państwo, że "tak ma być".

Jednocześnie chciałbym zapytać, czy mogliby Państwo rozważyć dodanie nowego, dedykowanego endpointu, który realizowałby operację "odłączenia płatności od faktury" w sposób atomowy?

Chodziłoby o endpoint, który w ramach jednego wywołania:

Odłączałby płatność od wskazanych faktur

Jednocześnie gwarantowałby przeliczenie i zaktualizowanie statusów tych faktur, od których płatność została odpięta.

Dla deweloperów taki atomowy endpoint byłby rozwiązaniem czystym, bezpiecznym i rozwiązałby cały problem, o którym dyskutujemy. Uniknęlibyśmy konieczności wysyłania wielu żądań i ryzyka pozostawienia systemu w niespójnym stanie.

Bardzo proszę o poważne rozważenie takiej prośby. Myślę, że jest to rozwiązanie, które pogodzi Państwa stanowisko z realnymi potrzebami klientów korzystających z API.

Chciałbym również zwrócić uwagę, jak bardzo skomplikowana bywa logika rozliczania płatności, co dodatkowo komplikuje problem, o którym dyskutujemy.

Logika płatności w realnych scenariuszach biznesowych jest często bardzo złożona i opiera się na relacjach wiele-do-wielu.

Proszę rozważyć następujący, bardzo typowy przypadek:

Mamy fakturę F1, do której podpięte są płatności [P1, P2, P3].

Ta sama płatność P3 jest płatnością zbiorczą, która jednocześnie opłaca w całości faktury F2 i F3.

Teraz proszę sobie wyobrazić, że przez API muszę skorygować błąd i odpinam płatność P3 (np. wysyłając PATCH /payments/P3 z "invoice_ids": [] lub "invoice_ids": [F2, F3].

statusy faktur F1, F2 i F3 nie zostaną automatycznie zaktualizowane.

Oznacza to, że po mojej stronie (klienta API) musiałbym wykonać następujące operacje:

Wiedzieć, jakie wszystkie faktury (F1, F2, F3) były wcześniej powiązane z P3.

Pobrać każdą z tych faktur osobnym żądaniem.

Po swojej stronie zaimplementować skomplikowaną logikę, która przeliczy ich nowe salda (sumując pozostałe płatności, np. P1 i P2 dla faktury F1).

Wysłać kolejne, osobne żądania PATCH dla F1, F2 i F3, aby "ręcznie" naprawić ich statusy.

To jest koszmar implementacyjny, operacja nieatomowa i wysoce podatna na błędy. Przecież dokładnie po to płacimy za gotowe rozwiązanie, jakim jest Fakturownia, aby nie musieć implementować tak złożonej logiki księgowej po swojej stronie.

Utrzymanie spójności danych i automatyczne przeliczanie sald po modyfikacji powiązań płatności to podstawowa odpowiedzialność systemu fakturowego.

Dzień dobry,

Dla jasności - czy czekam na odpowiedź ponieważ temat został przekazany jakiejś innej osobie i ta osoba (naturalnie) dokona interakcji z pewnym opóźnieniem, czy po prostu zostałem całkowicie zignorowany i mam spodziewać się braku odpowiedzi?