Vulcode
Integracja z KSeF: harmonogram obowiązku i podłączenie własnego systemu do API 2.0
Blog
Technologia

Integracja z KSeF: harmonogram obowiązku i podłączenie własnego systemu do API 2.0

Kto i od kiedy wystawia e-faktury w KSeF, co zmienia się w firmie i jak zintegrować sklep, panel albo ERP: uwierzytelnianie, wysyłka i odbiór faktur, limity, tryby offline i kody QR

DualFroz - VulCode CEODualFroz - VulCode CEO·28 września 2026·20 min czytania

Integracja z KSeF jest potrzebna każdej firmie, która wystawia faktury z własnego systemu: sklepu internetowego, panelu, ERP albo aplikacji do rozliczeń. Od 1 lutego 2026 r. wszyscy podatnicy odbierają faktury przez Krajowy System e-Faktur, od 1 kwietnia 2026 r. wystawiają je w nim wszystkie firmy poza korzystającymi z okresu przejściowego, a 1 stycznia 2027 r. okres przejściowy się kończy. Dokument wysłany do KSeF staje się fakturą dopiero po nadaniu mu numeru KSeF, z wyjątkiem ustawowych trybów offline.

Pierwsza część tekstu opisuje harmonogram i zmiany w codziennym fakturowaniu. Druga jest dla zespołów, które podłączają własny system: uwierzytelnianie w API 2.0, wysyłka i odbiór faktur, limity i to, co system musi umieć, gdy KSeF albo internet nie działa.

W skrócie
  • Od 1 lutego 2026 r. faktury w KSeF wystawiają firmy, których sprzedaż wraz z VAT przekroczyła w 2024 r. 200 mln zł, a od 1 kwietnia 2026 r. pozostałe. Odbiór faktur przez KSeF obowiązuje wszystkich od 1 lutego 2026 r.
  • Do 31 grudnia 2026 r. poza KSeF można wystawiać faktury do łącznej kwoty 10 000 zł brutto w miesiącu oraz faktury z kas rejestrujących.
  • Według obecnych przepisów kary za naruszenia mają być stosowane od 1 stycznia 2027 r. Projekt ustawy opublikowany 23 września 2026 r. przesuwa ten termin na 1 stycznia 2028 r., ale do jego uchwalenia obowiązuje data z ustawy.
  • Integracja z API KSeF 2.0 obejmuje uwierzytelnienie, szyfrowaną wysyłkę plików XML w strukturze FA(3), pobranie UPO i przyrostową synchronizację faktur kosztowych.
  • System musi obsłużyć tryby offline: oznaczanie faktur, dwa kody QR, certyfikat KSeF do trybu offline i dosyłanie faktur w ustawowym terminie.
i
Informacja

Stan na 28 września 2026 r. Tekst opisuje przepisy i dokumentację techniczną z perspektywy wykonawcy oprogramowania i nie jest poradą prawną ani podatkową. Terminy KSeF były już przesuwane, a dokumentacja API jest regularnie aktualizowana, dlatego przed wdrożeniem sprawdź aktualne komunikaty na ksef.podatki.gov.pl i historię zmian API.

Harmonogram KSeF na koniec września 2026 r.

Obowiązkowy KSeF wprowadziła ustawa z 5 sierpnia 2025 r. o zmianie ustawy o VAT (Dz. U. poz. 1203), która ustaliła obecne terminy. Na dzień publikacji wyglądają one tak:

Najważniejsze daty

DataCo się dzieje
1 lutego 2026 r.Obowiązek wystawiania faktur w KSeF dla firm, których sprzedaż wraz z VAT przekroczyła w 2024 r. 200 mln zł. Obowiązek odbierania faktur przez KSeF dla wszystkich. Struktura FA(3) obowiązuje od tego dnia
1 kwietnia 2026 r.Obowiązek wystawiania faktur w KSeF dla pozostałych podatników
do 31 grudnia 2026 r.Poza KSeF można wystawiać faktury do łącznej wartości 10 000 zł brutto w miesiącu, faktury z kas rejestrujących i paragony uznane za faktury uproszczone
1 stycznia 2027 r.Koniec okresu przejściowego. Numer KSeF w tytule przelewu między czynnymi podatnikami VAT. Według obecnych przepisów początek stosowania kar

