Integracja systemu ERP z KSeF krok po kroku

Integracja ERP z KSeF powinna łączyć dokument w ERP z wynikiem jego przetworzenia, numerem KSeF i urzędowym poświadczeniem odbioru, czyli UPO. Osobny proces musi pobierać faktury zakupowe i przekazywać je do akceptacji lub księgowania.

Przed wyborem rozwiązania sprawdź dokładną wersję ERP, rozszerzenia i rodzaje faktur. Konektor producenta, warstwa pośrednia i własne połączenie z API mogą współpracować w jednej architekturze.

Wysyłka rozpoczyna przetwarzanie. Dopiero końcowy wynik pozwala oznaczyć fakturę jako przyjętą. Po utracie odpowiedzi najpierw uzgodnij wynik poprzedniej operacji, zamiast wysyłać dokument ponownie.

Odbierz wdrożenie na podstawie testów błędów, odtwarzania i kompletności zakupów. Procedury offline wymagają różnych terminów; lokalny problem z Internetem nie jest ogłoszoną awarią KSeF.

1. Zakres i odpowiedzialność

2. Konektor, middleware czy własne API

3. Dostęp i środowiska

4. Mapowanie danych

5. Sprzedaż, statusy i UPO

6. Odbiór zakupów

7. Błędy i ponowienia

8. Offline i awarie

9. 12 testów odbiorowych

10. Start produkcyjny i utrzymanie

11. Koszt i zapytanie ofertowe

12. Zakres KSeFGPT

13. Najczęściej zadawane pytania

Zacznij od listy spółek, kontekstów podatnika i miejsc powstawania faktur. Rozdziel sprzedaż krajową między firmami, sprzedaż konsumencką, transakcje zagraniczne, zaliczki, korekty i samofakturowanie. Dodaj przypadki z rozszerzeń ERP, a nie tylko standardowy formularz sprzedaży.

Obowiązek KSeF zależy od podatnika i dokumentu. Zwolnienie z VAT nie daje automatycznego wyłączenia, a faktury konsumenckie są fakultatywne w KSeF. Ustal reguły z księgowością; sam polski NIP ani waluta faktury nie rozstrzygają kwalifikacji.

Księgowość zatwierdza reguły podatkowe i dane faktury. Administrator ERP potwierdza źródła danych oraz zgodność wersji i rozszerzeń. Integrator odpowiada za transport, statusy i odtwarzanie. Wyznacz także osobę reagującą na zaległą kolejkę i zespół akceptujący zakupy.

Rezultatem jest podpisana macierz: rodzaj dokumentu, źródło danych, sposób wystawienia, odbiorca, właściciel i kryterium odbioru. Wysyłanie sprzedaży oraz odbieranie zakupów mają osobne wymagania. Odbioru nie odkładaj do chwili uruchomienia wysyłki.

Poproś dostawcę o potwierdzenie zgodności dla konkretnej rodziny i wersji ERP, aktualizacji, modułów i własnych modyfikacji. Ogólna deklaracja obsługi KSeF nie określa obsługiwanych korekt, odbioru zakupów ani sposobu zapisania numeru KSeF przy dokumencie.

Konektor to gotowy moduł połączenia, zwykle utrzymywany przez producenta lub partnera. Middleware jest warstwą pośrednią między systemami, która może zarządzać kolejkami i mapowaniem. Własna integracja wymaga zespołu utrzymującego cały cykl komunikacji z API. Warstwa pośrednia może korzystać z konektora, więc te rozwiązania nie muszą się wykluczać.

Rezultatem jest schemat przepływu danych i umowa o odpowiedzialności. Dla każdego przejścia wskaż, gdzie powstaje trwały zapis, kto naprawia błąd i jak dane wracają do ERP. Przed zakupem poproś o demonstrację na zestawie własnych, zanonimizowanych scenariuszy.

Uwierzytelnienie potwierdza tożsamość. Uprawnienia określają operacje dostępne w danym kontekście. Przetestuj osobno wystawianie i odczyt, także po odebraniu uprawnienia. Skuteczne logowanie nie jest odbiorem tego etapu.

