Faktury z Allegro w KSeF 2026 bez ręcznego CSV (jak połączyć Allegro, BaseLinker i KSeF krok po kroku)

Problem nie leży w KSeF, tylko w tym, co dzieje się wokół niego

Kiedy klient sklepu internetowego przychodzi do nas z pytaniem „jak podłączyć KSeF do BaseLinkera”, zwykle po dwóch rozmowach okazuje się, że chodzi o zupełnie inny problem. Integracja techniczna jest prostą częścią zadania. Trudniejsze jest zaprojektowanie procesu tak, żeby faktura nie wystawiła się dwa razy dla tego samego zamówienia, kiedy w grę wchodzi zwrot, reklamacja, ręczna korekta konsultanta albo zwykła zmiana statusu w BaseLinkerze, która wygląda niewinnie, a w praktyce odpala trigger po raz drugi.

KSeF nie wybacza takich pomyłek. System nie ma mechanizmu „nadpisz poprzedni dokument”. Każda faktura, która trafi do Krajowego Systemu e-Faktur, dostaje numer i zostaje w systemie na stałe. Jeśli trzeba coś poprawić, nie edytuje się pierwotnego dokumentu, tylko wystawia fakturę korygującą. To oznacza, że błąd w logice automatyzacji nie znika sam, tylko mnoży się w czasie: po miesiącu masz dziesiątki zduplikowanych dokumentów i księgowość, która ręcznie próbuje ustalić, który numer jest „ten prawdziwy”.

Mapa procesu: od kliknięcia „kupuję teraz” do numeru KSeF

Zanim zaprojektuje się regułę antyduplikacyjną, warto rozrysować cały łańcuch zdarzeń, bo większość błędów bierze się z tego, że ktoś pominął jedno ogniwo. W typowym sklepie wielokanałowym wygląda to tak: zamówienie powstaje na Allegro, trafia do BaseLinkera przez integrację API, system pobiera informację o płatności (albo z operatora płatności, albo ze statusu Allegro), zmienia status zamówienia na „opłacone”, generuje dokument sprzedażowy i wysyła go dalej, do KSeF, a równolegle do klienta i do etykiety kurierskiej.

Allegro udostępnia REST API z limitami zapytań na minutę, więc przy sklepie, który obsługuje kilkaset zamówień dziennie, zwykłe odpytywanie co minutę o nowe zamówienia prędzej czy później zacznie się wysypywać albo dublować dane. W praktyce lepiej opierać integrację na webhookach zdarzeń zamówienia i dopiero po ich otrzymaniu pobierać szczegóły, zamiast robić ciągły polling. To drobna rzecz, ale decyduje o tym, czy BaseLinker dostaje jedno zdarzenie na zamówienie, czy trzy, co później trzeba będzie filtrować już na poziomie triggera fakturowania.

Jeden trigger, nie trzy: jak zaprojektować regułę bez dubli

Naiwne podejście to ustawienie automatu na „zmiana statusu zamówienia na zapłacone → wystaw fakturę”. Działa świetnie do pierwszego zwrotu częściowego. Wtedy status zamówienia w BaseLinkerze często wraca do „w realizacji”, a po uregulowaniu sprawy ponownie zmienia się na „zapłacone”. Automat, który reaguje wyłącznie na zmianę statusu, odpali się po raz drugi i spróbuje wystawić drugą fakturę dla tego samego zamówienia.

Dlatego trigger, który faktycznie działa w produkcji, musi sprawdzać dwa warunki jednocześnie: status „zapłacone” oraz brak istniejącego numeru KSeF przypisanego do tego zamówienia. Numer KSeF zapisujemy w polu niestandardowym zamówienia zaraz po jego otrzymaniu z systemu. To pole pełni funkcję blokady idempotencji: zanim cokolwiek zostanie wysłane do KSeF, automat najpierw sprawdza, czy pole jest puste. Jeśli nie jest, nic się nie dzieje, niezależnie od tego, ile razy status zamówienia zmieni się tam i z powrotem.

Druga rzecz, o której firmy zapominają, to mapowanie statusów osobno dla każdego kanału sprzedaży. „Zapłacone” na Allegro Smart nie znaczy tego samego co „zapłacone” w sklepie własnym z płatnością przelewem, gdzie księgowanie wpłaty może trwać dzień czy dwa. Jeden uniwersalny trigger dla wszystkich kanałów to najczęstsza przyczyna fałszywie pozytywnych wystawień faktury przed faktycznym zaksięgowaniem wpłaty.

Zwroty i korekty: miejsce, gdzie automatyzacja najczęściej się sypie

Tu trzeba być szczery: w pełni automatyczne korekty faktur w sklepie z realnym wolumenem zwrotów to zły pomysł. Automat dobrze radzi sobie z prostym przypadkiem: pełny zwrot całego zamówienia, jedna stawka VAT, brak rabatów. Gorzej, kiedy zwrot jest częściowy, dotyczy jednej pozycji z kilku, a do tego klient skorzystał z kodu rabatowego rozłożonego proporcjonalnie na cały koszyk. Wtedy przeliczenie kwoty netto, VAT i podstawy korekty wymaga decyzji, a nie tylko podstawienia liczb do szablonu.