Limit 10 000 zł z art. 145m ustawy zmieniającej działa od faktury: podatnik traci prawo do wystawiania faktur poza KSeF, począwszy od tej, którą przekroczył miesięczny próg. Do limitu nie wlicza się faktur z kas rejestrujących ani paragonów do 450 zł uznanych za faktury uproszczone, co Ministerstwo Finansów potwierdza w pytaniach i odpowiedziach o KSeF 2.0.

Kary opisuje art. 106ni ustawy o VAT. Za wystawienie faktury poza KSeF wbrew obowiązkowi albo za niedosłanie faktury offline w terminie naczelnik urzędu skarbowego nakłada karę do 100% kwoty VAT z tej faktury, a gdy faktura nie wykazuje podatku, do 18,7% kwoty należności ogółem. Według obecnych przepisów stosuje się je od 1 stycznia 2027 r.

16 września 2026 r. Ministerstwo Finansów poinformowało, że chce przedłużyć okres bez kar do 31 grudnia 2027 r. Ministerstwo zaznacza, że odroczenie kar nie oznacza braku obowiązku stosowania KSeF, a Krajowa Administracja Skarbowa będzie reagować na wystawianie faktur poza systemem. 23 września 2026 r. w Rządowym Centrum Legislacji opublikowano projekt ustawy (UD477), zgodnie z którym przepisy o karach z art. 106ni miałyby wejść w życie 1 stycznia 2028 r. Na dzień publikacji tego tekstu projekt jest na etapie uzgodnień i konsultacji, więc obowiązuje termin z ustawy.

Co KSeF zmienia w firmie

Faktura ustrukturyzowana to plik XML zgodny ze strukturą FA(3), przesłany do KSeF. Po przyjęciu otrzymuje numer KSeF: 35 znaków składających się z NIP-u sprzedawcy, daty przyjęcia, części technicznej i sumy kontrolnej. Faktura jest uznana za otrzymaną przez nabywcę w momencie nadania numeru, bez żadnej akceptacji z jego strony. Datę tę potwierdza Urzędowe Poświadczenie Odbioru (UPO). KSeF przechowuje faktury przez 10 lat, licząc od końca roku, w którym je wystawiono.

Kilka konsekwencji, które dotykają procesów w firmie:

  • KSeF nie jest systemem raportowania. Faktury nie wystawia się w programie i nie "zgłasza" później. Wystawia się ją przy użyciu KSeF, a plik, który nie dostał numeru, nie jest fakturą.
  • Faktury dla konsumentów są w KSeF dobrowolne. Jeśli sprzedawca je tam wystawi, przekazuje je konsumentowi w uzgodniony sposób, na przykład jako PDF z kodem QR.
  • Zagraniczny nabywca bez polskiego NIP-u nie zaloguje się do KSeF. Fakturę wystawia się w KSeF, a nabywcy przekazuje uzgodnionym kanałem z kodem QR.
  • Korekta tylko do faktury z numerem. Fakturę korygującą przesyła się dopiero po nadaniu numeru KSeF fakturze pierwotnej. Faktury przyjętej przez KSeF nie da się zmienić, błędy poprawia się korektą.
  • Załączniki wymagają zgłoszenia. Faktury z załącznikiem można wystawiać po złożeniu zgłoszenia w e-Urzędzie Skarbowym, wyłącznie w programach zintegrowanych z API i tylko w sesji wsadowej. Maksymalny rozmiar takiej faktury to 3 MB.
  • Dostęp nadaje się uprawnieniami. Firma niebędąca osobą fizyczną, która nie ma pieczęci kwalifikowanej, składa zawiadomienie ZAW-FA wskazujące osobę do obsługi KSeF, a ta nadaje uprawnienia kolejnym osobom i systemom.

Ministerstwo wymienia też korzyści, między innymi szybszy zwrot VAT: w 40 dni zamiast 60.

Cztery drogi do KSeF

Nie każda firma potrzebuje własnej integracji. Wybór zależy od tego, gdzie powstają faktury i ile ich jest.

Sposoby korzystania z KSeF

