Integracja KSeF z ERP i sklepem internetowym – poradnik

Integracja KSeF to dziś jeden z najważniejszych projektów IT w polskich firmach. Krajowy System e-Faktur przestał być ciekawostką i stał się obowiązkiem. Faktury muszą trafiać do systemu ministerstwa, a zakupowe trzeba z niego pobierać. Jeśli faktury wystawiasz w ERP, sprzedajesz przez sklep internetowy, a ofertę prowadzisz w CRM, ręczne przeklejanie dokumentów do aplikacji podatnika szybko stanie się wąskim gardłem. W tym poradniku pokazujemy, jak podejść do tematu praktycznie: od wyboru modelu wdrożenia, przez testy i uwierzytelnianie, po sesje, UPO, limity API i błędy, które najczęściej widzimy w projektach MŚP.

Najpierw krótko o terminach. Obowiązek objął dużych podatników od 1 lutego 2026 r., pozostałych podatników VAT od 1 kwietnia 2026 r., a mikroprzedsiębiorców (z ustawowo określonymi wyjątkami) obejmie od 1 stycznia 2027 r. Do tej daty mikroprzedsiębiorcy z miesięczną sprzedażą do 10 tys. zł brutto nie muszą wystawiać faktur w KSeF. Warto pamiętać, że odroczenie kar nie znosi samego obowiązku, więc nie warto odkładać przygotowań na ostatnią chwilę.

Integracja KSeF – od czego zacząć i jak wybrać podejście

Zanim ktokolwiek napisze linijkę kodu, zrób inwentaryzację. Odpowiedz sobie na kilka pytań:

Gdzie powstają faktury? W ERP, w sklepie internetowym, w systemie do rezerwacji, a może w kilku miejscach naraz?
Gdzie mają trafiać faktury kosztowe? Do księgowości wewnętrznej, do biura rachunkowego, do obiegu akceptacji?
Ile dokumentów miesięcznie wystawiasz i odbierasz, oraz czy są dni szczytowe (np. koniec miesiąca, Black Friday)?
Kto w firmie odpowiada za uprawnienia w KSeF i reakcję na odrzucone faktury?

Na tej podstawie wybierasz jedno z trzech podejść.

Gotowy moduł w ERP lub platformie sklepowej

Wiele popularnych systemów ERP i platform e-commerce ma własne moduły KSeF. To zwykle najszybsza droga, jeśli cała sprzedaż odbywa się w jednym systemie. Ograniczenie: moduł robi to, co przewidział producent. Jeśli faktury powstają w kilku miejscach albo chcesz automatycznie przekazywać numer KSeF do CRM, możesz trafić na ścianę.

Integrator lub platforma pośrednicząca

Zewnętrzna usługa przyjmuje faktury z Twoich systemów i sama komunikuje się z KSeF. Sprawdza się, gdy masz kilka źródeł faktur lub nietypowy system dziedzinowy. Kluczowe pytania do dostawcy: gdzie są przechowywane dane, jak wygląda obsługa błędów i jak szybko dostawca reaguje na zmiany w API.

Własna integracja przez KSeF API

KSeF API integracja na własną rękę daje pełną kontrolę: możesz połączyć ERP, sklep i CRM w jeden przepływ, z własną logiką ponowień i powiadomień. Wymaga jednak kompetencji programistycznych i utrzymania, bo dokumentacja API jest często aktualizowana. Dlatego integrację warto opierać na aktualnej specyfikacji OpenAPI i bibliotekach referencyjnych MF, a nie na artykułach sprzed roku.

Przykład z praktyki: hurtownia z Gliwic wystawia faktury w ERP, ale część sprzedaży detalicznej idzie przez sklep internetowy na innej platformie. Gotowy moduł obsłużyłby tylko ERP. Rozsądne rozwiązanie to jedna warstwa integracyjna, która zbiera faktury z obu źródeł, wysyła je do KSeF i odsyła numer KSeF tam, gdzie jest potrzebny.

Środowiska TEST, DEMO i produkcja – kolejność testów

KSeF API 2.0 udostępnia trzy środowiska:

TEST (api-test.ksef.mf.gov.pl) – do pierwszych prób i developmentu. Dane mogą być tu współdzielone między integratorami, więc nie umieszczaj w nich niczego wrażliwego.
DEMO, czyli środowisko przedprodukcyjne (api-demo.ksef.mf.gov.pl) – do testów zbliżonych do realnych warunków.
PROD (api.ksef.mf.gov.pl) – produkcja, gdzie faktury mają skutki prawne.

TEST i DEMO służą wyłącznie do testów. Nie wysyłaj tam faktur produkcyjnych ani prawdziwych danych klientów. Rekomendowana kolejność prac wygląda tak:

