KSeF i JPK w enova365: co naprawdę wyciągniecie przez WebAPI

Większość projektów automatyzacji księgowości na enova365 nie wykłada się na tej ciekawej części. Wykłada się dwa tygodnie wcześniej, na pytaniu, którego nikt nie wpisał do oferty: czy te dane w ogóle wychodzą z systemu, cyklicznie, w formie, która na zewnątrz nadal coś znaczy?

Powiem wprost, skąd ten tekst. Ze wszystkiego, co tu publikuję, ludzie realnie trafiają na strony techniczne o enova365 — przewodnik programisty po WebAPI przynosi więcej ruchu z wyszukiwarki niż cały klaster księgowy razem wzięty. Więc zadaję pytanie księgowe od tej strony, z której naprawdę przychodzicie: macie enova365, obowiązkowy KSeF już przestawił to, co siedzi w zapisach faktur, i chcecie wiedzieć, co automat jest w stanie z tego zobaczyć.

Trzy drogi wyjścia z enova365 i ta, której pożałujecie

Drogi są trzy. Wybór zwykle zapada źle — pada na tę, która jest dostępna najszybciej, a nie na tę, która przeżyje najbliższą aktualizację wersji.

WebAPI, pobieranie. Interfejs REST, autoryzacja JWT, kontrolery dynamiczne wystawiające dane dokumentów i zapisów oraz kontrolery statyczne do tego, co Soneta zamodelowała wprost. To jest droga wspierana. To także moduł płatny — jedno zdanie, które zatrzymuje więcej projektów niż wszystkie problemy techniczne z tego artykułu razem wzięte. Sprawdźcie to jako pierwsze, zanim ktokolwiek zacznie rysować architekturę.

Harmonogram Zadań, wysyłanie. Wbudowany harmonogram enova365 można ustawić tak, żeby sam się odzywał, zamiast czekać, aż ktoś go zapyta. Przy nocnym uzgodnieniu znaczy to mniej, niż się ludziom wydaje. Ale przy czymkolwiek, co musi zareagować tego samego dnia — odrzucona wysyłka do KSeF, dokument zmieniony już po wygenerowaniu zestawienia — push jest różnicą między kontrolą a alertem.

Replika SQL tylko do odczytu. Najszybsza do postawienia i wdrażałem ją nieraz, kiedy było jasne, że licencja WebAPI nie dojdzie w oknie projektu. Tylko trzeba wiedzieć, co się kupuje: schemat bazy nie jest kontraktem. Nic nie zobowiązuje Sonety, żeby zostawić kolumnę tam, gdzie spodziewa się jej wasze zapytanie. A w dniu, w którym ta kolumna się przesunie, integracja nie zaczyna działać gorzej — zaczyna po cichu kłamać. Traktujcie to jak most z datą ważności, trzymajcie wszystkie zapytania w jednym pliku i powiedzcie na głos, przy świadkach, że tak właśnie robicie.

Co KSeF naprawdę zmienił na poziomie pól

O obowiązku mówi się jak o wydarzeniu compliance'owym. Dla kogoś, kto buduje na tych danych, stało się coś węższego i dużo bardziej użytecznego: pojawił się pewny klucz.

Każda ustrukturyzowana faktura, która przechodzi przez krajowy system, wraca z numerem KSeF, a ten numer jest unikalny. Wcześniej odsiewanie duplikatów oznaczało dopasowanie po kontrahencie, kwocie i dacie — plus życie z fałszywymi trafieniami. Dwie identyczne faktury abonamentowe do tego samego klienta to przecież nie jest błąd, a żadna heurystyka nigdy nie rozdzieliła tego czysto. Powtórzony numer KSeF to fakt, nie przypuszczenie. Zupełnie inna klasa kontroli.

Druga rzecz, która doszła, jest warta pilnowania jeszcze bardziej: czy dokument, który księgi uważają za realny, faktycznie został przyjęty. Awaria, którą spotykam w praktyce, to nie jest odrzucona faktura — odrzucenie jest głośne i ktoś się nim zajmie tego samego popołudnia. Groźna jest faktura, przy której nikt nawet nie doszedł do próby wysyłki. Zerwana sesja. Token, który wygasł przez weekend. Dokument utworzony tak, że po cichu ominął ścieżkę wysyłki.

Księgi mówią, że faktura istnieje. Rejestr państwa milczy. I nikt tego nie wykrywa w dniu, w którym się dzieje, bo nic się nie zepsuło — coś się po prostu nie wydarzyło.

Uzgodnienie tych dwóch list to zapytanie, a nie problem dla AI. Na portfelu czterdziestu klientów i mniej więcej 2 400 dokumentów miesięcznie liczy się w sekundach. I ani razu nie widziałem, żeby w pierwszym miesiącu wróciło puste.

Pola JPK_V7 już tam są