Certyfikat KSeF typu 1 służy do uwierzytelniania. Typ 2 potwierdza wystawcę w odpowiednich procedurach offline. Certyfikat nie nadaje uprawnień. Token KSeF jest innym poświadczeniem niż krótkotrwały token dostępu otrzymywany podczas komunikacji z API.

MF informuje o bezterminowym utrzymaniu tokenów KSeF. Przy wyborze metody dostępu sprawdź aktualne przepisy wykonawcze i dokumentację API. Dla używanej metody wyznacz właściciela odnowienia, unieważnienia i bezpiecznego przechowywania poświadczeń. Sekrety i pełne dane faktur nie powinny trafiać do zwykłych logów diagnostycznych.

TEST, DEMO i PROD muszą mieć oddzielną konfigurację, kolejki, archiwa i punkty synchronizacji. W TEST używaj danych zanonimizowanych. DEMO korzysta z rzeczywistych danych uwierzytelniających i uprawnień, ale faktury nie wywołują skutków prawnych. PROD służy rzeczywistym dokumentom, a nie fikcyjnym fakturom testowym.

Rezultatem jest potwierdzony dostęp w każdym wymaganym kontekście oraz próba utraty i przywrócenia dostępu. Przed startem porównaj faktyczny kontrakt API środowiska produkcyjnego z kontraktem użytym w testach. Daty planowanych wdrożeń z changelogu nie zastępują tej kontroli.

FA(3) jest strukturą standardowej faktury ustrukturyzowanej od 1 lutego 2026 r. KSeF otrzymuje XML, a nie PDF lub arkusz. Dla każdego obsługiwanego rodzaju faktury przygotuj własną mapę danych i przykład; jedno poprawne odwzorowanie zwykłej sprzedaży nie potwierdza obsługi zaliczek lub korekt.

W mapie zapisz pole źródłowe ERP, element struktury, regułę przekształcenia, warunek wypełnienia i osobę zatwierdzającą. Uwzględnij dane stron, daty, numer faktury, walutę, pozycje, stawki, kwoty, płatności oraz powiązania z wcześniejszymi fakturami. Określ, co zrobić, gdy danych brakuje.

Walidacja według XSD sprawdza zgodność ze schematem. Osobno skontroluj reguły biznesowe i podatkowe: zgodność sum, zaokrąglenia, kwalifikację transakcji i prawidłowość korekty. Rozróżnij pola obowiązkowe w schemacie, alternatywne warianty i pola wymagane dopiero w określonym przypadku.

Rezultatem jest zatwierdzona mapa i zestaw dokumentów testowych obejmujący wszystkie deklarowane scenariusze. Każdy odrzucony dokument powinien wskazywać użytkownikowi przyczynę i miejsce poprawy. Podstawy formatu opisuje poradnik XML i FA(3).

Obieg sprzedaży obejmuje przygotowanie i walidację XML, otwarcie sesji i szyfrowanie, wysyłkę, sprawdzanie wyniku każdej faktury oraz zapis numeru KSeF i UPO. Przyjęcie żądania do przetwarzania nie oznacza przyjęcia faktury. W sesji zawierającej wiele dokumentów część może zostać przyjęta, a część odrzucona.

Zachowaj dokładnie ten XML, który wysłano, oraz jego skrót. Trwały rejestr operacji powinien łączyć fakturę ERP z próbą wysyłki, referencjami i wynikiem. Numer własny faktury, techniczne referencje i numer KSeF są różnymi identyfikatorami.

Rozdziel stany: przygotowana, wysłana i przetwarzana, wynik nieznany, odrzucona, przyjęta oraz UPO zarchiwizowane. Faktura przyjęta z brakującym UPO wymaga pobrania poświadczenia, a nie ponownej wysyłki. UPO potwierdza odbiór przez KSeF; nie potwierdza akceptacji dostawy, zaksięgowania ani płatności.

Rezultatem jest możliwość odtworzenia losu jednej faktury bez przeglądania przypadkowych logów. Po przyjęciu zmiana danych wymaga właściwego obiegu korekty, a nie nadpisania zaakceptowanego XML.

Zakupy pobiera się z KSeF dla właściwego kontekstu i ról podmiotu. Faktury zakupowej otrzymanej z systemu nabywca nie wysyła ponownie jako własnej sprzedaży. Po pobraniu zachowaj XML i metadane, rozpoznaj kontrahenta oraz powiązania korekt, a następnie skieruj dokument do właściwego obiegu ERP.

