Przejdź do treści
dvnt.io

CRM, ERP i systemy firmowe15 min czytania2954 słówRedakcja dvnt

Integracja z KSeF — API KSeF dla firmy z własnym systemem: trzy drogi i jak wybrać

API KSeF dla firmy z własnym systemem: program księgowy jako brama, gotowy łącznik albo własna integracja. Co obsłużyć, co deklarują moduły i jak wybrać.

API KSeF to interfejs Krajowego Systemu e-Faktur, przez który systemy firm wysyłają faktury ustrukturyzowane, pobierają faktury zakupu i odbierają numer KSeF oraz urzędowe poświadczenie odbioru — bez ręcznego logowania do aplikacji ministerstwa. Dla większości małych firm KSeF jest sprawą programu do faktur: włączasz integrację w abonamencie i temat znika. Ten tekst jest dla firmy, w której faktura powstaje gdzie indziej — w sklepie internetowym, w systemie ERP, w platformie B2B, we własnej aplikacji albo w zamówieniu z Allegro — i która pyta, jak to podłączyć.

Odpowiedź ma trzy warianty: program księgowy jako brama, gotowy łącznik platformy lub integratora, albo własna integracja z API KSeF 2.0. Wybór zależy od tego, gdzie faktura powstaje, ile ich jest i czy numer KSeF musi wrócić do systemu, który ją wystawił.

KSeF w jednym akapicie — co jest obowiązkowe i od kiedy

Faktury między firmami wystawiasz w KSeF; faktury dla konsumentów możesz, ale nie musisz. Według strony Ministerstwa Finansów Od kiedy trzeba wystawiać faktury w KSeF (stan 30.04.2026) obowiązek objął od 1 lutego 2026 r. firmy, które w 2024 r. miały sprzedaż powyżej 200 mln zł z VAT, a od 1 kwietnia 2026 r. pozostałych — z jednym wyjątkiem: do 31 grudnia 2026 r. faktury można wystawiać poza KSeF, jeśli ich miesięczna suma sprzedaży z VAT nie przekracza 10 000 zł. Według kalendarium MF od 1 stycznia 2027 r. KSeF jest obowiązkowy dla wszystkich. Co to oznacza dla samej księgowości i jak sprawdzić, czy Twój program jest gotowy, opisujemy w tekście o programie księgowym; tu zajmujemy się tylko tym, co dzieje się między Twoim systemem a API.

Trzy fakty z pytań i odpowiedzi MF o KSeF 2.0 (stan 8.10.2026). Po pierwsze: „Wystawianie w KSeF faktur na rzecz konsumentów nie jest obowiązkowe” — to zdanie decyduje o tym, co ma robić sklep. Po drugie: kary za błędy w KSeF odroczono do 1 stycznia 2027 r., a faktury z kas fiskalnych, w tym paragony z NIP do 450 zł, do 31 grudnia 2026 r. nie muszą przechodzić przez KSeF. Po trzecie: firmy mogą tworzyć własne rozwiązania do obsługi KSeF bez podpisywania umów z ministerstwem — droga trzecia jest otwarta dla każdego, kto ma programistę.

Gdzie powstaje faktura — mapa systemów w firmie

O drodze integracji decyduje miejsce, w którym faktura powstaje, a nie miejsce, w którym jest księgowana. Księgowość widzi fakturę na końcu; KSeF chce ją w momencie wystawienia, bo według MF przy wysyłce online datą wystawienia jest data przesłania do systemu. Dlatego pierwsze pytanie nie brzmi „jaki mamy program księgowy”, tylko „kto naciska przycisk wystaw”.

W firmach, z którymi pracujemy, faktura powstaje w jednym z pięciu miejsc:

  1. Program do faktur lub księgowy. Usługi, projekty, kilkadziesiąt faktur miesięcznie. Integrację z KSeF daje dostawca programu; to przypadek z tekstu o programie do faktur i nie wymaga niczego, co opisujemy niżej.
  2. System ERP. Faktura jest wynikiem procesu: zamówienie, wydanie magazynowe, rozliczenie. Numer KSeF musi wrócić do ERP, bo tam żyje dokument, a jego brak zatrzymuje kolejne kroki. Co to jest ERP i kiedy mała firma go potrzebuje, opisujemy w tekście o systemie ERP.
  3. Sklep internetowy. Faktura powstaje automatycznie do zamówienia, często bez udziału człowieka, w setkach sztuk; większość odbiorców to konsumenci, mniejszość — firmy z NIP.
  4. Platforma B2B lub własna aplikacja. Klient sam składa zamówienie i sam pobiera fakturę z panelu. Wszyscy odbiorcy mają NIP, więc każda faktura jest fakturą do KSeF. Jak działa taka platforma, opisujemy w tekście o platformie B2B.
  5. Marketplace. Zamówienie pochodzi z Allegro, faktura powstaje w systemie, który je obsługuje — w sklepie, w Base.com albo w programie księgowym podłączonym do konta.