Nasze podejście w takich wdrożeniach jest konsekwentne: automat generuje dla zwrotu gotowy szkic faktury korygującej z wyliczonymi kwotami, ale wysłanie do KSeF wymaga ręcznej akceptacji osoby z działu księgowości, przynajmniej dla zwrotów częściowych albo powyżej ustalonego progu kwotowego. Automat robi 80% pracy, czyli zbiera dane, liczy proporcje, przygotowuje dokument. Decyzję o ostatecznym kształcie korekty zostawiamy człowiekowi. To nie jest kompromis z lenistwa, tylko wniosek z obserwacji: błędna korekta w KSeF to kolejny dokument do poprawienia, a nie coś, co da się po cichu usunąć.

Jeśli chcesz zobaczyć, jak wygląda to w praktyce na pełnym procesie faktur, a nie tylko w kontekście e-commerce, warto przejrzeć automatyzację faktur jako osobny temat, bo logika idempotencji i akceptacji wyjątków powtarza się też poza sklepami internetowymi, np. w fakturach kosztowych.

Natywny moduł KSeF w BaseLinkerze czy pośrednik (n8n, Make)?

BaseLinker rozwija własną integrację z KSeF w ramach modułu faktur, ale zakres dostępnych funkcji zależy od wariantu konta i tego, z jakiego dokładnie modułu fakturowania korzysta dany sklep. W praktyce, przy prostszych konfiguracjach wbudowana ścieżka wystarcza. Przy bardziej złożonych procesach, szczególnie tam, gdzie trzeba połączyć kilka kanałów sprzedaży z różną logiką VAT albo z zewnętrznym systemem księgowym innym niż domyślny, lepiej dołożyć warstwę pośredniczącą opartą na n8n lub Make, która pilnuje reguł, loguje błędy walidacji i pozwala wstrzymać wysyłkę do ręcznej weryfikacji, zamiast polegać wyłącznie na wbudowanym mechanizmie.

Terminy KSeF 2026, o których sklep internetowy musi pamiętać

Obowiązkowy KSeF wchodzi etapami. Od 1 lutego 2026 obejmuje firmy, których wartość sprzedaży w 2024 roku przekroczyła 200 mln złotych. Od 1 kwietnia 2026 obowiązek dotyczy pozostałych czynnych podatników VAT, czyli w praktyce większości średnich i małych sklepów internetowych. To oznacza, że właściciel sklepu, który dziś generuje kilkadziesiąt zamówień dziennie, formalnie ma jeszcze trochę czasu, ale testowanie integracji warto zacząć wcześniej, niż wynika to z twardego terminu.

Powód jest prozaiczny: sklep internetowy generuje dziesiątki albo setki faktur dziennie, więc błąd w logice triggera, który w firmie usługowej wystawiającej dziesięć faktur miesięcznie ujawniłby się po kilku tygodniach, w e-commerce wychodzi na jaw po dwóch dniach i od razu w dużej skali. Uruchomienie automatu na próbie 20-30 realnych zamówień, zanim włączy się go dla całego ruchu, to najtańsza polisa ubezpieczeniowa, jaką można sobie kupić przed kwietniem 2026.

Osobny temat to faktura do paragonu z NIP nabywcy. Jeśli sprzedaż online wiąże się z wystawieniem paragonu fiskalnego zawierającego NIP klienta, fakturę można wystawić tylko na ten sam NIP, który widnieje na paragonie. W BaseLinkerze dane NIP pochodzą czasem z innego pola niż dane do faktury wpisane przez klienta przy składaniu zamówienia, zwłaszcza gdy zamówienie wpada z Allegro, gdzie dane do faktury klient uzupełnia osobno. Rozjazd między tymi polami to kolejne miejsce, gdzie automat potrafi próbować wystawić dokument niezgodny z paragonem, a KSeF go odrzuci na etapie walidacji.

Krótka checklista przed włączeniem automatu

Zanim przełączysz cały ruch na automatyczne fakturowanie, warto przejść przez kilka punktów, które w naszych wdrożeniach oszczędzają najwięcej czasu później:

• Zmapuj statusy zamówień osobno dla każdego kanału sprzedaży i zaznacz, który status faktycznie oznacza zaksięgowaną wpłatę, a nie tylko deklarację płatności.
• Dodaj pole niestandardowe z numerem KSeF i datą wystawienia jako blokadę przed podwójnym wysłaniem dokumentu.
• Oddziel ścieżkę zwrotów i korekt od ścieżki standardowego wystawiania, z wymaganą akceptacją człowieka przy zwrotach częściowych.
• Przetestuj cały łańcuch na próbce 20-30 realnych zamówień, zanim włączysz automat dla całego ruchu.
• Ustaw alert e-mail lub na Slacka przy błędzie walidacji KSeF, żeby dowiedzieć się o problemie w ciągu godzin, nie podczas kwartalnego audytu.

Jeśli dopiero porządkujesz całą automatyzację sklepu, nie tylko sam obszar faktur, warto spojrzeć na to szerzej, bo logistyka, obsługa zwrotów i fakturowanie często opierają się na tych samych danych źródłowych z BaseLinkera. Więcej o tym, jak to ogarnąć całościowo, znajdziesz przy automatyzacji e-commerce.