NarzędzieDla kogo
Aplikacja Podatnika KSeF i aplikacja mobilna, bezpłatne narzędzia MFKilka faktur miesięcznie wystawianych ręcznie
e-mikrofirma w e-Urzędzie SkarbowymNajmniejsze firmy, które chcą mieć faktury od razu w ewidencji VAT
Program księgowy albo fakturowy zintegrowany z KSeFFirmy, które już wystawiają faktury w takim programie
Własna integracja przez APISklep, panel, ERP albo system rozliczeń, który sam generuje faktury

Jeśli faktury powstają w sklepie albo panelu, są dwie drogi. Można przekazywać dane z zamówienia do programu fakturowego, który ma integrację z KSeF, albo zbudować wysyłkę do KSeF bezpośrednio w swoim systemie. Pierwsza jest szybsza w uruchomieniu. Druga daje pełną kontrolę nad statusami i obsługą błędów, ale zgodność ze strukturą FA(3), tryby offline i kody QR spadają wtedy na Twój system.

Do budowy integracji Ministerstwo Finansów udostępnia dokumentację API KSeF 2.0 ze specyfikacją OpenAPI i dwie biblioteki open source: dla Javy i dla C#. Dla innych języków specyfikacja wystarcza do napisania własnego klienta.

Uwierzytelnianie: kontekst, certyfikat KSeF i token

Każde chronione wywołanie API wymaga tokena dostępowego JWT. Żeby go uzyskać, system wskazuje kontekst, czyli podmiot, w imieniu którego działa (najczęściej NIP firmy), i udowadnia tożsamość podmiotu uwierzytelniającego, który musi mieć w tym kontekście aktywne uprawnienie.

Dokumentacja uwierzytelniania opisuje dwie metody. Pierwsza to dokument XML AuthTokenRequest podpisany w formacie XAdES: kwalifikowanym podpisem, pieczęcią kwalifikowaną, podpisem zaufanym albo certyfikatem KSeF. Druga to token KSeF wygenerowany wcześniej w systemie. Przebieg wygląda tak:

1
Wyzwanie

POST /auth/challenge zwraca wartość challenge i znacznik czasu. Wyzwanie jest ważne 10 minut.

2
Podpis albo token

w wariancie z podpisem system przesyła podpisany AuthTokenRequest na POST /auth/xades-signature. W wariancie z tokenem szyfruje ciąg token|znacznikCzasuWMilisekundach kluczem publicznym KSeF algorytmem RSA-OAEP z SHA-256 i wysyła go na POST /auth/ksef-token.

3
Status

odpowiedź zawiera tymczasowy token operacji i numer referencyjny. System odpytuje GET /auth/{referenceNumber}, aż uwierzytelnienie się zakończy. Na środowisku przedprodukcyjnym i produkcyjnym KSeF sprawdza też status certyfikatu u jego wystawcy, co może potrwać.

4
Tokeny dostępowe

POST /auth/token/redeem zwraca jednorazowo parę: accessToken o krótkiej ważności i refreshToken ważny do 7 dni.

5
Odświeżanie

POST /auth/token/refresh z tokenem odświeżającym zwraca nowy token dostępowy bez ponownego uwierzytelnienia.

Kilka decyzji projektowych, które warto podjąć od razu:

  • Certyfikat KSeF na produkcji. Dokumentacja zaleca uwierzytelnianie certyfikatem KSeF, bo jego weryfikacja odbywa się wewnątrz systemu, bez oczekiwania na odpowiedź zewnętrznego dostawcy certyfikatów kwalifikowanych. Certyfikat występuje w dwóch typach: do uwierzytelniania i do trybu offline. Każdy jest ważny najwyżej 2 lata, więc rotacja musi być zaplanowana.
  • Tokeny. Tokeny z KSeF 1.0 nie działają w KSeF 2.0, a nowe można generować od 1 lutego 2026 r. Przepisy przewidywały wygaśnięcie tej metody z końcem 2026 r., ale MF zdecydowało, że tokeny pozostaną dostępne bezterminowo, i zapowiedziało zmianę rozporządzenia.
  • Sekrety poza kodem. Klucz prywatny certyfikatu, token KSeF i token odświeżający przechowuje się w sejfie na sekrety albo w zmiennych środowiska serwera, nigdy w repozytorium.
  • Lista adresów IP. Żądanie uwierzytelnienia może zawierać politykę autoryzacji z listą dozwolonych adresów IP, z których wolno używać wydanego tokena dostępowego.
  • Uprawnienia na miarę zadania. Do wysyłki faktur potrzebne jest uprawnienie InvoiceWrite. Konto techniczne systemu nie musi mieć uprawnień do zarządzania uprawnieniami innych osób.

