Automatyzacja faktur krok po kroku, czyli jak zbudowaliśmy własny system oparty o dowolnego agenta SI

Aktualizacja z października 2026: dopisaliśmy, jak agent odczytuje faktury, co w automatyzacji zmienia KSeF, i odpowiedzi na najczęstsze pytania.

Jest taki rytuał, który zna każdy przedsiębiorca. Zbliża się termin wysyłki dokumentów do księgowej, a Ty otwierasz skrzynkę i zaczynasz archeologię. Faktura od Google gdzieś była, przecież ją widziałeś. Ta od Stripe przyszła chyba na drugi adres. Twilio wysłało coś w załączniku, ElevenLabs dało tylko link, a połowa "faktur" okazuje się paragonami, potwierdzeniami i newsletterami, które mają słowo VAT w stopce. Po dwóch godzinach masz otwarte czternaście kart, trzy pobrane duplikaty i cichą pewność, że czegoś i tak brakuje.

U nas ten rytuał pochłaniał co miesiąc kilka godzin i regularnie kończył się mailem od księgowej z listą braków. W końcu pękliśmy. Postanowiliśmy problem zautomatyzować, ale nie gotowym SaaS-em, tylko własnym narzędziem zbudowanym na Claude Code, czyli agencie AI działającym z linii poleceń. To jest opowieść o tym wdrożeniu: z błędami, ślepymi uliczkami, gotowym promptem do skopiowania i paczką narzędzi do pobrania na końcu.

Najpierw mapa terenu: skąd przychodzą faktury

Zanim napisaliśmy pierwszą linijkę kodu, spisaliśmy, skąd w ogóle przychodzą do nas dokumenty. I to było pierwsze otrzeźwienie. Faktury nie mieszkają w jednym miejscu: większość przychodzi na skrzynkę firmową w Google Workspace (głównie przez Stripe), ale spora część historycznie trafiała na prywatnego Gmaila, bo ktoś kiedyś założył subskrypcję "na chwilę". Do tego dochodzą faktury w załącznikach PDF, faktury ukryte za linkiem "kliknij i pobierz", portale dostawców, z których dokument trzeba wynieść własnymi rękami, i wyciągi bankowe, które też chcemy mieć w komplecie, bo księgowa pyta o nie równie często. Do tego dochodzą faktury, które zespół zbiera sam: z delegacji, zakupów i wyjazdów.

Stąd pierwsza lekcja, którą oddajemy za darmo: automatyzacja faktur to nie jest "podłącz OCR do skrzynki". To system, który musi ogarnąć kilka źródeł, kilka formatów i całe morze szumu. Kto tego nie zaplanuje na starcie, będzie dobudowywał na kolanie później. Wiemy, bo dobudowywaliśmy.

Jak działa automatyzacja faktur w praktyce

Sercem systemu są dwa przebiegi sztucznej inteligencji, ustawione jak sito o dwóch gęstościach. Najpierw tani i szybki model dostaje sam tekst maila i odpowiada na jedno pytanie: czy to w ogóle sprawa księgowa? Newslettery, powiadomienia i marketing odpadają już tutaj, zanim ktokolwiek zapłaci za czytanie PDF-ów. Dopiero to, co przeszło, trafia do mocniejszego modelu, który czyta wyciągnięty z PDF-a tekst i zwraca konkret: typ dokumentu, sprzedawcę, nabywcę, numer, kwoty, rok i miesiąc.

Dalej dzieje się już zwykła, nudna informatyka. Plik ląduje na dysku współdzielonym w folderze rok/miesiąc, a do arkusza-rejestru dopisuje się wiersz: jeden dokument, jeden wiersz. Nuda jest tu komplementem. Na nudzie można polegać.

Dlaczego akurat Claude Code, a nie gotowa wtyczka? Z trzech powodów, które odkrywaliśmy po kolei. Po pierwsze, reguły w stylu "jak w mailu jest słowo faktura, to jest faktura" umierają przy pierwszym paragonie ze Stripe. Model językowy rozumie kontekst: odróżni fakturę od paragonu, przypisze dokument do miesiąca po dacie sprzedaży, a nie dacie maila, i pozna po treści, że wyciąg "za okres 1-31 maja" należy do maja, choć przyszedł w czerwcu. Po drugie, OCR dostaliśmy w standardzie: skan bez warstwy tekstowej agent po prostu czyta wizyjnie. Po trzecie, mieliśmy dwie skrzynki o zupełnie różnych interfejsach, Gmail API po stronie firmowej i IMAP po prywatnej. Napisaliśmy dwa cienkie adaptery o identycznym interfejsie i reszta systemu do dziś nie wie, skąd przyszedł mail. I nie musi wiedzieć.