Miejsce 1 nie potrzebuje żadnej drogi, miejsca 3 i 5 najczęściej dostają gotowy łącznik, miejsce 4 i część miejsca 2 kończą we własnej integracji, a program księgowy jako brama łączy wszystko, co nie ma własnego modułu. Zanim wybierzesz, policz dwie rzeczy: ile faktur B2B miesięcznie wychodzi z każdego miejsca i czy po wysyłce ktoś potrzebuje numeru KSeF z powrotem w systemie źródłowym.

Mapa bez liczb. Po lewej pięć źródeł faktury: program do faktur lub księgowy; system ERP; sklep internetowy; platforma B2B lub własna aplikacja; marketplace (Allegro). Po prawej trzy drogi: droga 1 program księgowy jako brama; droga 2 gotowy łącznik (moduł platformy lub integrator); droga 3 własna integracja z API KSeF 2.0. Strzałki: program do faktur prowadzi wprost do KSeF (integracja dostawcy, bez drogi); ERP prowadzi do drogi 1 (gdy księgowość wystawia) albo do drogi 3 (gdy numer KSeF musi wrócić do ERP); sklep internetowy prowadzi do drogi 2 (moduł platformy) albo do drogi 1 (program księgowy podłączony do sklepu); platforma B2B lub własna aplikacja prowadzi do drogi 3 albo do drogi 1; marketplace prowadzi do drogi 2 (Base.com, moduł sklepu) albo do drogi 1. Na dole dwa pytania kontrolne: ile faktur B2B miesięcznie z każdego miejsca; czy numer KSeF musi wrócić do systemu źródłowego.
Gdzie powstaje faktura — pięć miejsc i trzy drogi do KSeFŹródło: Opracowanie własne dvnt na podstawie projektów integracyjnych i dokumentacji MF (ksef.podatki.gov.pl, stan 20.10.2026)

Droga 1: program księgowy jako brama do KSeF

Program księgowy z własnym API może być bramą do KSeF dla każdego systemu, który potrafi w nim utworzyć fakturę. Twój sklep, ERP albo aplikacja nie rozmawia z ministerstwem; tworzy fakturę w programie księgowym przez jego API, a program wysyła ją dalej, odbiera numer KSeF i trzyma UPO. Dla Ciebie integracja z KSeF staje się integracją z programem, który i tak masz.

Co deklarują dostawcy (dokumentacja z 20.10.2026). wFirma w artykule o integracji z KSeF pisze, że faktury wystawione przez API i integracje — wymienia BaseLinker, Apilo i sklepy internetowe — „są automatycznie wysyłane do KSeF w momencie ich utworzenia w systemie wFirma.pl”, pod dwoma warunkami: wysyłka jest włączona w konfiguracji, a użytkownik klucza API ma aktywną autoryzację w KSeF. Osobne przełączniki decydują o fakturach B2B i B2C, a faktury zakupu system może pobierać „codziennie w godzinach nocnych”. Przez API nie da się utworzyć wersji roboczej, więc faktura z integracji idzie do KSeF od razu. inFakt na stronie o KSeF opisuje podłączenie przez profil zaufany, wysyłkę jednym kliknięciem i automatyczne pobieranie faktur kosztowych z KSeF; deklaruje, że korzystanie z KSeF w inFakcie jest „całkowicie bezpłatne”. iFirma w opisie integracji ze Shoperem obiecuje automatyczną wysyłkę faktur do KSeF, a następnie do kupującego, oraz sprawdzenie NIP w GUS przed wystawieniem; do 100 zamówień miesięcznie w pakiecie Faktura+ bez dopłat.