Tu zaskoczenie spotyka wszystkich, którzy zakładają, że kontrola przed wysyłką oznacza odbudowanie pliku. Nie oznacza. Prawie wszystko, czego potrzebuje kontrola mechaniczna, jest już polem na dokumencie, który enova365 trzyma u siebie: oznaczenia GTU, oznaczenia procedur i typów dokumentów, klasyfikacja decydująca, do którego koszyka trafia pozycja, i kwoty, przez które ewidencja zgadza się z deklaracją albo się nie zgadza.

Kontrola przed wysyłką jest więc zwykłym odczytem. Pobrać dokumenty miesiąca, przyłożyć reguły, wypluć listę. Uruchomić trzeciego, kiedy poprawka kosztuje jeden telefon — a nie dwudziestego czwartego, kiedy kosztuje ten jedyny tydzień, którego już nie macie.

Rozróżnienie, przez które to w ogóle ma sens — i przez które lista kontroli jest krótka, a nie nieskończona — opisałem w tekście o tym, co agent naprawi w JPK_V7, a czego nie tknie: plik sprzeczny sam ze sobą to problem z danymi, który ma jedną poprawną odpowiedź. Plik będący wiernym zapisem błędnego rozumienia — nie ma.

API pomaga wyłącznie przy tym pierwszym rodzaju. I tak to jest większość wolumenu.

Czego WebAPI wam nie da

Uczciwy plan integracji potrzebuje tej listy bardziej niż poprzedniej.

Niczego interpretacyjnego. To, do którego okresu trafia faktura korygująca, zależy od momentu, w którym obie strony uzgodniły nowe warunki. A to uzgodnienie bardzo często było rozmową telefoniczną, spisaną później albo wcale. Żadne pole tego nie trzyma. Agent oznaczy każdą korektę, do której nie znalazł dokumentu potwierdzającego — przydatne, ale to zupełnie co innego niż podjęcie decyzji.

Pól niestandardowych, o które nie zapytacie. Instalacje enova365 obrastają w dodatki, a pola, które te dodatki wprowadzają, to nierzadko dokładnie te, na których firma faktycznie działa. Kontrolery dynamiczne same ich wam nie podsuną. Poproście o listę pól własnych używanych u każdego klienta wcześnie — przed wyceną zakresu, nie w połowie testów.

Powodu stojącego za wartością. Brakujące oznaczenie GTU i słusznie nieobecne oznaczenie GTU wyglądają w danych identycznie. Najwięcej, co powie wam kontrola, to: wygląda na to, że tu powinno coś być. Potem listę czyta człowiek.

Niczego o dokumentach, które nie przyszły. Najdroższe luki w miesiącu księgowym to nieobecności. Faktura, której klient nie przysłał. Wyciąg, którego nikt nie zaimportował. Żadne API nie powie wam o zapisie, którego nie ma. Tę kontrolę buduje się wobec oczekiwania — co powinno już tu leżeć — a to jest inny projekt i zwykle późniejszy etap.

Co zbudowałbym najpierw

Jeśli macie enova365 i chcecie mieć jedną działającą rzecz w dwa tygodnie zamiast mapy drogowej, zbudujcie nocne zadanie z trzema kontrolami i bez żadnego prawa zapisu:

1. Uzgodnienie statusów KSeF — dokumenty w księgach, przy których wysyłka nigdy się nie dokończyła, wylistowane z wiekiem w dniach.
2. Duplikaty po numerze KSeF — dziś tanie, jeszcze niedawno niewykonalne.
3. Pokrycie oznaczeń — pozycje, których klasyfikacja implikuje GTU albo oznaczenie dokumentu, a tego oznaczenia nie ma. Plus sytuacja odwrotna, której nikt nigdy nie szuka.

Wynikiem jest mail. Nic nie wraca zapisem, nic nie jest zatwierdzane, żaden dokument nie zmienia stanu. To trzyma całość po bezpiecznej stronie granicy, którą opisałem w tekście o tym, kto podpisuje, gdy agent się pomyli — czytanie i proponowanie, nigdy wysyłanie — i sprawia, że pierwsza wersja nie wymaga od nikogo decyzji o tym, na co agent ma pozwolenie. Jeśli chcecie zobaczyć, jak to wygląda w całości, opisałem to po stronie usług: integracja enova365 z AI.

O terminie nie decyduje budowa. Decyduje to, ile czasu zajmie, zanim konektor dostanie działające dane dostępowe do odczytu na produkcji — na dwóch porównywalnych projektach widziałem jeden dzień i pięć tygodni. Uczciwą wersję tej arytmetyki opisałem tutaj.

Zadajcie w tym tygodniu jedno pytanie: czy moduł WebAPI jest aktywny na waszej licencji i na jakim buildzie? Wszystko powyżej zaczyna się dopiero od tej odpowiedzi.

Chcecie usłyszeć wprost, która z tych kontroli ma sens przy waszej instalacji enova365, a która wyprodukuje wyłącznie szum? Napiszcie do mnie — ustalenie zakresu jest bezpłatne i zajmuje pół godziny.