Automatyczne księgowanie w enova365: jak agent AI tworzy szkice dokumentów przez WebAPI

Dwa API, jedna pętla

Napisałem dwa teksty, które razem dają całą historię: jak KSeF zamienia każdą fakturę zakupową w ustrukturyzowane dane za jednym API oraz jak Soneta WebAPI w enova365 zapisuje dokumenty — jako szkice do przejrzenia, nigdy jako finalne księgowania. Ten artykuł jest o tym, co siedzi pomiędzy nimi: o agencie, który zamienia "przyszła ustrukturyzowana faktura" w "poprawny, zweryfikowany szkic siedzi w buforze enova365 i czeka na jedno kliknięcie".

Prowadzę wersję tej pętli produkcyjnie — nie dokładnie ten przepływ księgowy, ale tę samą architekturę, zastosowaną do szkiców zamówień hurtowych zapisywanych do enova365 przez WebAPI. Wzorzec jest identyczny: ekstrakcja, mapowanie, klasyfikacja, zapis do bufora, kolejka do akceptacji. Poniżej opisuję, jak to działa, gdy na wejściu są faktury, a nie zamówienia.

Jeśli szukasz kontekstu biznesowego tego podejścia — nie tylko architektury — zajrzyj na stronę o integracji enova365 z AI.

Co wchodzi: XML z KSeF i ogon w postaci PDF-ów

Agenta zasilają dwa źródła dokumentów, i nie są równoważne pod względem wiarygodności.

Faktury z KSeF przychodzą jako ustrukturyzowany XML FA(3) przez API KSeF 2.0 — NIP sprzedawcy, kwoty, stawki VAT per pozycja, daty — wszystko już jako pola, nie ma czego odczytywać z obrazka. To większość przypadków dla krajowych zakupów B2B teraz, gdy ustrukturyzowane fakturowanie jest obowiązkowe, i to ścieżka, wokół której agent jest zaprojektowany.

PDF-y z maila pokrywają to, czego KSeF nie obejmuje: zagranicznych dostawców, paragony, spóźnialskich sprzed obowiązku. Przechodzą przez krok ekstrakcji — OCR plus model językowy czytający układ dokumentu — który z natury jest mniej dokładny niż pole ustrukturyzowane. Agent utrzymuje tę ścieżkę, bo jest potrzebna, ale traktuje ją jako wyjątek, nie domyślne podejście. Jeśli projektujesz podobny system, oprzyj się pokusie budowania całego pipeline'u wokół ekstrakcji z PDF-ów, bo "działa dla wszystkiego" — działa, ale mniej precyzyjnie, a precyzja jest dokładnie tym, czego chcesz po stronie wejściowej zapisu księgowego.

Obie ścieżki zbiegają się do tego samego znormalizowanego kształtu, zanim cokolwiek innego się wydarzy: tożsamość sprzedawcy, kwoty, daty, rozbicie VAT, pozycje, referencja do dokumentu źródłowego. Od tego momentu faktury z KSeF i z maila są przetwarzane identycznie.

Mapowanie kontrahenta: NIP to jedyny klucz złączenia, który się trzyma

Zanim agent cokolwiek zaproponuje, musi wiedzieć, od kogo jest faktura — a konkretnie, na który rekord kontrahenta w enova365 to się mapuje.

Dopasowanie po nazwie nie przetrwa kontaktu z rzeczywistością. "ABC Sp. z o.o." na fakturze, "ABC Spółka z o.o." w enova365, "ABC" w eksporcie z portalu — trzy ciągi znaków, jedna firma, a algorytm dopasowania rozmytego prędzej czy później albo przegapi prawdziwe dopasowanie, albo — gorzej — połączy dwie różne firmy, które przypadkiem współdzielą fragment nazwy. NIP nie ma tego problemu. To unikalny, weryfikowalny identyfikator i dokładnie to pole, po którym kluczują rekordy kontrahentów w enova365.