Ta droga wystarcza, gdy faktur B2B jest kilkadziesiąt, góra kilkaset miesięcznie, system źródłowy ma gotowy łącznik z Twoim programem księgowym albo potrafi wywołać jego API, a numer KSeF wystarczy, że istnieje w programie księgowym. Przestaje wystarczać, gdy klient w panelu Twojej platformy B2B ma zobaczyć fakturę z kodem QR i numerem KSeF od razu po zamówieniu, gdy ERP blokuje proces bez numeru, albo gdy faktur jest tyle, że limity i opóźnienia programu księgowego stają się Twoim problemem. Dwie rzeczy sprawdź przed decyzją: czy API programu księgowego zwraca numer KSeF i status wysyłki, i co dzieje się z fakturą, którą KSeF odrzuci — kto o tym wie i gdzie to widać.

Droga 2: gotowy łącznik — moduł platformy albo integrator

Jeśli faktura powstaje w sklepie na platformie abonamentowej albo w systemie wielokanałowym, łącznik z KSeF najpewniej już tam jest — i to on wyznacza, co możesz, a czego nie. Poniżej deklaracje producentów z ich dokumentacji (odczyt 20.10.2026); deklaracja to nie to samo, co działanie w Twoim sklepie, więc pod tabelą jest lista rzeczy do sprawdzenia.

Shoper. Według poradnika Shoper Faktury i Magazyn (22.01.2026, aktualizacja 28.01.2026) integrację włączasz w ustawieniach modułu, uwierzytelniając się tokenem albo certyfikatem typu 1 z własnym kluczem prywatnym; do faktur offline potrzebny jest drugi certyfikat z przeznaczeniem „Podpis linku do weryfikacji wystawcy”. Wysyłka może być automatyczna albo ręczna z poziomu faktury. Importu faktur zakupu nie ma — wydatki wpisujesz ręcznie z numerem KSeF.

IdoSell. Pomoc IdoSell opisuje konfigurację per NIP z dwoma certyfikatami (uwierzytelnienia i podpisu linku), każdy ważny 2 lata. Integracja działa w trybie offline: datą wystawienia jest data z dokumentu (pole P_1), a nie data przekazania. Faktury z automatów i wystawiane grupowo idą wsadowo co 10 minut, pojedyncza wystawiona ręcznie — od razu; etapu kontroli przed wysyłką nie ma. Faktury dla osób prywatnych i faktury OSS to osobne, nieobowiązkowe przełączniki; proformy, paragony i faktury uproszczone nie idą wcale. Dokumenty wystawione w czasie awarii KSeF wysyła po jej ustaniu, a testować pozwala na Demo wyłącznie na zanonimizowanych danych. Jeśli faktury wystawiasz w zewnętrznym systemie z własną integracją, w IdoSell nie konfigurujesz nic.

Base.com (dawniej BaseLinker). Baza wiedzy Base.com opisuje token generowany osobno dla każdego środowiska, z samym uprawnieniem do wystawiania faktur. Faktury mogą iść natychmiast po utworzeniu albo ręcznie i zbiorczo, do 12 miesięcy wstecz. Dwa filtry: „Przekazuj faktury bez NIP nabywcy” (możesz wyłączyć wysyłkę faktur konsumenckich) i wybór serii numeracji, które idą do KSeF. Po akceptacji wydruk dostaje kod QR, numer KSeF, datę i status; faktury w przetwarzaniu system sprawdza co 60 minut, odrzucone odblokowuje do ponownej wysyłki. Tryb offline obsługuje automatycznie, ale wymaga do tego certyfikatu z opcją podpisu linku weryfikacji wystawcy; faktur zakupu nie pobiera. Strona integracji deklaruje, że funkcja jest w abonamencie bez dodatkowych opłat.

WooCommerce. Na wordpress.org KSeF Add-on do Flexible Invoices ma wersję 2.5.3 z 13.10.2026 i ponad 700 aktywnych instalacji; wymaga wtyczki Flexible Invoices co najmniej 6.2.0, a automatyczne generowanie faktur — wersji PRO. Uwierzytelnia tokenem albo, od wersji 2.5.0, certyfikatem; faktury, które nie wyszły z powodu problemów z siecią, ponawia co 8 godzin. WordPress i WooCommerce wdrażamy wyłącznie na życzenie klienta; jeśli sklep już na nich stoi, to jest jego droga.