Wysyłka faktur: sesja interaktywna czy wsadowa

Faktury wysyła się w sesjach. Każdy plik XML jest szyfrowany algorytmem AES-256-CBC z dopełnieniem PKCS#7, kluczem symetrycznym o długości 256 bitów i wektorem inicjującym o długości 128 bitów. Klucz symetryczny szyfruje się algorytmem RSA-OAEP z SHA-256 kluczem publicznym Ministerstwa Finansów, który system pobiera z GET /security/public-key-certificates. Dokumentacja rekomenduje nowy klucz dla każdej sesji.

Sesja interaktywna służy do wysyłki pojedynczych faktur. Otwiera się ją przez POST /sessions/online, podając kod formularza (dla FA(3): systemCode "FA (3)", schemaVersion "1-0E", value "FA") i zaszyfrowany klucz. Sesja jest ważna 12 godzin, a w ramach jednego uwierzytelnienia można mieć kilka otwartych sesji. Fakturę wysyła się na POST /sessions/online/{referenceNumber}/invoices razem ze skrótami SHA-256 i rozmiarami pliku przed i po zaszyfrowaniu. Weryfikacja jest asynchroniczna: status faktury i UPO pobiera się osobnymi wywołaniami, a zamknięcie sesji uruchamia generowanie zbiorczego UPO.

Przygotowanie treści żądania w Node.js wygląda tak (certyfikat to wartość z pola certificate dla klucza o przeznaczeniu SymmetricKeyEncryption):

ksef-szyfrowanie.mjs · javascript
import {
  X509Certificate, constants, createCipheriv, createHash, publicEncrypt, randomBytes,
} from 'node:crypto';

const sha256 = (data) => createHash('sha256').update(data).digest('base64');