Na tym samym wzorcu podłączyliśmy kolejne źródła. Faktury z KSeF i z iFirmy pobieramy przez ich API, a faktury od zespołu z folderu na Dysku Google, do którego każdy wrzuca swoje dokumenty. Dane z API przychodzą jako gotowe pola, więc trafiają do rejestru bez udziału AI. Pliki z Dysku przechodzą ten sam odczyt co załączniki z maili. Na końcu wszystko spotyka się w jednym rejestrze, a deduplikacja pilnuje, żeby faktura, która przyszła i mailem, i przez KSeF, nie została policzona dwa razy.

Odczyt faktur przez AI, czyli co agent wyciąga z PDF-a

"Odczyt faktur" brzmi jak jedna czynność, a w praktyce to trzy różne sytuacje. Każda idzie u nas inną ścieżką.

Najczęstsza jest faktura cyfrowa, czyli PDF wygenerowany przez system dostawcy, z warstwą tekstu. Tu nie ma czego OCR-ować: tekst wyciągamy zwykłą biblioteką (pdfplumber), przycinamy do rozsądnej długości i dopiero wtedy oddajemy modelowi. Model zwraca stały zestaw pól: typ dokumentu, sprzedawcę, nabywcę, numer faktury, kwotę, walutę, rok i miesiąc oraz kierunek, czyli czy to nasz koszt, czy nasza sprzedaż. Kierunku nie zgadujemy z tonu maila, tylko ustalamy go z samej faktury: jeśli nasza firma jest nabywcą, to koszt, a jeśli sprzedawcą, to sprzedaż.

Druga sytuacja to skan albo zdjęcie, czyli obraz bez warstwy tekstu. Takie pliki model czyta wizyjnie, ale tylko wtedy, gdy są małe i typowe: kilka stron i rozsądny rozmiar. Wielki, nietypowy skan nie jest czytany w ciemno, tylko dostaje status "do decyzji" i czeka na człowieka. Odczyt wizyjny kosztuje więcej i częściej się myli, więc nie nadużywamy go.

Trzecia sytuacja to śmieci udające dokumenty: logotypy, ikonki i stopki, które banki i kurierzy dokładają do maili. Odsiewamy je po rozmiarze pliku, zanim model w ogóle je zobaczy.

Najważniejsza zasada odczytu jest jednak inna: model nie ma prawa zgadywać. Jeśli na dokumencie nie widać numeru albo kwoty, pole zostaje puste, a nie "prawdopodobne". Odpowiedź przychodzi jako JSON, który walidujemy po swojej stronie, a spór "faktura czy paragon" rozstrzyga najpierw nazwa pliku, dopiero potem treść. Pusta komórka w rejestrze kłuje w oczy, więc ktoś ją uzupełni. Zmyślona kwota wygląda wiarygodnie i dożyje do kontroli.

Perypetie, czyli miesiące dopieszczania

Wersja pierwsza powstała w jeden wieczór i klasyfikowała wszystko jak leci. Byliśmy zachwyceni przez mniej więcej dobę. Potem zaczęła się prawdziwa robota, rozłożona na miesiące krótkich iteracji, z których każda zostawiała ślad w systemie.

Najpierw okazało się, że przepuszczanie każdego maila przez AI jest wolne i drogie. Tak powstał pre-filtr: okno dat plus około 57 słów kluczowych po polsku i angielsku, plus lista realnych nadawców billingowych, od Stripe po Hetznera. Ta lista rosła z każdym miesiącem, bo każdy dostawca ma swój dialekt. Potem Stripe zaskoczył nas mailem, w którym była i faktura, i paragon do tej samej płatności; rejestr zaczął puchnąć od duplikatów, więc faktura dostała bezwzględny priorytet nad paragonem. Następnie banki i kurierzy nauczyli nas, że "załącznik" to pojęcie względne: potrafią wrzucić do jednego maila kilkanaście ikonek i logotypów, które system próbował czytać jak dokumenty. Dziś odsiewamy je po rozmiarze pliku, zanim ktokolwiek je otworzy.

Był też odcinek z duplikatami, który nauczył nas pokory. Ten sam dokument potrafi przyjść na obie skrzynki naraz. Plik na dysku łatwo zdedupować po nazwie i numerze faktury, ale wiersze w rejestrze celowo zostawiamy oba, z adnotacją "możliwy duplikat, oryginał w wierszu N". Chcemy widzieć, że coś przyszło dwoma kanałami, zamiast udawać, że przyszło raz.