Tabela: sześć wierszy, pięć kolumn (uwierzytelnienie; wysyłka; faktury B2C; numer KSeF i QR na dokumencie; tryb offline i błędy). Shoper Faktury i Magazyn (poradnik 28.01.2026): token lub certyfikat typu 1 plus certyfikat offline; automatyczna lub ręczna; brak informacji o filtrze B2C; QR tak, numer KSeF nie opisany; certyfikat offline, brak opisu obsługi błędów. IdoSell (pomoc, stan 20.10.2026): dwa certyfikaty po 2 lata, per NIP; wsadowo co 10 minut, ręcznie od razu; B2C opcjonalnie; dwa kody QR przed numerem, jeden kod i numer po rejestracji; tryb offline domyślnie, dokumenty z czasu awarii wysyłane po jej ustaniu. Base.com (pomoc, stan 20.10.2026): token per środowisko; natychmiast lub ręcznie i zbiorczo do 12 miesięcy wstecz; filtr „bez NIP nabywcy” i wykluczanie serii; QR, numer, data, status na wydruku; offline automatycznie z certyfikatem podpisu linku, status co 60 minut, odrzucone do ponownej wysyłki, korekty tak, bez dopłat. WooCommerce Flexible Invoices KSeF Add-on (v2.5.3, 13.10.2026, 700+ instalacji): token lub certyfikat; jedna lub zbiorczo, automat w PRO; brak informacji o filtrze B2C; numer KSeF i status w panelu; ponowienie co 8 godzin po błędzie sieci. wFirma jako brama (pomoc, stan 20.10.2026): certyfikat z wFirma, własny lub token; faktury z API natychmiast; osobne przełączniki B2B i B2C; numer KSeF w liście i na wydruku; tryb offline w osobnym artykule. iFirma plus Shoper (strona integracji, stan 20.10.2026): nie opisano; automatyczna do KSeF i do kupującego; nie opisano; nie opisano; nie opisano; do 100 zamówień bez dopłat.
Co deklarują łączniki z KSeF — sześć modułów, odczyt 20.10.2026Źródło: Dokumentacja producentów: shoper.pl/learn, pomoc.idosell.com, base.com/pomoc, wordpress.org/plugins, pomoc.wfirma.pl, ifirma.pl — odczyt 20.10.2026; deklaracje, nie testy

Cztery rzeczy do sprawdzenia w swoim sklepie, zanim uznasz temat za zamknięty. Czy faktury dla konsumentów są wyłączone — jeśli moduł nie ma takiego filtra, wysyłasz do KSeF dobrowolnie wszystko, a to ma konsekwencje dla korekt i zwrotów. Czy kod QR i numer KSeF trafiają na PDF, który dostaje klient firmowy, czy tylko do panelu. Co widzisz, gdy KSeF odrzuci fakturę, i kto to zobaczy w sobotę. I czy w Twoim łączniku uwierzytelnienie opiera się na tokenie: Shoper i wFirma w swoich poradnikach piszą, że tokeny będą obsługiwane tylko do końca 2026 r., podczas gdy MF w pytaniach i odpowiedziach (stan 8.10.2026) podaje, że uwierzytelnianie tokenem zostaje w KSeF 2.0 bezterminowo, a wygenerowany token jest ważny do czasu unieważnienia przez użytkownika. Niezależnie od tego, która wersja się utrzyma, przejście na certyfikat zaplanuj — i tak jest potrzebny do faktur offline.

Droga 3: własna integracja z API KSeF — co trzeba obsłużyć

Własna integracja z API KSeF 2.0 ma sens, gdy faktura musi powstać i wrócić z numerem KSeF w Twoim systemie, a żaden łącznik tego nie zrobi tak, jak proces tego wymaga. Dokumentację dla integratorów ministerstwo publikuje w repozytorium CIRFMF/ksef-api (README z 5.05.2026) z przykładami w C# i Javie oraz specyfikacją OpenAPI. Poniżej nie ma kodu — jest lista rzeczy, które Twój system musi umieć, w kolejności z API. Jeśli pojęcia API i tokenu są dla Ciebie nowe, zacznij od tekstu API — co to jest.