Wyszukiwanie jest więc bezpośrednie: bierzesz NIP sprzedawcy z faktury, sprawdzasz go wobec rekordów kontrahentów enova365 przez kontroler dynamiczny WebAPI i albo dostajesz dokładne dopasowanie — łączysz fakturę wprost z tym wewnętrznym ID — albo nie. Brak dopasowania nie wywołuje zgadywania. Trafia do kolejki wyjątków z NIP-em, wyekstrahowaną nazwą firmy i proponowaną akcją (utworzenie nowego kontrahenta albo oznaczenie jako prawdopodobny duplikat istniejącego) do potwierdzenia przez człowieka. Automatyczne tworzenie rekordów kontrahentów bez spojrzenia człowieka to jedno z niewielu miejsc, w których aktywnie unikałbym pełnej automatyzacji nawet po tym, jak reszta pipeline'u zdobędzie zaufanie — błędny albo zduplikowany rekord kontrahenta to typ drobnej pomyłki, który po cichu psuje raportowanie przez miesiące.

To samo wyszukiwanie po NIP jest też zaczepem dla weryfikacji kontrahenta, zanim cokolwiek zostanie zaksięgowane: aktywny status VAT na białej liście, dopasowanie IBAN z faktury do zarejestrowanych rachunków, VIES dla kontrahentów z UE. Zbudowałem dokładnie to sprawdzenie też jako osobne narzędzie — bota na Telegramie, który weryfikuje kontrahentów po NIP w kilka sekund — bo to sprawdzenie jest użyteczne samo w sobie, poza całym pipeline'em księgowania, kiedy ktoś po prostu potrzebuje szybkiej odpowiedzi przed zatwierdzeniem płatności.

Klasyfikacja księgowania

Po znormalizowaniu faktury i rozwiązaniu kontrahenta agent proponuje stronę księgową: które konto kosztowe, KUP czy NKUP, VAT odliczalny czy nie, które MPK. To nie jest jedna tabela lookup — to mieszanka twardych reguł (prawo VAT jest jednoznaczne w wielu przypadkach) i modelu językowego, który nauczył się konwencji konkretnej firmy albo klienta biura z historycznych księgowań. Powtarzalny dostawca, zawsze księgowany na to samo konto z tym samym traktowaniem VAT, dostaje klasyfikację z wysoką pewnością; pierwszy raz widziany dostawca albo typ faktury, którego agent nie widział, dostaje propozycję z niższą pewnością — a niska pewność to dokładnie sygnał, który kieruje coś do człowieka zamiast zapisywać po cichu.

Każda zaproponowana klasyfikacja niesie krótką notatkę wyjaśniającą rozumowanie — które historyczne księgowania pasowały, która reguła zadziałała, albo dlaczego jest niepewna. Ta notatka podróżuje ze szkicem do enova365 jako pole komentarza, więc człowiek przeglądający go nie zaczyna od zera — potwierdza albo poprawia konkretny, widoczny fragment rozumowania.

Zapis szkicu przez WebAPI

Tu bezpośrednio wchodzi w grę mechanika WebAPI. Agent tworzy dokument faktury zakupu (FZ) przez kontroler dynamiczny, z każdym polem, które wyprodukował krok klasyfikacji, już uzupełnionym — kontrahent, kwoty, rozbicie VAT, konto, MPK — i jedną świadomie ustawioną flagą: status bufora, nie zatwierdzony.

Ta jedna flaga to cała architektura bezpieczeństwa w jednym miejscu. enova365 nadal uruchamia własną logikę przy zapisie — przydziela numer dokumentu z własnej sekwencji, stosuje własne reguły VAT i cenowe tam, gdzie mają zastosowanie — ale dokument siedzi w buforze dokładnie tak, jak zrobiłby to człowiek, który jeszcze go nie potwierdził. Jest widoczny wewnątrz enova365, edytowalny i całkowicie obojętny, dopóki ktoś go nie zatwierdzi. Dokument w statusie bufora nie dotyka rejestrów VAT ani nie zamyka okresu.