I wreszcie rzecz, z której jesteśmy dziwnie dumni: system umie powiedzieć "nie wiem". Faktura dostępna tylko za linkiem? Wielki skan, którego nie warto OCR-ować w ciemno? Zamiast zgadywać, do rejestru trafia jasny status i krótka lista do ręcznego domknięcia. Automatyzacja, która zna swoje granice, jest warta więcej niż taka, która udaje wszechmoc.

Pamięć systemu, czyli dlaczego z czasem jest tylko lepiej

Z całego wdrożenia najważniejsza jest jedna obserwacja: wartość nie siedzi w modelu AI, tylko w utrwalonej wiedzy wokół niego. Każdy miesiąc dokładał cegiełki. Nowy nadawca do filtra. Nowa reguła klasyfikacji. Nowy status brzegowy. Nowa procedura w runbooku. Model można jutro wymienić na inny; tej pamięci wymienić się nie da, bo to ona jest wdrożeniem.

Wykres jest poglądowy: ilustruje dynamikę naszego wdrożenia, nie laboratoryjny pomiar. Na początku ręcznie poprawialiśmy sporą część klasyfikacji: złe miesiące, paragony udające faktury, pominięci nadawcy. Z każdą iteracją odsetek malał, aż został twardy rdzeń dokumentów, których w mailu po prostu nie ma.

Mechanizm jest banalnie prosty i to jest w nim najpiękniejsze. Błąd pojawia się raz, zostaje opisany jako reguła i nigdy nie wraca. Po roku takiej akumulacji uruchomienie agenta to jedno polecenie, a jego "doświadczenie" to setki utrwalonych decyzji, których nikt nie musi podejmować ponownie.

Wyciągi bankowe domykają obieg

W pewnym momencie dołożyliśmy do systemu klasę dokumentu "wyciąg". Wyciągi są rozpoznawane automatycznie i katalogowane do miesiąca, którego dotyczy okres wyciągu, więc w folderze każdego miesiąca leżą obok siebie faktury i zestawienie z rachunku. A skoro jedno i drugie jest już w jednym miejscu, zbudowaliśmy na tych klockach kolejny moduł: weryfikator kompletności.

Agent czyta transakcje z wyciągu i najpierw je kategoryzuje, bo ZUS, podatki i opłaty bankowe faktury z definicji nie mają i nie powinny nikogo straszyć na liście braków. Resztę dopasowuje do faktur z rejestru: punktuje zgodność kwoty i waluty, bliskość dat, nazwę kontrahenta i numer faktury w tytule przelewu. A kiedy do jednej transakcji pasuje kilka dokumentów albo kwoty nie zgadzają się wprost, bo faktura jest w dolarach, a karta pobrała złotówki po przewalutowaniu, spór rozstrzyga zagnieżdżony, tani model AI. Dostaje transakcję i kandydatów, oddaje wybór z uzasadnieniem i oceną pewności. Na końcu powstaje zestawienie: co ma fakturę, co jej nie ma (to jest właściwa lista braków dla księgowej), co faktury nie wymaga i które faktury nie mają swojej transakcji, bo zapłacono je z innego rachunku. Zamiast pytania "czy mam wszystko?" dostajesz listę konkretów z kwotami. To dokładnie ten moment, w którym księgowa zaczyna wierzyć w AI.

A co z fakturami, których nie ma w mailu?

Zawsze zostanie grupa dostawców, którzy faktur nie wysyłają, tylko trzymają je w portalu. Tu kolejność ataku jest prosta. Jeśli portal ma API, używamy API, bo to droga stabilna i bezobsługowa. Jeśli API nie ma, zostaje automatyzacja przeglądarkowa: Playwright do powtarzalnych skryptów albo agent AI z dostępem do przeglądarki tam, gdzie logowanie i nawigacja bywają kapryśne. Z dwiema uwagami z życia: automatyzujcie wyłącznie własne konta i sprawdźcie regulamin portalu, a do pól z hasłami i płatnościami niech siada człowiek. To, czego nie da się pobrać żadną z tych dróg, system przynajmniej wykrywa i wpisuje do rejestru jako pozycję do ręcznego pobrania. Krótka lista zamiast archeologii to już zupełnie inna jakość życia.