Środowiska. Według opisu środowisk (16.03.2026) są trzy: testowe api-test.ksef.mf.gov.pl, przedprodukcyjne Demo api-demo.ksef.mf.gov.pl i produkcyjne api.ksef.mf.gov.pl. Test i Demo „służą wyłącznie do testowania integracji” i nie wolno wysyłać tam faktur produkcyjnych ani prawdziwych danych podmiotów; tylko test dopuszcza certyfikaty samopodpisane, Demo odpowiada konfiguracji produkcyjnej, a produkcja ma gwarantowane SLA. Z kalendarium MF: dokumentację API 2.0 opublikowano 30.06.2025, otwarte testy ruszyły 30.09.2025, Demo 15.10.2025, KSeF 2.0 na produkcji od 1.02.2026.

Uwierzytelnienie. Według opisu uwierzytelniania system najpierw pobiera challenge (ważny 10 minut), a potem potwierdza tożsamość jedną z dwóch metod: podpisem XAdES (kwalifikowany podpis osoby, pieczęć firmy, profil zaufany albo certyfikat KSeF, który „nie jest certyfikatem kwalifikowanym”) lub tokenem KSeF zaszyfrowanym kluczem publicznym systemu. W zamian dostaje parę: accessToken o krótkiej ważności („kilkanaście minut”, pole exp) i refreshToken ważny do 7 dni. Twój system musi więc umieć odświeżać token i obsłużyć stan „uwierzytelnianie w toku”: na Demo i produkcji system czeka na potwierdzenie statusu certyfikatu u jego wystawcy (OCSP/CRL), co według dokumentacji jest normalne. Certyfikat KSeF według MF jest ważny najwyżej 2 lata, a tokeny z KSeF 1.0 nie działają w 2.0.

Sesja i wysyłka. Fakturę wysyłasz w sesji. Sesja interaktywna to: otwarcie z deklaracją schematu FA(3) i symetrycznym kluczem AES-256 zaszyfrowanym kluczem publicznym MF (dokumentacja zaleca nowy klucz na każdą sesję), wysłanie zaszyfrowanej faktury z dwoma hashami, asynchroniczna weryfikacja, zamknięcie sesji i zbiorcze UPO. Sesja żyje 12 godzin. Sesja wsadowa to paczka ZIP dzielona na części do 100 MB, wgrywana pod adresy wskazane przez system; czas na wysyłkę to 20 minut razy liczba części. Dokumentacja poleca ją firmom, „które generują wiele faktur dziennie”. Limity domyślne: faktura do 1 MB (3 MB z załącznikiem), 10 000 faktur w sesji, 500 faktur w jednym identyfikatorze zbiorczym; na produkcji limity podnosi się tylko uzasadnionym wnioskiem.

Status, numer KSeF, UPO. Wysyłka nie kończy się odpowiedzią „OK”. Twój system odpytuje stan sesji i poszczególnych faktur (osobny endpoint zwraca te odrzucone z opisem błędu), a faktura przyjęta dostaje numer KSeF. Według opisu numeru ma on 35 znaków: NIP sprzedawcy, data przyjęcia do przetwarzania, 12 znaków technicznych i dwuznakowa suma kontrolna CRC-8. Ten numer musi wrócić do dokumentu w Twoim systemie, bo według MF faktura jest uznana za otrzymaną w momencie nadania numeru, a fakturę korygującą — jak podaje dokumentacja trybów offline — przesyła się dopiero po nadaniu numeru KSeF dokumentowi pierwotnemu. UPO według dokumentacji sesji pobierasz per faktura albo zbiorczo po zamknięciu sesji; MF w FAQ dodaje, że archiwizowanie UPO nie jest wymagane, a KSeF przechowuje faktury 10 lat od końca roku wystawienia. Warto je jednak zapisać — to dowód w sporze o datę.

Tryby offline i kody QR. To część, którą najłatwiej pominąć i najdrożej dopisać później. Według opisu trybów offline są trzy: offline24 (decyzja Twoja; wysyłka do następnego dnia roboczego po dacie wystawienia), offline (niedostępność ogłoszona przez MF; do następnego dnia roboczego po jej zakończeniu) i awaryjny (do 7 dni roboczych po zakończeniu awarii), plus awaria całkowita, po której faktur do KSeF nie dosyła się wcale. Fakturę offline oznaczasz flagą offlineMode: true, a jej wizualizacja musi mieć dwa kody QR: według opisu kodów QR KOD I prowadzi do weryfikacji faktury po hashu SHA-256, a KOD II podpisuje link kluczem prywatnym certyfikatu KSeF typu Offline — „Generowanie wymaga posiadania aktywnego certyfikatu KSeF typu Offline”. Faktura online dostaje tylko KOD I z numerem KSeF pod spodem. Twój system musi więc: wystawiać z własną datą P_1, generować oba kody, pilnować terminów, które przesuwają się przy kolejnych awariach, i ponawiać wysyłkę po powrocie systemu.