Agent nigdy nie wywołuje osobnej akcji, która przenosi dokument z bufora do zatwierdzonego. Ten krok to odrębne, jawne wywołanie — i w tej architekturze uruchamia je wyłącznie działanie człowieka, bezpośrednio w enova365 albo przez interfejs przeglądu, który dopiero wtedy wykonuje to jedno wywołanie w imieniu człowieka, powiązane z jego tożsamością.

Pętla akceptacji

Strona skierowana do człowieka jest celowo nudna: kolejka szkiców, każdy pokazujący dokument źródłowy (oryginalny XML z KSeF albo PDF), wyekstrahowane pola, dopasowanie kontrahenta, proponowaną klasyfikację z notatką uzasadniającą i jeden przycisk. Zatwierdź potwierdza dokument w enova365. Odrzuć albo popraw odsyła go z zapisaną korektą — która, robiona konsekwentnie, jest też sygnałem uczącym, poprawiającym kolejną klasyfikację.

Wolumen, który kiedyś zjadał przedpołudnie — trzydzieści, pięćdziesiąt, sto faktur — przychodzi wstępnie posortowany. Uwaga księgowej idzie na naprawdę niejednoznaczne przypadki, nie na przepisywanie liczb, które już były poprawne w XML-u z KSeF.

Dlaczego szkice, nigdy finalne księgowania — powiedziane wprost

Powiem to tak wprost, jak się da, bo to jedna decyzja projektowa w całej tej architekturze, na której punkcie nie ustąpiłbym nawet pod presją, żeby "po prostu zrobić to szybciej": agent nigdy nie wywołuje kroku zatwierdzenia. Nie po okresie próbnym, nie po miesiącach czystych szkiców, nawet nie dla faktur niskiej wartości z wysoką pewnością. Kilka powodów, jeden na drugim:

Finalne księgowanie ma konsekwencje — wpływa na rejestry VAT, wpływa na okres, który może się właśnie zamykać, wpływa na liczby, pod którymi ktoś podpisze deklarację. Te konsekwencje powinny prowadzić z powrotem do decyzji człowieka, nie do progu w funkcji oceniającej.

Błędy kumulują się inaczej w zależności od tego, kto je łapie. Błędny szkic kosztuje jedno kliknięcie do poprawienia. Błędne finalne księgowanie kosztuje korektę, być może korektę deklaracji, być może rozmowę z klientem o tym, dlaczego jego liczby zmieniły się po fakcie.

A zaufanie do automatyzacji takiej jak ta buduje się na historii widocznych, poprawnych szkiców — nie przez usunięcie punktu kontrolnego, który w ogóle robi tę historię widoczną. W momencie, gdy automatyzujesz zatwierdzenie, tracisz dokładnie ten sygnał (człowieka patrzącego na każdy zapis), który mówi Ci, czy system faktycznie działa.

Projektowanie kolejki wyjątków

Kolejka wyjątków jest użyteczna tylko wtedy, gdy jest konkretna co do powodu, dla którego coś w niej wylądowało — stos "wymaga przeglądu" bez uzasadnienia to po prostu druga skrzynka odbiorcza. Kolejka w tej architekturze kieruje pozycje z podanym powodem, a każdy powód implikuje inną kolejną akcję:

• Niezmapowany kontrahent — NIP nie ma dopasowania w rekordach kontrahentów enova365. Akcja: potwierdzenie utworzenia nowego kontrahenta albo oznaczenie jako prawdopodobna zmiana nazwy/scalenie istniejącego.
• Nieudana weryfikacja kontrahenta — NIP nie przechodzi sprawdzenia białej listy, jest nieaktywny albo IBAN z faktury nie pasuje do zarejestrowanego rachunku. Akcja: ocena człowieka przed jakimkolwiek księgowaniem, biorąc pod uwagę odpowiedzialność solidarną powyżej progu 15 000 zł.
• Niska pewność klasyfikacji — pierwszy raz widziany dostawca, nietypowy rodzaj kosztu albo wzorzec, którego model nie widział wystarczająco dużo razy. Akcja: ręczna klasyfikacja, która staje się później sygnałem treningowym.
• Anomalia kwoty lub VAT — suma niezgadzająca się z pozycjami, stawka VAT wyglądająca źle dla opisanego towaru, faktura ze split payment (MPP) wymagająca jawnego, a nie zakładanego, odwzorowania podziału netto/VAT. Akcja: ręczne sprawdzenie wobec dokumentu źródłowego.
• Błąd zapisu przez WebAPI — token wygasł w środku batcha, ścieżka sieciowa do serwera WebAPI padła albo moduł licencyjny chwilowo wygasł. Akcja: automatyczna ponowna próba z zapisanym błędem, eskalacja do człowieka tylko po wyczerpaniu prób.

Ta ostatnia kategoria zasługuje na osobne wymienienie, bo jest specyficzna dla tej architektury: te same tryby awarii, które opisałem w przewodniku programisty po WebAPI — timing odświeżania tokena, dostęp sieciowy, status licencji — tutaj nie tylko spowalniają synchronizację portalu. To różnica między fakturą zaksięgowaną na czas a fakturą po cichu brakującą w miesięcznym zamknięciu. Logika ponawiania prób i alertowania agenta traktuje łączność z WebAPI jako coś do monitorowania pierwszej klasy, nie jako założenie.

Ścieżka audytu

Każdy zapis niesie rekord niezależny od własnej historii enova365: dokument źródłowy (numer referencyjny KSeF albo oryginalny PDF), każde wyekstrahowane pole, decyzję dopasowania kontrahenta i identyfikator zapytania weryfikacji NIP, uzasadnienie klasyfikacji, kto i kiedy zatwierdził, oraz — dla wszystkiego, co przeszło przez kolejkę wyjątków — co wywołało wyjątek i jak został rozwiązany. To nie jest opcjonalna księgowość księgowości; to jest to, co czyni cały system obronnym, jeśli ktoś — audytor, urząd skarbowy, sam klient — zapyta miesiące później, dlaczego konkretny zapis wygląda tak, jak wygląda.

Jak zacząć bez obstawiania na to zamknięcia miesiąca

Ta sama zasada obowiązuje tu, co wszędzie indziej w tego typu automatyzacji: zacznij wąsko, w trybie cienia, i poszerzaj, kiedy system stanie się nudno poprawny.

Wybierz jedną kategorię kosztową albo strumień faktur jednego klienta biura. Uruchom agenta tylko-do-odczytu — ekstrakcja, mapowanie, klasyfikacja, propozycja — przez tydzień lub dwa i porównuj jego propozycje z tym, co faktycznie zaksięgował człowiek, bez pozwalania mu na jakikolwiek zapis. Potem włącz zapis szkiców dla tego samego wąskiego zakresu, zostaw kolejkę wyjątków przed człowiekiem i poszerzaj zakres dopiero, kiedy szkice przestaną kogokolwiek zaskakiwać.

---

Buduję dokładnie ten pipeline — KSeF i mail na wejściu, mapowanie kontrahenta i klasyfikacja pomiędzy, zapis wyłącznie szkiców do bufora enova365 przez WebAPI, akceptacja człowieka i pełna ścieżka audytu na wyjściu — dla polskich biur rachunkowych i działów finansowych. Jeśli chcesz zobaczyć, jak to wygląda na Twojej konfiguracji enova365, strona o integracji enova365 z agentami AI ma szczegóły, strona usługi agentów AI pokazuje ofertę handlową, albo po prostu odezwij się bezpośrednio.