export function prepareSessionKey(certificateBase64) {
  const certificate = new X509Certificate(Buffer.from(certificateBase64, 'base64'));
  const key = randomBytes(32);
  const iv = randomBytes(16);
  const encryptedKey = publicEncrypt(
    { key: certificate.publicKey, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
    key,
  );
  return {
    key,
    iv,
    encryption: {
      encryptedSymmetricKey: encryptedKey.toString('base64'),
      initializationVector: iv.toString('base64'),
    },
  };
}

export function buildSendInvoiceBody(invoiceXml, key, iv, offlineMode = false) {
  const cipher = createCipheriv('aes-256-cbc', key, iv);
  const encrypted = Buffer.concat([cipher.update(invoiceXml), cipher.final()]);
  return {
    invoiceHash: sha256(invoiceXml),
    invoiceSize: invoiceXml.length,
    encryptedInvoiceHash: sha256(encrypted),
    encryptedInvoiceSize: encrypted.length,
    encryptedInvoiceContent: encrypted.toString('base64'),
    offlineMode,
  };
}

invoiceXml to bufor z dokładnie tymi bajtami, które trafią do KSeF, w UTF-8 bez znacznika BOM. Skrót z innej wersji pliku, na przykład po przeformatowaniu XML-a, nie zgodzi się z treścią.

Sesja wsadowa służy do wysyłki wielu faktur naraz. Pliki XML pakuje się do archiwum ZIP, które dzieli się binarnie na części do 100 MB przed zaszyfrowaniem, najwyżej 50 części i 5 GB łącznie. Każdą część szyfruje się osobno, a jej wysyłka nie jest objęta limitami żądań, więc części można przesyłać równolegle.

Domyślne limity według dokumentacji z września 2026 r.

ParametrWartość
Rozmiar faktury bez załącznika / z załącznikiem1 MB / 3 MB
Liczba faktur w jednej sesji10 000
Wysłanie faktury w sesji interaktywnej10 na sekundę, 30 na minutę, 180 na godzinę
Otwarcie sesji interaktywnej / wsadowej120 / 60 na godzinę
Eksport paczki faktur kosztowych20 na godzinę

Limity żądań liczy się osobno dla każdej pary kontekst i adres IP, w oknie przesuwającym się w czasie. Po przekroczeniu API zwraca kod 429 z nagłówkiem Retry-After, a powtarzane przekroczenia wydłużają blokadę. Dokumentacja zastrzega, że limity są dynamiczne i mogą się zmieniać.

Dla sklepu internetowego ma to bezpośrednie znaczenie. Limit 180 faktur na godzinę w trybie interaktywnym łatwo przekroczyć w dniu promocji. Ministerstwo w dokumentacji limitów wprost opisuje scenariusz e-commerce: faktury nie muszą trafiać do KSeF natychmiast po wystawieniu, a osobny proces może je zbierać i co kilka minut wysyłać paczką w sesji wsadowej. Tryb interaktywny zostaje dla sytuacji, w których numer KSeF jest potrzebny od razu, na przykład w punkcie sprzedaży. Pamiętaj tylko, że faktura wystawiona jako online musi trafić do KSeF tego samego dnia, inaczej system potraktuje ją jako wystawioną w trybie offline24.

Walidacja: zanim KSeF odrzuci fakturę

Weryfikacja faktury w KSeF obejmuje poprawność XML 1.0, kodowanie UTF-8 bez BOM, zgodność ze schematem zadeklarowanym przy otwarciu sesji, brak instrukcji przetwarzania i niedozwolonych znaków. Data wystawienia z pola P_1 nie może być późniejsza niż data przyjęcia do KSeF, a na produkcji sprawdzane są sumy kontrolne NIP-ów.

KSeF wykrywa duplikaty globalnie, na podstawie NIP-u sprzedawcy, rodzaju faktury i numeru faktury z pola P_2, i odrzuca je z kodem 440. Unikalność obowiązuje przez 10 lat. Jeśli faktury w imieniu jednej firmy wystawia kilka systemów albo oddziałów, muszą mieć uzgodnioną numerację.

Ważne jest też to, czego KSeF nie sprawdza. Według Ministerstwa Finansów system nie weryfikuje poprawności rachunkowej ani danych kontrahenta. Faktura z błędnym NIP-em nabywcy zostanie przyjęta i będzie widoczna dla podmiotu o tym numerze, a naprawa wymaga korekty do zera i nowej faktury. Plik odrzucony przez KSeF nie jest fakturą, więc nie koryguje się go, tylko wysyła nowy, poprawny XML.

Z tego wynikają trzy zasady implementacji:

  • Walidacja lokalna przed wysyłką. Plik sprawdzany względem schematu XSD FA(3) i reguł biznesowych, w tym sumy kontrolnej NIP-u nabywcy, zanim trafi do kolejki.
  • Kolejka zamiast wysyłki w żądaniu użytkownika. Faktura trafia do tabeli z kolejką, a osobny proces wysyła ją do KSeF, odbiera status i zapisuje numer KSeF oraz UPO przy fakturze. Klient w sklepie nie czeka na odpowiedź KSeF.
  • Skrót jako klucz idempotencji. System zapisuje skrót SHA-256 każdego wysłanego pliku. Po przerwanym połączeniu najpierw sprawdza w KSeF listę faktur przesłanych w sesji, a dopiero potem decyduje o ponownej wysyłce.

Odbiór faktur kosztowych: synchronizacja, nie przeglądanie

API do pobierania faktur zostało zaprojektowane jako mechanizm synchronizacji z lokalną bazą, a nie do obsługi użytkowników w czasie rzeczywistym. Dokumentacja wprost odradza pobieranie faktury z KSeF w reakcji na kliknięcie użytkownika: wyszukiwanie, filtrowanie i podgląd mają działać na danych już zsynchronizowanych.

Zalecany mechanizm to przyrostowe pobieranie przez eksport paczek (POST /invoices/exports). Eksport działa asynchronicznie: system zleca go z kluczem szyfrującym, odpytuje status, pobiera zaszyfrowane części archiwum ZIP, odszyfrowuje je i rozpakowuje pliki XML razem z plikiem _metadata.json. Kolejne okna czasowe mają do siebie przylegać i opierać się na dacie trwałego zapisu w KSeF z mechanizmem High Water Mark. Gdy paczka zostanie obcięta przez limit liczby faktur albo rozmiaru, następne okno zaczyna się od daty ostatniej faktury w paczce. Duplikaty usuwa się po numerach KSeF z metadanych.

Faktury pobiera się osobno dla każdej roli, w jakiej firma może występować na fakturze: nabywcy, sprzedawcy, podmiotu trzeciego i podmiotu upoważnionego. Interwał synchronizacji nie powinien być krótszy niż 15 minut dla każdej roli, a w godzinach 20:00-06:00 obowiązują wyższe limity pobierania.

Jedna rzecz dotyczy księgowości, a nie kodu: datą otrzymania faktury jest data nadania numeru KSeF, niezależnie od tego, kiedy Twój system ją pobierze. Jeśli od daty otrzymania liczysz termin płatności albo okres rozliczeniowy, bierz ją z metadanych KSeF, a nie z daty importu.

Tryby offline i awarie

Ustawa przewiduje kilka sytuacji, w których fakturę wystawia się bez połączenia z KSeF i dosyła później. Dokumentacja trybów offline zestawia je tak:

Tryby wystawiania poza KSeF

TrybKiedyTermin przesłania do KSeF
offline24Z dowolnej przyczyny, na przykład brak internetuNajpóźniej następny dzień roboczy po dniu wystawienia
offline (niedostępność)Prace serwisowe ogłoszone przez MFNastępny dzień roboczy po zakończeniu niedostępności
awaryjnyAwaria ogłoszona w BIP MF i w oprogramowaniu interfejsowym7 dni roboczych od zakończenia awarii, a przy kolejnym komunikacie od nowa
awaria całkowitaOgłoszona w środkach masowego przekazuNie przesyła się; faktura papierowa albo elektroniczna, bez kodów QR

Za datę wystawienia faktury offline uznaje się datę z pola P_1. Przy wysyłce takiej faktury ustawia się offlineMode: true. Jeśli nabywca dostaje fakturę przed jej dosłaniem do KSeF, wizualizacja musi mieć dwa kody QR: pierwszy z napisem "OFFLINE", pozwalający zweryfikować fakturę, i drugi z napisem "CERTYFIKAT", potwierdzający tożsamość wystawcy. Do wygenerowania drugiego kodu potrzebny jest certyfikat KSeF typu offline, który trzeba mieć przed pierwszą awarią, a nie zamawiać w jej trakcie. Certyfikat do uwierzytelniania się do tego nie nadaje.

Jeśli dosłana faktura offline zostanie odrzucona z przyczyn technicznych, na przykład przez błąd schematu albo rozmiar pliku, dokumentacja przewiduje korektę techniczną: ponowne przesłanie faktury o tej samej treści w poprawnej postaci, wyłącznie w sesji interaktywnej. Korekta techniczna nie służy do zmiany treści faktury.

Dla systemu oznacza to konkretne funkcje: wykrywanie braku połączenia, faktury offline z dwoma kodami QR, kolejkę dosłania z terminami w dniach roboczych i alert, gdy termin się zbliża.

Kody QR na fakturach przekazywanych poza KSeF

Kody QR są potrzebne wszędzie, gdzie faktura trafia do odbiorcy inaczej niż przez pobranie z KSeF: jako PDF w e-mailu, wydruk dla konsumenta, faktura dla zagranicznego nabywcy. Generuje je lokalnie system wystawiający fakturę, zgodnie z normą ISO/IEC 18004:2024.

Pierwszy kod zawiera adres z NIP-em sprzedawcy, datą wystawienia z pola P_1 w formacie DD-MM-RRRR i skrótem SHA-256 pliku faktury w formacie Base64URL. Pod kodem faktury przyjętej przez KSeF umieszcza się jej numer KSeF.

ksef-qr.mjs · javascript
import { createHash } from 'node:crypto';

export function invoiceVerificationUrl(sellerNip, issueDate, invoiceXml) {
  const [year, month, day] = issueDate.split('-');
  const hash = createHash('sha256').update(invoiceXml).digest('base64url');
  return `https://qr.ksef.mf.gov.pl/invoice/${sellerNip}/${day}-${month}-${year}/${hash}`;
}

Na środowiskach testowych zamiast qr.ksef.mf.gov.pl używa się adresów qr-test.ksef.mf.gov.pl i qr-demo.ksef.mf.gov.pl. Po zeskanowaniu kodu każdy może sprawdzić, czy faktura jest w KSeF i czy nie została zmieniona.

Numer KSeF w płatnościach od 2027 r.

Od 1 stycznia 2027 r. czynny podatnik VAT, który płaci przelewem albo poleceniem zapłaty za fakturę ustrukturyzowaną innemu czynnemu podatnikowi VAT, musi podać w tytule płatności numer KSeF faktury albo identyfikator zbiorczy nadany przez KSeF (art. 108g ustawy o VAT). Od tej samej daty numer KSeF jest obowiązkowy także w przelewach w mechanizmie podzielonej płatności.

Dla systemów oznacza to, że numer KSeF musi być przechowywany przy każdej fakturze kosztowej i trafiać do pliku z przelewami albo do integracji z bankiem. W jednym identyfikatorze zbiorczym można według dokumentacji ująć do 500 faktur.

Środowiska i testy przed produkcją

KSeF 2.0 ma trzy publiczne środowiska: testowe (TEST) z wersjami kandydującymi, przedprodukcyjne (DEMO) z konfiguracją produkcyjną i produkcyjne (PROD). Na środowisku testowym dopuszczalne są certyfikaty samopodpisane, więc dane nie są odizolowane od innych integratorów i należy używać losowych NIP-ów, nigdy prawdziwych danych. Limity są tam dziesięciokrotnie wyższe niż na produkcji, a osobne wywołania pozwalają włączyć limity produkcyjne. Od 1 października 2025 r. na środowiskach testowych mogą odbywać się prace serwisowe w godzinach 16:00-18:00.

Przed uruchomieniem na produkcji warto przejść co najmniej te scenariusze:

  • wysyłka poprawnej faktury, pobranie statusu i UPO,
  • faktura z błędem schematu i duplikat numeru,
  • przekroczenie limitu żądań i poprawna obsługa nagłówka Retry-After,
  • wygaśnięcie tokena dostępowego w trakcie pracy i jego odświeżenie,
  • faktura offline24 z dwoma kodami QR i jej dosłanie, także z korektą techniczną,
  • synchronizacja faktur kosztowych z obciętą paczką i usuwaniem duplikatów,
  • zmiana klucza publicznego MF, którą dokumentacja opisuje jako planowy scenariusz rotacji.

Plan wdrożenia integracji krok po kroku

1
Spis źródeł faktur

sklep, panel, ERP, ręczne faktury w biurze.

2
Wybór drogi

własna integracja albo przekazywanie danych do programu fakturowego zintegrowanego z KSeF.

3
Dostęp i uprawnienia

zawiadomienie ZAW-FA albo pieczęć kwalifikowana, konto techniczne z uprawnieniem do wystawiania, certyfikaty do uwierzytelniania i do trybu offline, sejf na sekrety.

4
Mapowanie danych na FA(3)

wszystkie rodzaje wystawianych faktur, w tym korekty i zaliczki, z walidacją względem schematu.

5
Wysyłka

kolejka, sesje, statusy, numer KSeF i UPO zapisane przy fakturze.

6
Odbiór

przyrostowa synchronizacja faktur kosztowych do własnej bazy.

7
Tryby offline i wizualizacje

PDF z kodami QR, kolejka dosłania z terminami w dniach roboczych.

8
Płatności

numer KSeF w przelewach od 2027 r.

9
Testy na TEST i DEMO

scenariusze z poprzedniej sekcji.

10
Monitoring

alerty o fakturach czekających zbyt długo, o błędach 4xx i 5xx z API i o wygasających certyfikatach.

Alert ma trafiać do osoby, która może zareagować, zanim minie ustawowy termin. Jak ułożyć monitoring, opisaliśmy w tekście o monitoringu i utrzymaniu po wdrożeniu. Jeśli faktury powstają dziś w arkuszu, a integracja ma być częścią większego panelu, przeczytaj też, kiedy panel zastępuje arkusz.

Sklep internetowy a KSeF

W sklepie najwięcej decyzji dotyczy podziału klientów. Faktury dla konsumentów nie muszą trafiać do KSeF, ale gdy klient poda NIP i kupuje jako firma, faktura musi zostać wystawiona w KSeF (do końca 2026 r. z zastrzeżeniem opisanych wyżej wyjątków), a klient może ją pobrać z systemu. Sklep powinien więc rozróżniać zamówienia firmowe i konsumenckie już w koszyku.

Klient sklepu nadal oczekuje e-maila z PDF-em, więc wizualizacja powinna zawierać kod QR i numer KSeF. Dane na fakturach dla osób prowadzących jednoosobową działalność są danymi osobowymi, więc ich przetwarzanie podlega zasadom opisanym w tekście o RODO na stronie internetowej. Jeśli dopiero wybierasz kanał sprzedaży, porównanie własnego sklepu i marketplace znajdziesz w tekście Własny sklep internetowy czy Allegro.

Najczęściej zadawane pytania

Od kiedy KSeF jest obowiązkowy?

Od 1 lutego 2026 r. dla firm, których sprzedaż wraz z VAT przekroczyła w 2024 r. 200 mln zł, i od 1 kwietnia 2026 r. dla pozostałych. Odbieranie faktur przez KSeF obowiązuje wszystkich od 1 lutego 2026 r.

Czy mała firma musi korzystać z KSeF w 2026 r.?

Do 31 grudnia 2026 r. może wystawiać faktury poza KSeF, jeśli ich łączna wartość brutto w miesiącu nie przekracza 10 000 zł. Od faktury, którą przekroczy ten próg, musi korzystać z KSeF. Od 1 stycznia 2027 r. wyjątek przestaje obowiązywać.

Czy faktury dla konsumentów trzeba wystawiać w KSeF?

Nie, wystawianie faktur dla konsumentów w KSeF jest dobrowolne. Jeśli sprzedawca je tam wystawi, przekazuje konsumentowi fakturę w uzgodniony sposób, z kodem QR.

Czy token KSeF przestanie działać na koniec 2026 r.?

Według informacji Ministerstwa Finansów nie. MF zdecydowało o pozostawieniu tokenów jako metody uwierzytelnienia bezterminowo i zapowiedziało zmianę rozporządzenia. Tokeny wygenerowane w KSeF 1.0 nie działają w KSeF 2.0.

Co zrobić, gdy KSeF nie działa?

Przy pracach serwisowych fakturę dosyła się następnego dnia roboczego po ich zakończeniu, przy awarii ogłoszonej przez MF w ciągu 7 dni roboczych od jej zakończenia, a przy awarii całkowitej wcale. Niezależnie od stanu KSeF można też wystawić fakturę w trybie offline24 i przesłać ją najpóźniej następnego dnia roboczego.

Czy kary za błędy w KSeF będą stosowane od 2027 r.?

Według obecnych przepisów tak, od 1 stycznia 2027 r. Projekt ustawy opublikowany 23 września 2026 r. (UD477) przesuwa ten termin na 1 stycznia 2028 r., ale dopóki nie zostanie uchwalony, obowiązuje data z ustawy.

Integracja, która przetrwa awarię i kontrolę

Integracja z KSeF to kilka procesów: kolejka wysyłki, synchronizacja kosztów, tryby offline, kody QR i monitoring terminów. Najtaniej zaprojektować je razem, zanim pierwsza faktura utknie w kolejce w dniu awarii.

Jeśli Twój sklep, panel albo ERP ma wysyłać faktury do KSeF i chcesz omówić zakres takiej integracji, napisz przez formularz kontaktowy. Projekty integracyjne opisujemy na stronie Integracje i Automatyzacje, a przebieg współpracy na stronie jak pracujemy. Po oddaniu projektu dostajesz pełne prawa do kodu i dokumentację, więc integrację może dalej rozwijać także Twój zespół.

Czy ten wpis był przydatny?

Zobacz też