Schemat ośmiu kroków w pionie z limitami po prawej. Krok 1 środowisko: test api-test.ksef.mf.gov.pl, Demo api-demo.ksef.mf.gov.pl, produkcja api.ksef.mf.gov.pl; test i Demo wyłącznie do testów integracji. Krok 2 uwierzytelnienie: challenge ważny 10 minut; XAdES (podpis, pieczęć, profil zaufany, certyfikat KSeF) albo token KSeF; accessToken kilkanaście minut, refreshToken do 7 dni; certyfikat KSeF ważny do 2 lat. Krok 3 otwarcie sesji: schemat FA(3); klucz AES-256 zaszyfrowany kluczem publicznym MF; sesja interaktywna 12 godzin. Krok 4 wysyłka: faktura do 1 MB, z załącznikiem do 3 MB; do 10 000 faktur w sesji; wsadowo ZIP w częściach do 100 MB, czas wysyłki 20 minut razy liczba części, do 500 faktur w identyfikatorze zbiorczym. Krok 5 status: weryfikacja asynchroniczna; osobny odczyt faktur odrzuconych z opisem błędu. Krok 6 numer KSeF: 35 znaków, NIP sprzedawcy, data RRRRMMDD, 12 znaków technicznych, suma CRC-8; wraca do dokumentu w systemie. Krok 7 UPO: per faktura lub zbiorcze po zamknięciu sesji. Krok 8 offline: offline24 do następnego dnia roboczego; offline do następnego dnia roboczego po końcu niedostępności; awaryjny do 7 dni roboczych; flaga offlineMode true; KOD I z hasha SHA-256, KOD II z certyfikatu typu Offline.
Integracja z API KSeF 2.0 — przebieg i limity, które Twój system musi obsłużyćŹródło: github.com/CIRFMF/ksef-api (README 5.05.2026, środowiska 16.03.2026) i ksef.podatki.gov.pl — pytania i odpowiedzi (8.10.2026); odczyt 20.10.2026

Jedna uwaga praktyczna: terminy offline liczą się w dniach roboczych, więc monitoring i alert o fakturach bez numeru KSeF są częścią wdrożenia, nie dodatkiem. Jak projektujemy takie zależności między systemami, opisujemy w tekście o automatyzacji procesów.

Faktury ze sklepu i z marketplace — konsument, firma, Allegro

Sklep internetowy nie musi wysyłać do KSeF faktur dla konsumentów; musi wysyłać faktury dla firm, a odróżnia je po NIP nabywcy. Dwa źródła MF: strona Konsumenci i osoby fizyczne (stan 30.10.2025) mówi, że „wystawianie faktur B2C (na rzecz osób prywatnych – konsumentów) w KSeF jest dobrowolne”, a FAQ dodaje, że podmioty identyfikowane na fakturze przez NIP mają w KSeF dostęp do swoich faktur zakupu. W ścieżce zamówienia pole NIP przestaje więc być kosmetyką: od niego zależy, czy faktura idzie do KSeF.

Trzy decyzje projektowe, które z tego wynikają. Po pierwsze, walidacja NIP w koszyku — błędny NIP to faktura w KSeF wystawiona na nieistniejący podmiot, a MF pisze, że system nie podpowie sprzedawcy, czy kontrahent ma dostęp do KSeF; stąd sprawdzanie w GUS przed wystawieniem, które reklamuje iFirma. Po drugie, moment wystawienia: sklep, który generuje fakturę przy zamówieniu, w KSeF wystawia ją w chwili wysyłki do systemu, więc anulowanie zamówienia po tej chwili jest korektą, nie usunięciem — stąd w IdoSell data z dokumentu w trybie offline, a w Base.com opcja wysyłki ręcznej zamiast natychmiastowej. Po trzecie, faktura dla firmy musi dotrzeć do klienta z kodem QR: według MF faktura online przekazana poza KSeF, na przykład jako PDF, potrzebuje jednego kodu, a zagraniczny nabywca bez polskiego NIP do KSeF się nie zaloguje.