W TEST sprawdź uwierzytelnianie, otwarcie sesji i wysłanie pojedynczej faktury.
Nadal w TEST przetestuj przypadki brzegowe: korekty, faktury z wieloma stawkami VAT, faktury w walucie obcej, celowo błędne dokumenty.
W DEMO przeprowadź test całego procesu: od zamówienia w sklepie, przez fakturę w ERP, po zapis numeru KSeF i UPO.
Sprawdź wydajność: czy przy dziennym szczycie nie przekraczasz limitów.
Dopiero potem przełącz konfigurację na PROD, najlepiej najpierw dla ograniczonej grupy dokumentów.

Adres środowiska trzymaj w konfiguracji, a nie w kodzie. Pozwoli to uniknąć klasycznej wpadki, czyli wysłania testowych faktur na produkcję albo odwrotnie.

Uwierzytelnianie w KSeF 2.0 API: certyfikaty i tokeny

W KSeF 2.0 uwierzytelnianie jest odrębnym procesem, niezależnym od inicjalizacji sesji. Najpierw system potwierdza, kim jesteś i w czyim imieniu działasz, a dopiero potem otwierasz sesję do wysyłki faktur. Oficjalny przewodnik dla integratorów opisuje dwa główne mechanizmy: certyfikaty KSeF i tokeny KSeF.

Na co zwrócić uwagę w praktyce:

Bezpieczne przechowywanie sekretów. Token czy klucz prywatny certyfikatu nie może leżeć w pliku konfiguracyjnym sklepu ani w arkuszu. Użyj sejfu na sekrety albo przynajmniej szyfrowanego magazynu.
Zasada minimalnych uprawnień. Integracja sklepu, która tylko wystawia faktury sprzedażowe, nie potrzebuje uprawnień do pobierania wszystkich faktur kosztowych.
Kontrola ważności. Monitoruj daty ważności certyfikatów i ustaw przypomnienia z wyprzedzeniem.
Plan na rotację. Wymiana tokenu lub certyfikatu powinna być prostą procedurą, a nie awarią.

Ważna uwaga o tokenach: w podręczniku KSeF 2.0 z sierpnia 2026 r. Ministerstwo Finansów zrezygnowało z daty końcowej dla uwierzytelniania tokenem. Podręcznik nie jest jednak przepisem, a zmiana rozporządzenia w sprawie korzystania z KSeF jest w toku. Przed wdrożeniem sprawdź aktualny stan na ksef.podatki.gov.pl i projektuj integrację tak, by przejście na certyfikaty było możliwe bez przebudowy.

Wysyłanie i pobieranie faktur: sesje, numer KSeF, UPO

Automatyczne wysyłanie faktur do KSeF odbywa się w ramach sesji. Przewodnik integratora opisuje dwa rodzaje:

Sesja interaktywna – faktury wysyłane są pojedynczo, na bieżąco. Pasuje do sklepu internetowego, który wystawia fakturę zaraz po opłaceniu zamówienia.
Sesja wsadowa – wysyłka paczki wielu faktur naraz. Pasuje do ERP, który np. raz dziennie wystawia faktury zbiorcze lub abonamentowe.

Po przyjęciu faktury KSeF nadaje jej numer KSeF. To identyfikator, który powinien wrócić do systemu źródłowego i zostać zapisany przy dokumencie. Dzięki temu księgowość, obsługa klienta czy CRM wiedzą, że faktura jest skutecznie w systemie. Drugi ważny element to UPO, czyli urzędowe poświadczenie odbioru. Przechowuj je razem z fakturą, bo jest dowodem, że dokument trafił do KSeF.

Pamiętaj, że wysłanie faktury to nie to samo co jej przyjęcie. Proces jest asynchroniczny: najpierw wysyłasz dokument, potem sprawdzasz status przetwarzania. Integracja powinna więc rozróżniać co najmniej stany: przygotowana, wysłana, przyjęta (z numerem KSeF) i odrzucona (z opisem błędu).

Druga strona medalu to pobieranie faktur zakupowych. Dobrze zaprojektowana integracja cyklicznie pobiera nowe dokumenty, zapisuje je w ERP lub w obiegu akceptacji i zapamiętuje, które już pobrała, aby nie dublować kosztów. Tu właśnie przydaje się integracja KSeF z CRM lub systemem obiegu dokumentów: faktura od dostawcy może automatycznie trafić do osoby odpowiedzialnej za dane zlecenie.

Limity API i obsługa błędów