Przy odbiorze przez KSeF datą otrzymania jest co do zasady dzień nadania numeru KSeF, a nie dzień późniejszego importu. Tryby awaryjne i przekazanie określonym odbiorcom poza systemem mają odrębne zasady. Pobranie faktury nie oznacza zatwierdzenia kosztu ani prawa do odliczenia VAT.

Pobieranie przyrostowe wymaga bezpiecznej granicy kompletności. Dokumentacja MF opisuje datę trwałego zapisu, PermanentStorage, oraz znacznik HWM wyznaczający zakres dostępnych dokumentów. Nie zastępuj go godziną z lokalnego zegara ani datą wystawienia faktury.

Obsłuż wszystkie strony, części eksportu i obcięte zakresy. Graniczne dokumenty mogą pojawiać się ponownie, dlatego deduplikuj po numerze KSeF w ramach właściwego środowiska i kontekstu. Punkt synchronizacji przesuwaj dopiero po trwałym zapisaniu całego przetworzonego zakresu.

Rezultatem jest uzgodniony zbiór zakupów, który pozostaje kompletny po opóźnionym zapisie, ponownym pobraniu i awarii importu. Jedna faktura widoczna w kilku rolach nie powinna tworzyć kilku zobowiązań do zapłaty.

Przykład: ERP zlecił wysyłkę, KSeF rozpoczął przetwarzanie, ale połączenie zerwało się przed otrzymaniem odpowiedzi. Zapisz wynik nieznany. Jeśli masz referencję faktury, odczytaj jej status; jeśli tylko referencję sesji, uzgodnij jej dokumenty. Nie twórz zmienionego XML wyłącznie po to, by ponowić transport.

Ponowienia wykonuj z trwałego rejestru, z jednym aktywnym wykonawcą dla dokumentu. Status duplikatu o kodzie 440 jest statusem przetwarzania faktury, a nie kodem HTTP. Wykorzystaj zwrócone powiązanie z pierwotnym dokumentem. Kontrola lokalna nadal jest potrzebna: biznesowo ta sama faktura może mieć różne dane techniczne.

Przy HTTP 429 respektuj wskazany czas oczekiwania Retry-After i ogranicz ruch odpowiedniej grupy żądań. Błąd XML wymaga poprawy danych. Brak uprawnień wymaga interwencji administratora. Przejściowe błędy odczytu można ponawiać z rosnącym odstępem; każda próba powinna zachowywać referencje i postęp.

Rezultatem jest kontrolowana kolejka interwencji i uzgadnianie ERP–rejestr–KSeF. Restart procesu powinien kontynuować wysyłkę, odpytywanie lub pobranie, zależnie od zapisanego stanu. Przywrócenie starej kopii bazy wymaga uzgodnienia dokumentów przyjętych już po jej wykonaniu.

Procedura zależy od przyczyny oraz oficjalnego komunikatu. Offline24 można stosować także z wyboru podatnika lub przy problemie z Internetem. Lokalna awaria ERP nie daje automatycznie terminu przewidzianego dla ogłoszonej awarii KSeF.

Poniższe terminy odpowiadają informacjom MF sprawdzonym 15 października 2026 r. Offline24 nie oznacza 24 godzin zegarowych. Kolejka musi liczyć dni robocze, śledzić komunikaty i alarmować przed upływem terminu. Jeżeli w międzyczasie ogłoszono kolejną awarię, zastosuj właściwe zasady przejścia między trybami.

W offline24, niedostępności i trybie awaryjnym datą wystawienia jest data wskazana w polu P_1. Data otrzymania zależy od trybu i kategorii odbiorcy. Dla krajowego odbioru w KSeF przy offline24 i niedostępności jest to zasadniczo nadanie numeru KSeF; w trybie awaryjnym co do zasady wcześniejszy faktyczny odbiór lub nadanie numeru.

Przy przekazaniu przed dosłaniem do KSeF odbiorcom wskazanym w art. 106gb ust. 4 wymagane są odpowiednie oznaczenia OFFLINE i CERTYFIKAT, z certyfikatem typu 2. Dla krajowego nabywcy z NIP MF opisuje potwierdzenie transakcji, które nie jest fakturą. Po przyjęciu wizualizacja przekazywana poza KSeF ma kod QR z numerem KSeF. Awaria całkowita nie wymaga QR KSeF ani dosłania faktury.