Allegro dotyka obu stron tej samej firmy. Jako kupujący od Allegro: moderator Allegro w FAQ o KSeF (2.11.2025, aktualizacja 11.02.2026) pisze, że faktury za opłaty Allegro „dodatkowo” przesyła do KSeF i że sprzedaż dla konsumentów „nadal będzie fakturowana po staremu”. Jako sprzedający: komunikat w pomocy Allegro mówi kupującym firmom, że faktury od sprzedawców znajdą w KSeF i że „ta zmiana nie wymaga od Ciebie żadnych dodatkowych działań na koncie Allegro” — faktury wystawia sprzedawca, nie Allegro. Dla Ciebie znaczy to: faktura do zamówienia z Allegro powstaje w systemie, który obsługuje Twoje zamówienia, i tam musi być NIP kupującego z danych zamówienia. Skąd go wziąć przez Allegro API i jak liczyć cały kanał, opisujemy w tekście o integracji z Allegro.

Ile pracy i jak wybrać drogę — jak do tego podchodzimy

Decyzja o drodze to trzy pytania zadane w tej kolejności: gdzie faktura powstaje, czy numer KSeF musi tam wrócić i czy istniejący łącznik robi to tak, jak wymaga proces. Jeśli numer nie musi wracać, droga pierwsza lub druga wystarcza i nie ma sensu budować własnej. Własna integracja wygrywa dopiero wtedy, gdy faktura jest częścią procesu w systemie, który budowaliśmy albo budujemy — w platformie B2B, w aplikacji z własnym fakturowaniem, w ERP bez modułu — i gdy łącznik pośredni dokładałby trzeci system do dwóch, które już muszą się zgadzać.

Tak liczymy pracę, gdy ktoś prosi nas o własną integrację — składowe i orientacyjne widełki w dniach pracy zespołu; to szacunek z projektów integracyjnych, nie cennik, i każdy projekt wyceniamy osobno. Uwierzytelnienie, odświeżanie tokenów, sesja i szyfrowanie: 2–4 dni, bo schemat jest opisany, a biblioteki MF dają punkt odniesienia. Mapowanie danych faktury z Twojego systemu na schemat FA(3) z walidacją: 5–15 dni i to jest największa niewiadoma — zależy od tego, ile wariantów faktur wystawiasz (zaliczkowe, zbiorcze, korekty, OSS) i jak czyste są dane. Status, numer KSeF zwrotnie, UPO i obsługa odrzuceń: 3–5 dni. Tryby offline, dwa kody QR, pilnowanie terminów i ponawianie: 4–8 dni. Testy na środowisku testowym i Demo z danymi, które nie są prawdziwe, oraz monitoring po starcie: 3–5 dni. Razem: od trzech do ośmiu tygodni jednego zespołu, z czego połowę gotowy łącznik daje w abonamencie. Dlatego pytanie „czy budować” zadajemy dopiero po pytaniu „czy numer musi wracać”.

Dwie części. Góra: ścieżka decyzji. Pytanie 1: gdzie powstaje faktura? Jeśli w programie do faktur lub księgowym: integracja dostawcy, koniec. Pytanie 2: czy numer KSeF musi wrócić do systemu, który ją wystawił? Jeśli nie: droga 1 program księgowy jako brama albo droga 2 gotowy łącznik, zależnie od tego, czy platforma ma moduł. Pytanie 3: czy istniejący łącznik obsługuje Twój proces (filtr B2C po NIP, QR i numer na PDF dla klienta, obsługa odrzuceń, offline)? Jeśli tak: droga 2. Jeśli nie: droga 3 własna integracja z API KSeF 2.0. Dół: pięć składowych własnej integracji z orientacyjnymi widełkami w dniach pracy zespołu, szacunek dvnt, bez cen: uwierzytelnienie, tokeny, sesja i szyfrowanie 2 do 4 dni; mapowanie danych na FA(3) i walidacja 5 do 15 dni, największa niewiadoma; status, numer KSeF zwrotnie, UPO i odrzucenia 3 do 5 dni; tryby offline, kody QR, terminy i ponawianie 4 do 8 dni; testy na środowisku testowym i Demo oraz monitoring 3 do 5 dni; razem 17 do 37 dni, czyli od trzech do ośmiu tygodni.
Którą drogą do KSeF — trzy pytania i składowe własnej integracjiŹródło: Opracowanie własne dvnt, szacunek z projektów integracyjnych, stan 20.10.2026; składowe wg dokumentacji CIRFMF/ksef-api