Ten sam wzorzec działa zresztą dalej: źródłem nie musi być skrzynka. Dropbox, Google Drive, OneDrive, kanał na Slacku, na który ktoś wrzuca skan "faktury z delegacji". Schemat się nie zmienia: źródło, pobranie pliku, klasyfikacja, katalog i rejestr. Im więcej strumieni wpada do jednego rejestru, tym mniej dokumentów kończy żywot w folderze "Pobrane" na czyimś laptopie. A gdy skrypty przestają wystarczać, bo obiegowi dokumentów potrzebny jest panel, uprawnienia i historia zmian, naturalnym kolejnym krokiem jest dedykowana aplikacja spinająca wszystkie kanały w jedno.

A co z KSeF?

Od 1 lutego 2026 roku wszyscy podatnicy VAT odbierają faktury przez Krajowy System e-Faktur. Obowiązek wystawiania faktur w KSeF objął najpierw największe firmy (od 1 lutego), a od 1 kwietnia 2026 roku pozostałe. Najmniejsi, ze sprzedażą fakturowaną do 10 tys. zł miesięcznie, mają czas na wystawianie do końca 2026 roku. Czy to znaczy, że automatyzacja faktur z maila właśnie straciła sens?

Nie, ale przesuwa się jej środek ciężkości. Faktura z KSeF to ustrukturyzowany plik XML, więc odczyt przez AI jest przy niej zbędny: numer, kwoty i NIP-y leżą w polach, a nie w PDF-ie. Taką fakturę wystarczy pobrać przez API KSeF i dopisać do rejestru. Tyle że KSeF nie obejmuje wszystkiego, co ląduje na biurku księgowej. Faktury od zagranicznych dostawców (u nas to spora część kosztów: chmura, narzędzia, modele AI) dalej przychodzą mailem albo czekają w portalu. Paragony, potwierdzenia płatności i wyciągi bankowe też nie przechodzą przez KSeF. A uzgadnianie faktur z wyciągiem jest potrzebne tak samo jak wcześniej.

Dlatego u nas KSeF jest po prostu kolejnym źródłem: faktury kosztowe z KSeF trafiają do tego samego rejestru, obok tych z maila, z iFirmy i z folderu zespołu na Dysku Google. Schemat zostaje ten sam, zmienia się tylko jedno ogniwo, i akurat w nim AI może odpocząć.

Sam system jest otwarty na każde źródło i każdy cel, który ma API: KSeF, iFirma, wFirma, Fakturownia, platformy e-faktur czy bank. Dlatego paczka do pobrania niżej dostała procedurę integracji. Agent najpierw pyta, co ma się dziać z dokumentami: pobierać je do rejestru, przekazywać wydatki do programu księgowego czy tylko wyłapywać różnice. Potem prosi o dokumentację systemu, z którym ma się połączyć (do KSeF linki do oficjalnej dokumentacji Ministerstwa Finansów są już w paczce), przygotowuje plik .env na klucze dostępu, który uzupełniasz sam, i mówi, skąd wziąć każdy klucz. Pierwsze połączenie zawsze idzie do środowiska testowego. Firmom, które wolą dostać to gotowe, budujemy takie integracje w ramach automatyzacji procesów.

Prompt, od którego można zacząć

Nie musisz wierzyć nam na słowo, że klasyfikacja działa. Poniżej uproszczona wersja promptu z naszego drugiego przebiegu. Wklej do dowolnego agenta AI, który umie czytać PDF-y, podmień nazwę firmy i patrz, co się dzieje:

Jesteś asystentem księgowym. Dostajesz tekst dokumentu wyciągnięty z pliku PDF.
Przeanalizuj go i zwróć WYŁĄCZNIE poprawny JSON, bez komentarzy:

{
  "typ": "faktura" | "paragon" | "wyciag" | "inne",
  "faktura_vat": true/false,
  "sprzedawca": "nazwa wystawcy lub null",
  "nabywca": "nazwa odbiorcy lub null",
  "numer_faktury": "numer dokumentu lub null",
  "kwota_brutto": liczba lub null,
  "waluta": "PLN/EUR/USD lub null",
  "rok": RRRR,
  "miesiac": MM,
  "kierunek": "koszt" | "sprzedaz_wlasna" | "nieznany"
}

Zasady:
- rok i miesiąc ustal z DATY SPRZEDAŻY, potem z daty wystawienia; ignoruj datę maila.
- dla wyciągu bankowego miesiąc = KONIEC okresu ("za okres 1-31 maja" to 05),
  a kierunek ZAWSZE "nieznany" (wyciąg to nie koszt ani sprzedaż).
