Faktury z marketplace’ów nie psują procesu dlatego, że jest ich dużo. Psują go wtedy, gdy wszystkie próbują wejść do KSeF jednocześnie, bez priorytetów, bez kontroli błędów i bez rozdzielenia tego, co trzeba wysłać natychmiast, od tego, co może poczekać kilka minut. Przy dużej sprzedaży na Allegro, Amazonie, Empiku, Kauflandzie czy własnym sklepie problemem nie jest samo wystawienie dokumentu. Problemem jest kolejka wysyłki faktur do KSeF, która ma działać przewidywalnie także wtedy, gdy zamówienia wpadają falami: po kampanii promocyjnej, po imporcie paczki zamówień z marketplace’u albo po nocnej synchronizacji stanów.
Kolejka nie może być zwykłą listą „do wysłania”
Najczęstszy błąd wygląda niewinnie: system generuje fakturę, zapisuje ją w bazie i wrzuca rekord do tabeli pending. Worker pobiera pierwszą z brzegu pozycję i wysyła ją do KSeF. Przy kilkuset fakturach dziennie to działa. Przy kilkunastu tysiącach zaczyna się loteria.
Dobra kolejka powinna mieć co najmniej kilka stanów, a nie tylko „wysłano” i „nie wysłano”. W praktyce potrzebne są:
- oczekuje na komplet danych — np. brakuje NIP-u, adresu, waluty, kraju nabywcy albo powiązania z zamówieniem,
- gotowa do walidacji — faktura ma dane, ale jeszcze nie przeszła kontroli struktury,
- gotowa do wysyłki — dokument przeszedł walidację techniczną i biznesową,
- wysłana do KSeF, czeka na wynik — system nie powinien wysyłać jej drugi raz tylko dlatego, że odpowiedź nie przyszła natychmiast,
- odrzucona do poprawy — wymaga zmiany danych, a nie kolejnej próby wysyłki,
- do ponowienia — błąd jest tymczasowy, więc faktura może wrócić do obiegu,
- zablokowana ręcznie — ktoś z księgowości lub obsługi sprzedaży musi podjąć decyzję.
To rozróżnienie jest ważniejsze niż wybór konkretnej technologii kolejki. RabbitMQ, Kafka, SQS, Redis Streams czy kolejka w PostgreSQL mogą działać dobrze albo źle. O jakości decyduje model procesu.
Przy marketplace’ach trzeba też oddzielić moment utworzenia faktury od momentu wysyłki do KSeF. Zamówienie może być opłacone, anulowane, częściowo zwrócone, scalone z innym zamówieniem albo rozbite na kilka przesyłek. Jeśli faktura trafia do KSeF zbyt wcześnie, korekty pojawią się szybciej niż sprzedaż. Jeśli trafia zbyt późno, księgowość traci kontrolę nad terminowością.
Najbezpieczniejsza reguła jest prosta: faktura trafia do kolejki wysyłkowej dopiero wtedy, gdy system ma potwierdzony obowiązek jej wystawienia i pełny zestaw danych wymaganych przez schemat. To brzmi sucho, ale w realnym wdrożeniu oznacza konkretne decyzje: czy fakturować po płatności, po wysyłce, po zamknięciu dnia, czy po potwierdzeniu danych z platformy. Dla sprzedaży masowej często wygrywa model mieszany: faktury B2B i żądania faktury idą szybciej, dokumenty wymagające uzupełnienia danych czekają w osobnej kolejce.
Priorytety, limity i ponowienia muszą być zaprojektowane przed pierwszym pikiem sprzedaży
KSeF nie powinien być traktowany jak zwykły endpoint API, do którego można strzelać bez opamiętania. Po stronie systemu sprzedażowego trzeba założyć limity, przerwy techniczne, odpowiedzi opóźnione, błędy walidacji i sytuacje, w których jedna grupa dokumentów blokuje drugą. Ministerstwo Finansów przewiduje indywidualne oraz czasowe zwiększanie limitów API KSeF 2.0 dla integratorów, ale takie zwiększenie jest przyznawane na wniosek i w uzasadnionych przypadkach, więc nie zastępuje poprawnej architektury kolejki.
W kolejce dla dużej sprzedaży marketplace’owej najważniejsze są trzy priorytety.
Pierwszy to faktury, których terminowość ma znaczenie operacyjne. To dokumenty potrzebne klientowi biznesowemu, działowi obsługi, księgowości albo procesowi rozliczeń. One nie powinny stać za tysiącami prostych faktur konsumenckich wygenerowanych z nocnego importu.
Drugi to faktury po poprawkach. Jeżeli użytkownik ręcznie uzupełnił NIP, adres albo dane nabywcy, dokument powinien szybko wrócić do wysyłki. Inaczej ludzie zaczynają obchodzić system: eksportują pliki, wysyłają dokumenty poza procesem albo tworzą duplikaty.
Trzeci to ponowienia po błędach technicznych. Nie wolno mieszać ich z błędami merytorycznymi. Jeśli KSeF chwilowo nie odpowiada, kolejka powinna zastosować backoff, czyli wydłużać odstępy między próbami. Jeśli błąd dotyczy danych faktury, kolejne wysłanie tego samego dokumentu niczego nie naprawi. Taki rekord musi trafić do naprawy, nie do pętli.
Dobre zasady ponowień wyglądają praktycznie tak:
- po błędzie sieciowym: ponowienie po krótkim czasie, potem coraz rzadziej,
- po przekroczeniu limitu: zatrzymanie tempa wysyłki, nie agresywne ponawianie,
- po błędzie walidacji: blokada i komunikat dla osoby lub modułu odpowiedzialnego za dane,
- po niejednoznacznym statusie: sprawdzenie wyniku operacji przed utworzeniem nowej próby,
- po ręcznej korekcie: powrót do walidacji, a nie automatyczny skrót do wysyłki.
Granica jest tu ostra: nie projektuje się kolejki pod średnią liczbę zamówień dziennie. Projektuje się ją pod najgorsze dwie godziny miesiąca. Marketplace potrafi zrzucić dużą paczkę zamówień po opóźnionej synchronizacji, kampania reklamowa może potroić sprzedaż, a awaria integracji może przesunąć wysyłkę faktur na późny wieczór. Jeśli kolejka nie ma kontroli tempa, priorytetów i osobnych ścieżek błędów, nadrobi zaległość w najbardziej ryzykowny sposób: chaotycznie.
Warto też dodać licznik wieku dokumentu. Faktura, która czeka 5 minut, nie jest problemem. Faktura, która czeka 6 godzin, wymaga reakcji. Faktura, która czeka dobę, powinna być widoczna na panelu operacyjnym bez żadnego filtrowania. Sama liczba elementów w kolejce mówi mało. Ważniejsze są: najstarszy niewysłany dokument, liczba faktur zablokowanych przez dane, liczba ponowień oraz procent odrzuceń po walidacji.
Marketplace daje zamówienie, ale nie zawsze daje fakturę gotową do KSeF
Dane z marketplace’ów bywają nierówne. Raz przychodzą kompletne, raz mają adres zapisany w nietypowym formacie, raz klient poda firmę bez NIP-u, raz platforma zwraca numer identyfikacyjny w polu, którego integracja wcześniej nie używała. Do tego dochodzą zamówienia zagraniczne, różne stawki VAT, dostawy, prowizje, płatności zbiorcze, korekty, zwroty i rozbicie jednego koszyka na kilka dokumentów.
Dlatego kolejka wysyłki do KSeF powinna być poprzedzona warstwą normalizacji danych. To w niej system decyduje, czy zamówienie jest gotowe do fakturowania, czy wymaga uzupełnienia. Wysyłka do KSeF nie jest miejscem na zgadywanie. Jeśli adres jest niepełny, NIP ma zły format albo brakuje informacji o nabywcy, trzeba zatrzymać dokument wcześniej.
Przy dużej liczbie zamówień sprawdzają się proste, twarde reguły:
- jedno źródło prawdy dla statusu faktury — nie osobno w sklepie, ERP i module integracji,
- idempotencja — ponowienie operacji nie może utworzyć drugiej faktury dla tego samego zdarzenia sprzedażowego,
- mapowanie błędów na działania — komunikat techniczny musi mówić, kto ma coś zrobić: system, księgowość, obsługa klienta czy administrator,
- blokada duplikatów — szczególnie przy retry po timeoutach i po ponownym imporcie zamówień,
- audyt zmian — przy fakturach z marketplace’u trzeba widzieć, kto i dlaczego zmienił dane przed wysyłką.
Najbardziej zdradliwe są duplikaty. Jeżeli worker wysłał dokument, ale nie zapisał poprawnie statusu, kolejna próba może potraktować fakturę jako niewysłaną. Dlatego przy każdej fakturze potrzebny jest stabilny identyfikator biznesowy: marketplace, numer zamówienia, numer przesyłki lub wewnętrzny numer dokumentu. Sam techniczny identyfikator rekordu w bazie nie wystarcza, bo przy reimportach i migracjach potrafi się zmienić.
Osobna sprawa to moment przejścia na obowiązkowy KSeF. Obowiązek wystawiania faktur w KSeF ruszył etapowo: od 1 lutego 2026 r. dla podatników ze sprzedażą brutto powyżej 200 mln zł w 2024 r., od 1 kwietnia 2026 r. dla pozostałych podatników, a dla najmniejszych podatników z miesięczną sprzedażą dokumentowaną fakturami do 10 000 zł brutto przesunięto obowiązek do 1 stycznia 2027 r. To oznacza, że system kolejkowy nie powinien mieć jednej globalnej flagi „KSeF włączony”. Lepiej zastosować reguły zależne od podmiotu, daty, typu dokumentu i statusu podatnika. W grupach kapitałowych albo firmach obsługujących kilka marek sprzedażowych jedna spółka może mieć inny harmonogram i inną skalę ryzyka niż druga.
Najlepszy start to nie przebudowa wszystkiego naraz. Najpierw trzeba usunąć blokery, które faktycznie zatrzymają wysyłkę: brak idempotencji, brak rozróżnienia błędów, brak panelu faktur zablokowanych i brak metryk wieku kolejki. Dopiero potem warto optymalizować wydajność workerów, liczbę równoległych procesów czy wielkość paczek. Szybka kolejka, która szybko produkuje błędy, nie jest przewagą. Jest mnożnikiem bałaganu.
Więcej informacji na: https://ksefservice.pl/blog/
FAQ
Czy faktury z marketplace’u trzeba wysyłać do KSeF natychmiast po zamówieniu?
Nie zawsze. Bezpieczniejszy jest moment, w którym zamówienie ma komplet danych i wiadomo, że powstał obowiązek wystawienia faktury. Przy części platform będzie to płatność, przy innych wysyłka, a przy B2B często dopiero poprawne potwierdzenie danych nabywcy.
Czy jedna kolejka wystarczy dla wszystkich faktur?
Technicznie tak, ale operacyjnie to słaby pomysł przy dużej skali. Lepiej rozdzielić kolejki lub przynajmniej priorytety dla faktur gotowych, błędnych, ponawianych i wymagających ręcznej poprawy.
Co jest ważniejsze: szybkość wysyłki czy kontrola błędów?
Najpierw kontrola błędów. Szybkość ma sens dopiero wtedy, gdy system nie tworzy duplikatów, poprawnie rozpoznaje statusy i nie ponawia dokumentów odrzuconych z powodów merytorycznych.
Od czego zacząć projektowanie kolejki?
Od mapy statusów i decyzji granicznych. Trzeba ustalić, kiedy faktura jest gotowa do wysyłki, kiedy ma czekać, kiedy wraca do ponowienia, a kiedy wymaga interwencji człowieka. Bez tego każda technologia kolejki będzie tylko szybszą wersją nieuporządkowanego procesu.