Od czego zacząć, niezależnie od drogi. Policz faktury B2B z każdego miejsca, w którym powstają, za ostatnie trzy miesiące. Sprawdź na własnym koncie to, co jest w tabeli: wystaw fakturę testową na Demo, zobacz PDF, odrzuć ją celowo błędnym NIP i zobacz, kto się o tym dowie. Jeśli po tym teście wiesz, że numer KSeF musi wrócić do Twojego systemu, a łącznik tego nie robi — to jest moment na rozmowę o własnej integracji. Robimy je jako część oprogramowania na zamówienie: aplikacji webowych, platform B2B i sklepów, w których fakturowanie jest jednym z procesów, a nie osobnym systemem; kiedy w ogóle warto budować zamiast kupić, rozbieramy w tekście o dedykowanym oprogramowaniu. Jakie oprogramowanie firma wybiera funkcja po funkcji — w przewodniku po aplikacjach dla firm.

Najczęstsze pytania o integrację z KSeF

Co to jest API KSeF?

To interfejs Krajowego Systemu e-Faktur, przez który system firmy (sklep, ERP, aplikacja, program księgowy) wysyła faktury ustrukturyzowane w schemacie FA(3), odbiera numer KSeF i UPO oraz pobiera faktury zakupu — bez logowania do aplikacji ministerstwa. Obowiązująca wersja to API KSeF 2.0; dokumentację z przykładami w C# i Javie ministerstwo publikuje w repozytorium CIRFMF/ksef-api, a środowisko produkcyjne działa od 1 lutego 2026 r.

Czy sklep internetowy musi wystawiać faktury w KSeF?

Faktury dla firm (nabywca z NIP) — tak, na zasadach ogólnych. Faktury dla konsumentów — nie: według Ministerstwa Finansów wystawianie faktur B2C w KSeF jest dobrowolne. Sklep musi więc odróżnić oba przypadki po NIP nabywcy w zamówieniu; moduły platform (Shoper, IdoSell, Base.com) mają własne ustawienia, czy faktury bez NIP wysyłać.

Co to jest numer KSeF i UPO?

Numer KSeF to 35-znakowy identyfikator nadawany fakturze przyjętej przez system: NIP sprzedawcy, data przyjęcia, 12 znaków technicznych i suma kontrolna. Od jego nadania faktura jest uznana za otrzymaną przez nabywcę i dopiero wtedy można wystawić do niej korektę. UPO to urzędowe poświadczenie odbioru, dostępne dla pojedynczej faktury albo zbiorczo dla sesji; MF pisze, że jego archiwizowanie nie jest wymagane.

Czy faktura dla konsumenta trafia do KSeF?

Tylko jeśli tak zdecydujesz. Strona MF „Konsumenci i osoby fizyczne” mówi, że zarówno przed 1 lutego 2026 r., jak i po tej dacie wystawianie faktur B2C w KSeF jest dobrowolne. Jeśli Twój łącznik nie ma filtra po NIP, może wysyłać wszystko — sprawdź to ustawienie, bo każda faktura w KSeF oznacza korektę w KSeF przy zwrocie.

Co jeśli KSeF nie działa — tryb offline?

Są trzy tryby: offline24 (Twoja decyzja, wysyłka do następnego dnia roboczego po wystawieniu), offline przy ogłoszonej niedostępności (do następnego dnia roboczego po jej końcu) i awaryjny przy ogłoszonej awarii (do 7 dni roboczych po jej zakończeniu). Faktura offline dostaje datę z dokumentu i dwa kody QR, z których drugi wymaga certyfikatu KSeF typu Offline; po powrocie systemu trzeba ją dosłać w terminie.

Ile kosztuje integracja z KSeF?

W programie do faktur i w modułach platform (Base.com, inFakt deklarują to wprost) integracja jest w abonamencie bez dopłat. Własna integracja z API to według naszego szacunku od trzech do ośmiu tygodni pracy zespołu, a koszt zależy od liczby wariantów faktur do zmapowania na FA(3), od tego, czy numer KSeF musi wracać do Twojego systemu, i od obsługi trybów offline. Każdy taki projekt wyceniamy osobno.

Powiązane artykuły