Rezultatem jest instrukcja dla pracownika: jak wybrać tryb, co wydać odbiorcy, kiedy dosłać dokument i kto kontroluje termin. Sam zapis XML w kolejce nie kończy tego etapu.

Dla każdego testu zapisz wejście, oczekiwany wynik, dowód wykonania i właściciela akceptacji. Użyj zanonimizowanych przykładów reprezentujących wszystkie deklarowane rodzaje faktur. Poniższe kryteria są rekomendacją odbioru wdrożenia, a nie urzędowym certyfikatem zgodności.

Najpierw odbierz testy w środowiskach nieprodukcyjnych. W produkcji zastosuj ograniczony pilotaż na rzeczywistych, poprawnie przygotowanych dokumentach i ustal, kto sprawdza wynik. Nie testuj powrotu do starego systemu przez ponowne wystawienie dokumentów już przyjętych w KSeF.

Monitoring powinien pokazywać wiek najstarszej faktury w kolejce, wyniki nieznane, odrzucenia, przyjęte faktury bez UPO, opóźnienie zakupów, obcięte eksporty i błędy dostępu. Dla każdego alarmu przypisz odbiorcę i czas reakcji. Progi dobierz do wolumenu i terminów firmy.

Utrzymanie obejmuje aktualizacje ERP i API, rotację kluczy, odnowienie poświadczeń, kopie oraz próby odtworzenia. Zmiana mapowania powinna uruchamiać testy wszystkich dotkniętych rodzajów faktur. Okresowo uzgadniaj liczbę i identyfikatory dokumentów między ERP, archiwum integracji i KSeF.

Rezultatem jest protokół odbioru, instrukcja incydentu i określony właściciel utrzymania. Dostawca powinien wskazać także sposób przekazania XML, UPO, historii operacji i konfiguracji przy zakończeniu współpracy.

Porównuj oferty dla tego samego zakresu. Na koszt wpływają liczba spółek i systemów, dostępność gotowego konektora, modyfikacje ERP, rodzaje faktur, jakość danych, wolumen, odbiór zakupów oraz wymagany poziom utrzymania. Sama cena licencji nie obejmuje automatycznie analizy, testów ani obsługi incydentów.

W zapytaniu ofertowym podaj wersję ERP, rozszerzenia, listę procesów, wolumen i okresy szczytu. Poproś o osobną wycenę wdrożenia, licencji, infrastruktury, utrzymania oraz zmian. Dołącz macierz mapowania i kryteria odbioru, aby porównać rzeczywiście podobne propozycje.

Ustal, kto poprawia dane źródłowe, pilnuje terminów offline i uzgadnia nieznane wyniki. Zapytaj o aktualizacje po zmianie API, czas reakcji, zakres odpowiedzialności i dostęp do danych po zmianie dostawcy. Bez tych ustaleń najtańsza oferta może obejmować tylko transport XML.

KSeFGPT udostępnia gotowe połączenie z Fakturownia.pl: konfigurację przez subdomenę i token API, podgląd, wysyłkę pojedynczą lub zbiorczą oraz sprawdzenie wyniku. Wybrane faktury z KSeF można także eksportować do Fakturowni. Zakres opisuje moduł Integracje.

Import plików jest inną ścieżką niż bezpośrednie połączenie z ERP. PDF wymaga odczytu OCR i weryfikacji danych, a CSV, XLS lub XLSX parsowania i mapowania kolumn. Do KSeF trafia przygotowany XML FA(3). Dostępność eksportu danych z konkretnego ERP trzeba potwierdzić w jego konfiguracji.

KSeFGPT nie ma obecnie bezpośredniej integracji z SAP. Automatyczny odczyt z SAP i zapis numeru KSeF w SAP pozostają planowanymi funkcjami bez ogłoszonej daty. Nie przenoś zakresu gotowego połączenia Fakturownia na dowolny ERP. Narzędzia fakturowania i wymiany danych nie zastępują pełnego systemu księgowego ani oceny podatkowej.

Odpowiedzi na pytania o zakres, potwierdzenia i odbiór wdrożenia.