- jeśli sprzedawca zawiera "TWOJA_FIRMA", kierunek "sprzedaz_wlasna";
  jeśli nabywca zawiera "TWOJA_FIRMA", kierunek "koszt".
- paragon i potwierdzenie płatności to NIE faktura; przy wątpliwości typ "inne".
- nie zgaduj numerów ani kwot: brak danych = null.

Dwie rady na drogę: każcie modelowi zwracać czysty JSON i walidujcie go po swojej stronie, a spory "faktura czy paragon" rozstrzygajcie dodatkowo po nazwie pliku, bo Invoice-* i Receipt-* bywają szczersze niż treść dokumentu.

Zanim wystartujesz u siebie, przemyśl jeszcze cztery rzeczy, o które i tak byś się potknął. Prywatność: klasyfikacja oznacza wysyłanie treści maili do modelu AI, a przy skrzynce prywatnej to prywatna korespondencja, więc podejmij tę decyzję świadomie. Dostępy: najwygodniej pracuje się z kontem serwisowym i delegacją domenową, które czyta skrzynkę i pisze na dysk bez logowania człowieka. Koszty: agent na dużym miesiącu potrafi zjeść zaskakująco dużo tokenów, więc przetwarzaj małymi oknami, tydzień zamiast miesiąca. I idempotencja: każdy przebieg musi dać się bezpiecznie powtórzyć, bo pady się zdarzają, a dedup po numerze faktury i identyfikatorze maila sprawia, że wznowienie niczego nie dubluje.

Zabierz nasze narzędzia do domu

Zamiast opowiadać, po prostu dajemy kod. Spakowaliśmy prawdziwe narzędzia z naszego wdrożenia (usunęliśmy tylko dane firmy) w paczkę startową: pobieranie maili przez Gmail API i IMAP, dwuetapowa klasyfikacja, katalogowanie na Dysku, rejestr w Arkuszu i weryfikator wyciągów. Całość jest opakowana w skill, czyli plik instrukcji dla dowolnego agenta AI. To celowo zalążek, nie produkt: przy pierwszym uruchomieniu agent ma obowiązek przepytać Cię, skąd pobierać dokumenty, jakie typy Cię interesują, dokąd je składać i jakie masz dostępy, a dopiero potem dostosowuje narzędzia do Twojego układu i rusza z małym testem. Zaszyliśmy w nim też zasadę, od której wszystko zależy: każdy błąd ma prawo wystąpić raz, potem staje się regułą.

W najnowszej wersji paczka umie też przygotować integrację z KSeF, iFirma i każdym systemem, który ma API. Klucze dostępu trzyma wyłącznie w pliku .env albo w zmiennych środowiskowych systemu, nigdy w kodzie, a pilnuje tego osobny skrypt kontrolny. Klucz API wklejony w kod ma bowiem zwyczaj wypływać w najmniej odpowiednim momencie.

Rok później

Dziś zbieranie faktur wygląda u nas tak: agent odpalany jednym poleceniem przechodzi skrzynki, KSeF, iFirmę i folder zespołu na Dysku, kataloguje dokumenty i aktualizuje rejestr, a do ręcznego domknięcia zostaje krótka lista pozycji z portali. Rytuał archeologii się skończył. Księgowa dostaje komplet, a mail z listą braków przychodzi coraz rzadziej, i to raczej z pytaniem, jak my to właściwie robimy.

Paczka startowa, którą pobrałeś wyżej, wystarczy na dobry początek. Ale jeśli Twoja firma potrzebuje czegoś więcej, projektujemy i wdrażamy agentów AI oraz automatyzacje procesów szyte na miarę: z głębszą integracją z systemami, w których naprawdę żyją Twoje dane (ERP, CRM, systemy księgowe, API bankowe, KSeF), z większą liczbą kanałów pozyskiwania dokumentów (portale dostawców, EDI, skrzynki zespołowe, SharePoint czy Dropbox) i z bardziej zaawansowanym przetwarzaniem: od OCR trudnych skanów, przez walidację i uzgadnianie danych, po raportowanie, które samo trafia na biurko zarządu. Budujemy takie obiegi od audytu procesu, przez wdrożenie, po utrzymanie i rozwój.

Napisz na hello@mtzn.pl, a pokażemy Ci na Twojej własnej skrzynce, ile faktur ucieka Ci co miesiąc. Spoiler: więcej, niż myślisz.

Najczęstsze pytania o automatyzację faktur