Najgorszy moment na odkrycie problemu z KSeF to chwila po złożeniu zamówienia przez klienta. Sklep przyjął płatność, magazyn dostał dyspozycję wysyłki, klient czeka na fakturę, a integracja zwraca lakoniczne „błąd walidacji” albo wisi na statusie „w toku”. W e-commerce faktura nie jest osobnym dokumentem księgowym tworzonym kiedyś później. To element procesu sprzedaży, który musi działać przewidywalnie: od zamówienia, przez token, sesję, wysyłkę XML, status, numer KSeF, UPO, aż po korektę po zwrocie albo zmianie danych nabywcy.
Token nie jest hasłem do wszystkiego
Pierwszy błąd w integracjach KSeF polega na traktowaniu tokenu jak zwykłego klucza API do zewnętrznej usługi. To zły skrót myślowy. W KSeF trzeba rozdzielić co najmniej trzy warstwy: token KSeF, accessToken używany w komunikacji z API oraz uprawnienia podatnika w konkretnym kontekście, najczęściej po NIP. Jeżeli te pojęcia zleją się w jeden „sekret w konfiguracji sklepu”, prędzej czy później pojawi się problem z dostępem, rotacją albo diagnozą błędów 401 i 403.
W praktycznej integracji e-commerce najbezpieczniej przyjąć prostą zasadę: sklep nie powinien samodzielnie „rządzić” tokenami, jeśli nie ma do tego dobrze zaprojektowanego modułu bezpieczeństwa. Token powinien trafić do zaszyfrowanego magazynu sekretów, a aplikacja sklepu powinna korzystać z niego przez warstwę pośrednią, która kontroluje:
- zakres uprawnień — osobny dostęp do wystawiania faktur, osobny do odczytu, osobny do zarządzania poświadczeniami;
- kontekst podatnika — szczególnie ważny przy marketplace’ach, wielu spółkach albo sprzedaży w modelu multi-tenant;
- czas życia tokenów sesyjnych — accessToken wygasa szybciej, refreshToken pozwala odświeżyć dostęp bez pełnego uwierzytelnienia;
- rotację i unieważnianie — token z nadanymi zbyt szerokimi prawami nie powinien żyć latami;
- logowanie użycia — nie samego sekretu, lecz informacji: kto, kiedy i w jakim procesie wywołał operację.
Ważny szczegół: od 2026 roku tokeny i certyfikaty KSeF funkcjonują równolegle, ale długofalowo integracje powinny być projektowane pod certyfikaty KSeF. Budowanie nowego wdrożenia wyłącznie wokół tokenów to techniczny dług z datą wymagalności. Dla sklepu internetowego oznacza to jedno: jeśli teraz tworzysz integrację, nie zamykaj architektury na model certyfikatowy, podpis XAdES i obsługę poświadczeń firmowych.
Największy priorytet ma więc nie samo „podłączenie API”, ale właściwy podział odpowiedzialności. Platforma e-commerce powinna wysyłać dane sprzedażowe, identyfikator zamówienia, dane nabywcy i pozycje faktury. Moduł KSeF powinien odpowiadać za XML, szyfrowanie, sesję, statusy, UPO i błędy. Mieszanie tych warstw kończy się kodem, którego nikt nie chce dotykać po pierwszej większej awarii.
Status faktury to proces, nie jedna odpowiedź HTTP
KSeF nie działa jak klasyczne API, w którym wysyłasz żądanie i od razu dostajesz finalny wynik. Część operacji jest asynchroniczna. To bardzo ważne w e-commerce, bo klient i panel administracyjny sklepu oczekują jasnego komunikatu: faktura wystawiona, faktura w trakcie, faktura odrzucona, trzeba poprawić dane.
Poprawny model powinien mieć lokalną tabelę statusów, a nie pole tekstowe dopisywane przy zamówieniu. Minimum, które warto zapisać przy każdej fakturze, to:
- lokalny identyfikator zamówienia;
- numer dokumentu w sklepie lub ERP;
- hash XML przed wysyłką;
- numer referencyjny sesji;
- numer referencyjny faktury;
- aktualny status techniczny;
- numer KSeF po nadaniu;
- czas ostatniego odpytania;
- treść błędu technicznego lub walidacyjnego;
- informacja, czy pobrano UPO.
Dopiero taki zapis pozwala sensownie obsłużyć sytuacje graniczne. Faktura może zostać przyjęta do przetwarzania, ale nie mieć jeszcze numeru KSeF. Sesja może być zamknięta, ale UPO może pojawić się dopiero po późniejszym sprawdzeniu stanu. Przy wysyłce wsadowej część faktur może przejść, a część polec na walidacji. Jeżeli sklep zapisuje tylko „sukces” albo „błąd”, administrator będzie ręcznie porównywał zamówienia, pliki XML i panel KSeF. To proszenie się o chaos.
W sprzedaży detalicznej warto przyjąć twardą regułę: wysyłka towaru nie powinna zależeć od tego samego statusu co księgowe zamknięcie faktury. Jeżeli proces biznesowy pozwala wydać towar po płatności, sklep może kontynuować realizację zamówienia, ale faktura powinna pozostać w kolejce kontrolnej do momentu uzyskania numeru KSeF albo błędu wymagającego poprawy. Inaczej każda chwilowa niedostępność lub wolniejsza walidacja KSeF będzie blokować logistykę.
Dla małego sklepu zwykle wystarczy sesja interaktywna, czyli wysyłka pojedynczych faktur. Przy większej liczbie dokumentów — na przykład fakturowaniu zamówień z całego dnia, marketplace’ach, dropshippingu albo B2B z tysiącami pozycji — lepsza może być wysyłka wsadowa. Ma jednak swoją cenę organizacyjną: trzeba utrzymywać mapowanie faktur w paczce, liczyć hashe, pilnować limitów rozmiaru, obsłużyć częściowe błędy i jasno pokazać operatorowi, który dokument z paczki wymaga reakcji.
Najprostsza decyzja wdrożeniowa wygląda tak:
- jeżeli faktura powstaje od razu po zamówieniu — wybierz tryb interaktywny;
- jeżeli faktury są generowane okresowo — rozważ tryb wsadowy;
- jeżeli sklep ma częste korekty, zwroty i zmiany danych — zacznij od dobrego modelu statusów, a dopiero potem optymalizuj wydajność;
- jeżeli nie masz pewności, czy dane faktury są poprawne — waliduj XML lokalnie przed wysyłką, zamiast robić z KSeF walidator pierwszego kontaktu.
Korekty i błędy: tu integracja pokazuje, czy jest gotowa na produkcję
Prawdziwy test integracji zaczyna się nie przy pierwszej poprawnie wystawionej fakturze, lecz przy pierwszej korekcie. Klient podał zły NIP. Zamówienie zostało częściowo zwrócone. Rabat naliczono po fakcie. Płatność została anulowana po wygenerowaniu dokumentu. W e-commerce to nie wyjątki, tylko codzienność.
Faktura korygująca powinna być traktowana jako osobny dokument powiązany z fakturą pierwotną, a nie jako edycja starego rekordu. Po wysłaniu faktury do KSeF nie „poprawia się jej w miejscu”. Trzeba wygenerować właściwy dokument korekty, zachować odniesienie do dokumentu pierwotnego i przeprowadzić go przez ten sam proces: XML, walidacja, wysyłka, status, numer KSeF, UPO. To wymaga, aby sklep przechowywał historię zmian, a nie tylko aktualny stan zamówienia.
Najczęstsze błędy w integracji pojawiają się w czterech miejscach. Pierwsze to dane nabywcy: NIP, kraj, nazwa firmy, adres i typ odbiorcy muszą być walidowane przed wygenerowaniem XML. Drugie to pozycje faktury: rabaty, koszty dostawy, różne stawki VAT i korekty ilościowe muszą mieć jednoznaczne mapowanie na strukturę FA(3). Trzecie to ponawianie wysyłki: retry nie może tworzyć duplikatu dokumentu, jeżeli poprzednia próba została przyjęta, ale nie ma jeszcze finalnego statusu. Czwarte to komunikaty błędów: operator sklepu nie powinien widzieć surowego JSON-a, tylko konkretną instrukcję, co poprawić.
Dobrze zaprojektowany panel administracyjny powinien rozróżniać błędy:
- 401 — problem z autoryzacją, wygasły lub niepoprawny token dostępowy;
- 403 — brak uprawnień do kontekstu, niewłaściwy NIP, zbyt wąski zakres tokena albo certyfikatu;
- 400 — niepoprawne żądanie, często błąd w strukturze danych lub ponowne użycie operacji, której nie wolno powtarzać;
- błąd walidacji XML — dokument nie przechodzi schematu albo reguł semantycznych;
- timeout — nie oznacza automatycznie, że faktura nie została przyjęta; najpierw trzeba sprawdzić status po numerze referencyjnym;
- limit API lub rozmiaru — trzeba zmniejszyć paczkę, poprawić kolejkę albo wystąpić o podniesienie limitów, jeśli skala biznesu to uzasadnia.
Najbardziej ryzykowny mechanizm to automatyczne „wyślij ponownie po każdym błędzie”. Retry ma sens przy chwilowych problemach sieciowych, ale powinien działać z blokadą idempotencji: ten sam dokument, ten sam hash, ten sam lokalny identyfikator i kontrola, czy wcześniejsza operacja nie jest nadal przetwarzana. Bez tego można stworzyć duplikaty, zawiesić kolejkę albo doprowadzić do sytuacji, w której księgowość widzi coś innego niż sklep.
W praktyce warto wdrożyć kolejkę z trzema poziomami reakcji. Pierwszy poziom to automatyczne ponowienie po błędzie technicznym. Drugi to ponowne sprawdzenie statusu po czasie, bez ponownej wysyłki dokumentu. Trzeci to ręczna interwencja operatora, kiedy problem dotyczy danych faktury, uprawnień albo korekty wymagającej decyzji księgowej. To prosty podział, ale ratuje wiele godzin pracy.
W przypadku gotowych integracji opartych o REST API warto sprawdzić nie tylko endpoint „wyślij fakturę”, ale cały cykl życia dokumentu: generowanie XML FA(3), statusy, pobieranie UPO, korekty, obsługę błędów, retry, webhooks lub inne mechanizmy automatyzacji. Więcej informacji na: https://ksefservice.pl
FAQ
Czy sklep internetowy musi czekać na numer KSeF przed realizacją zamówienia?
Nie zawsze. Proces logistyczny można oddzielić od procesu księgowego, ale faktura powinna pozostać w kontrolowanej kolejce aż do uzyskania numeru KSeF albo błędu wymagającego poprawy.
Czy token KSeF wystarczy do integracji z API?
Nie w sensie architektonicznym. Token jest tylko jednym z elementów uwierzytelnienia i uprawnień. Integracja musi jeszcze obsłużyć accessToken, refreshToken, kontekst podatnika, statusy sesji, szyfrowanie, XML i błędy.
Kiedy wybrać wysyłkę wsadową zamiast interaktywnej?
Wysyłka wsadowa ma sens przy dużej liczbie faktur generowanych okresowo, na przykład po zakończeniu dnia sprzedażowego. Przy fakturach wystawianych pojedynczo po zamówieniu prostsza i zwykle bezpieczniejsza operacyjnie jest sesja interaktywna.
Czy korektę faktury można zrobić przez edycję starego dokumentu?
Nie. Korekta powinna być osobnym dokumentem powiązanym z fakturą pierwotną. Integracja musi przeprowadzić ją przez pełny proces: wygenerowanie XML, wysyłkę, sprawdzenie statusu, nadanie numeru KSeF i pobranie UPO.
Od czego zacząć wdrożenie REST API KSeF w e-commerce?
Najpierw uporządkuj dane faktury i statusy lokalne. Dopiero potem podłącz wysyłkę. Najdroższy błąd to integracja, która potrafi wysłać poprawny dokument testowy, ale nie umie obsłużyć korekty, timeoutu, braku uprawnień ani faktury wiszącej w przetwarzaniu.