KSeF API ma limity żądań. Konkretne wartości zmieniają się wraz z dokumentacją, dlatego nie zakładaj ich na sztywno w kodzie. Endpointy GET /limits/context i GET /limits/subject zwracają limity dotyczące sesji i certyfikatów, więc integracja może je odczytywać. Na produkcji domyślne limity można zwiększyć wyłącznie na uzasadniony wniosek poparty realną potrzebą operacyjną, składany przez formularz kontaktowy z opisem zastosowania.

Jak projektować odporną integrację:

Kolejka zamiast wysyłki na żywo. Sklep zapisuje fakturę do kolejki, a osobny proces wysyła ją do KSeF. Klient nie czeka, a chwilowa niedostępność API nie blokuje sprzedaży.
Ponowienia z rosnącym odstępem. Przy przekroczeniu limitu lub błędzie sieci nie ponawiaj natychmiast w pętli.
Rozróżnianie błędów. Błąd techniczny (timeout) można ponowić. Błąd merytoryczny (np. niepoprawny NIP nabywcy) wymaga poprawki przez człowieka.
Idempotencja. Zanim ponowisz wysyłkę, sprawdź, czy faktura nie została już przyjęta. Inaczej ryzykujesz duplikat.
Powiadomienia. Odrzucona faktura powinna trafić do konkretnej osoby, a nie tylko do logu, którego nikt nie czyta.

Najczęstsze błędy przy integracji KSeF z ERP i sklepem internetowym

Z projektów, które widzimy w firmach MŚP, powtarza się kilka problemów:

Złe dane w systemie źródłowym. Integracja KSeF ze sklepem internetowym obnaża bałagan: brak NIP w zamówieniach firmowych, nazwy produktów pisane różnie, nieaktualne stawki VAT. KSeF nie poprawi danych za Ciebie.
Podwójne wystawianie faktur. Sklep i ERP mają osobne moduły i oba wysyłają tę samą fakturę. Ustal jedno źródło prawdy dla numeracji.
Brak zapisu numeru KSeF. Faktura poszła, ale numer nie wrócił do ERP. Przy korekcie czy reklamacji trzeba go potem szukać ręcznie.
Testy tylko na idealnych przypadkach. Wszystko działa, dopóki nie pojawi się korekta, zwrot częściowy czy faktura do paragonu.
Integracja oparta na nieaktualnej dokumentacji. Kod napisany pod wcześniejszą wersję API przestaje działać po zmianach. Śledź aktualną specyfikację i biblioteki referencyjne MF.
Brak właściciela procesu. Nikt nie odpowiada za uprawnienia, certyfikaty i odrzucone dokumenty. Problem wychodzi przy pierwszej awarii.
Pominięcie faktur kosztowych. Firma skupia się na sprzedaży, a dokumenty od dostawców nadal ktoś pobiera ręcznie.

FAQ – integracja KSeF w pytaniach i odpowiedziach

Czy mała firma potrzebuje własnej integracji przez API?

Nie zawsze. Jeśli faktury powstają w jednym systemie z dobrym modułem KSeF, często wystarczy on. Własna integracja ma sens, gdy łączysz kilka systemów lub masz nietypowe procesy.

Czy mogę testować na prawdziwych danych klientów?

Nie. Środowiska TEST i DEMO służą wyłącznie do testów, a w TEST dane mogą być współdzielone między integratorami. Używaj danych fikcyjnych.

Token czy certyfikat – co wybrać?

Zależy od aktualnych przepisów i Twojego procesu. Sytuacja wokół tokenów jest w toku zmian, więc sprawdź stan na ksef.podatki.gov.pl i zaprojektuj integrację tak, by obsługiwała oba mechanizmy.

Co zrobić, gdy przekraczamy limity API?

Najpierw zoptymalizuj integrację: kolejka, sesje wsadowe, rozsądne ponowienia. Jeśli realna potrzeba operacyjna wymaga więcej, na produkcji można złożyć uzasadniony wniosek o zwiększenie limitów.

Podsumowanie

Dobra integracja KSeF z ERP, sklepem internetowym i CRM to nie tylko wysyłka XML do ministerstwa. To uporządkowany proces: jedno źródło faktur, przemyślane uwierzytelnianie, testy w TEST i DEMO, zapis numeru KSeF i UPO, kolejka odporna na limity oraz jasna odpowiedzialność za błędy. Dzięki temu KSeF przestaje być kosztem zgodności, a staje się okazją do automatyzacji całego obiegu faktur.

Jeśli zastanawiasz się, które podejście będzie najlepsze dla Twojej firmy, albo masz już moduł, który nie obsługuje wszystkich źródeł faktur, porozmawiaj z zespołem CEBO.TECH. Przeanalizujemy Twoje systemy, wskażemy ryzyka i zaproponujemy integrację dopasowaną do skali Twojego biznesu.