Jak podłączyć własny system do KSeF przez API

Co KSeF zmienia w firmie i od kiedy

Krajowy System e-Faktur nie jest kolejnym formatem pliku. Zmienia miejsce, w którym faktura powstaje, i moment, w którym uznaje się ją za wystawioną.

Dotąd fakturę tworzył Twój program, a dostarczenie jej klientowi było Twoją sprawą. W KSeF dokument w strukturze logicznej FA(3) trafia najpierw do systemu Ministerstwa Finansów, tam dostaje numer KSeF i dopiero wtedy funkcjonuje w obrocie. Nabywca będący czynnym podatnikiem pobiera go z systemu, więc wysyłka mailem staje się co najwyżej uprzejmością.

Obowiązek wystawiania wszedł dwuetapowo: od 1 lutego 2026 r. objął podatników, u których wartość sprzedaży wraz z kwotą podatku przekroczyła w 2024 r. 200 mln zł, a od 1 kwietnia 2026 r. wszystkich pozostałych. Osobno ruszył obowiązek odbierania: od 1 lutego 2026 r. każdy podatnik musi umieć przyjąć fakturę przez KSeF, nawet jeśli sam nie musiał jeszcze w nim wystawiać. To rozróżnienie bywa przeoczane, bo pierwsza faktura kosztowa z systemu przychodzi wcześniej niż własny obowiązek.

Rok 2026 jest przejściowy. Ministerstwo Finansów zapowiedziało, że w tym okresie nie nakłada kar za błędy związane z korzystaniem z KSeF. Od 1 stycznia 2027 r. wchodzą dwie rzeczy naraz: obowiązek dla grupy korzystającej dotąd z wyłączenia dla drobnej sprzedaży oraz obowiązek podawania numeru KSeF albo identyfikatora zbiorczego w komunikacie przelewu, także w podzielonej płatności.

Podstawą prawną jest ustawa z 5 sierpnia 2025 r. (Dz. U. z 2025 r. poz. 1203). Daty i progi w tej sekcji to stan na 19 września 2026 r.; harmonogram przesuwano już kilkakrotnie, więc przed ułożeniem planu potwierdź terminy na ksef.podatki.gov.pl.

Kogo obowiązuje KSeF i co z niego wypada

Obowiązek jest szeroki, ale nie obejmuje wszystkiego, co w firmie nazywa się fakturą. Wyłączenia mają trzy warstwy i każda działa inaczej.

Pierwsza warstwa dotyczy podmiotów. Faktur w KSeF nie muszą wystawiać firmy bez siedziby i bez stałego miejsca prowadzenia działalności w Polsce oraz te, których stałe miejsce nie uczestniczy w transakcji. W tej samej grupie są faktury dla osób fizycznych nieprowadzących działalności, więc sprzedaż konsumencka zostaje poza obowiązkiem, choć wolno ją przesłać dobrowolnie.

Druga warstwa to wyłączenia obowiązkowe, których nie obejdzie się dobrowolną wysyłką: procedura OSS w wariancie nieunijnym, procedura importu IOSS, okazjonalny międzynarodowy przewóz drogowy osób oraz zwolnienie dla małych przedsiębiorstw z art. 113a ustawy o VAT. Tu wysłanie faktury do systemu jest błędem, a nie nadgorliwością.

Trzecia warstwa dotyczy rodzaju dokumentu. Poza systemem zostają faktury uproszczone za przejazd autostradą płatną, bilety jednorazowe uznane za faktury, usługi zwolnione z art. 43 ustawy o VAT oraz samofakturowanie bez polskiego numeru NIP po jednej ze stron. Nie trafiają tam też proformy, faktury wewnętrzne i noty obciążeniowe, a noty korygujące zniknęły z przepisów 1 lutego 2026 r.

Osobny kalendarz mają kasy rejestrujące: do końca 2026 r. faktury z kasy można wystawiać w dotychczasowej formie. Progi i daty w tej sekcji to stan na 19 września 2026 r., a zakres wyłączeń bywa doprecyzowywany, więc sprawdź listę na ksef.podatki.gov.pl.

• Wyłączenie do 10 000 zł kończy się z rokiem 2026Do 31 grudnia 2026 r. można wystawiać faktury poza KSeF, jeśli ich łączna wartość z podatkiem nie przekracza w danym miesiącu 10 000 zł. Od 1 stycznia 2027 r. wyłączenie znika.
• Do limitu nie wlicza się wszystkiegoLiczą się wyłącznie faktury objęte obowiązkiem. Poza limitem zostają faktury dla konsumentów, sprzedaż udokumentowana samym paragonem oraz paragony z numerem NIP do 450 zł, czyli równowartości 100 EUR, uznane za faktury uproszczone.
• Przekroczenie progu jest nieodwracalnePo przekroczeniu 10 000 zł w danym miesiącu w KSeF trzeba wystawić fakturę, która próg przekroczyła, i każdą następną. Słabszy miesiąc nie przywraca wyłączenia.

Ceny i stawki sprawdzone 19 września 2026. Dostawcy zmieniają cenniki, więc przed decyzją sprawdź aktualną kwotę u źródła.

Trzy drogi do KSeF: aplikacja MF, program księgowy, własna integracja

Nie każda firma potrzebuje integracji przez API. Wybór sprowadza się do dwóch pytań: gdzie powstaje faktura i ile ich jest w miesiącu.

Pierwsza droga to bezpłatne narzędzia Ministerstwa Finansów: Aplikacja Podatnika KSeF, aplikacja mobilna dostępna od 1 lutego 2026 r. oraz e-mikrofirma w e-Urzędzie Skarbowym. To rozwiązanie dla firmy wystawiającej kilkanaście faktur miesięcznie.

Druga droga to program księgowy z integracją po stronie dostawcy. Wystawiasz dokument jak dotąd, a ktoś inny odpowiada za wysyłkę, odbiór UPO i aktualizacje pod zmiany schematu. Dla większości firm to najrozsądniejszy domyślny wybór. Granicą jest moment, w którym faktura musi powstać automatycznie po zdarzeniu w systemie.

Trzecia droga to własna integracja przez API KSeF 2.0. Ministerstwo publikuje specyfikację OpenAPI 3.0.4 z interaktywną dokumentacją, udostępnia środowisko integracyjne i przedprodukcyjne oraz utrzymuje repozytoria z przewodnikiem i bibliotekami klienckimi w C# i Javie.

Zła przesłanka wyboru brzmi „napiszemy sobie sami, bo to tylko wysłanie XML-a”. Wysłanie XML-a jest najprostszą częścią. Trudne jest to, co dzieje się, gdy system odrzuci dokument o drugiej w nocy.

Jak działa API KSeF: uwierzytelnianie, sesja, UPO i tryby offline

Integracja to cztery kroki w stałej kolejności. Pominięcie któregokolwiek kończy się dokumentem, którego formalnie nie ma.

Osobny temat to sytuacje, w których wysyłka w czasie rzeczywistym jest niemożliwa. Tryb offline24 może zastosować każdy podatnik bez ograniczeń: fakturę wystawia się poza systemem i przesyła niezwłocznie, najpóźniej w następnym dniu roboczym, a datą wystawienia pozostaje ta z pola P_1. Dokument udostępniony nabywcy przed wysyłką musi mieć dwa kody QR, oznaczone OFFLINE i CERTYFIKAT; drugi wymaga certyfikatu typu drugiego.

Tryb offline przy zapowiedzianych pracach serwisowych daje na dosłanie jeden dzień roboczy po zakończeniu przerwy. Tryb awaryjny uruchamia się, gdy Ministerstwo ogłosi awarię w BIP i w oprogramowaniu interfejsowym; wtedy na dosłanie jest 7 dni roboczych od dnia jej zakończenia, a kolejna awaria w tym okresie liczy termin od nowa. Przy awarii całkowitej faktur nie dosyła się w ogóle.

Dochodzi jeszcze warstwa danych. Od 1 lutego 2026 r. obowiązuje struktura FA(3), z węzłem załącznika i szerszym polem opisu pozycji. Załączniki są dobrowolne, wyłącznie w formacie XML, o rozmiarze do 3 MB, i wymagają wcześniejszego zgłoszenia w e-Urzędzie Skarbowym. Terminy i limity w tej sekcji to stan na 19 września 2026 r.; przed kodowaniem sprawdź aktualną specyfikację OpenAPI i dziennik zmian API.

1. Uprawnienia i uwierzytelnianieUprawnienia nadaje się konkretnym osobom lub podmiotom, nigdy systemom. Podmiot niebędący osobą fizyczną zaczyna od zgłoszenia ZAW-FA, a dalej uwierzytelnia się podpisem kwalifikowanym, pieczęcią kwalifikowaną, Profilem Zaufanym, tokenem lub certyfikatem KSeF. Tokeny z API 1.0 tu nie zadziałają.
2. Certyfikat KSeF w dwóch typachUwierzytelnianie certyfikatem jest dostępne od 1 lutego 2026 r., a certyfikat jest ważny nie dłużej niż 2 lata od wytworzenia. Typ pierwszy służy do logowania w API, typ drugi do oznaczania faktur kodem QR w trybach offline. Wydziel osobny certyfikat dla integracji.
3. Sesja i wysyłkaFaktury wysyła się w sesji interaktywnej, dokument po dokumencie, albo w sesji wsadowej, paczką. Interaktywna pasuje do sprzedaży, w której faktura powstaje przy zapłacie, wsadowa do rozliczeń okresowych i migracji. Wysyłka jest asynchroniczna, więc kod czekający na odpowiedź w jednym żądaniu HTTP utknie.
4. UPO i numer KSeFPrzyjęcie potwierdza Urzędowe Poświadczenie Odbioru, zawierające datę przyjęcia dokumentu do systemu teleinformatycznego Ministerstwa Finansów oraz numer KSeF. Numer identyfikuje fakturę w systemie, nie zastępuje Twojej numeracji i nie jest elementem faktury. Zapisz go przy zamówieniu.

Sklep internetowy i system sprzedaży: co trzeba zmienić

W sklepie KSeF dotyka nie tylko faktury. Dotyka koszyka, danych klienta, kolejki zadań i tego, co widzi kupujący po zapłacie.

Zacznij od rozdzielenia sprzedaży konsumenckiej i firmowej. Faktury dla osób fizycznych nieprowadzących działalności nie podlegają obowiązkowi, a faktury z numerem NIP tak, więc kasa musi rozstrzygać, który przypadek zachodzi, i zapisywać tę decyzję przy zamówieniu. Pole „chcę fakturę” z opcjonalnym NIP-em przestaje wystarczać.

Druga zmiana dotyczy jakości danych. Struktura logiczna waliduje to, co dotąd przechodziło bez echa: format numeru NIP, kompletność adresu, poprawność stawek i jednostek miary. Walidację trzeba więc przesunąć do kasy, zanim klient zapłaci, bo naprawianie danych po fakcie kończy się korektą.

Trzecia zmiana to sposób wystawiania. Faktura nie może powstawać synchronicznie w żądaniu obsługującym płatność. Właściwy układ to kolejka: płatność potwierdzona, zadanie w kolejce, wysyłka do KSeF, zapis numeru KSeF i UPO, dopiero potem powiadomienie klienta. Chwilowa niedostępność systemu nie blokuje wtedy sprzedaży.

Czwarta zmiana jest widoczna dla klienta. Nabywca będący czynnym podatnikiem odbierze fakturę z KSeF, więc to, co wysyłasz mailem, jest wizualizacją, a nie dokumentem. Napisz to wprost w wiadomości i w panelu zamówień, razem z numerem KSeF.

Piąta zmiana dotyczy strony kosztowej. Odbieranie faktur przez KSeF jest obowiązkowe dla wszystkich od 1 lutego 2026 r., więc obieg dokumentów zakupowych musi je pobierać z systemu, a nie czekać na załącznik. Daty w tej sekcji to stan na 19 września 2026 r.

Najczęstsze błędy wdrożeniowe i jak ich uniknąć

Wdrożenie KSeF rzadko wykłada się na samej wysyłce. Wykłada się na tym, co dzieje się, gdy wysyłka nie zadziała.

Terminy w tej sekcji to stan na 19 września 2026 r. Wersje API zmieniają się częściej niż przepisy, więc zajrzyj do dziennika zmian API.

• Cicha porażka wysyłkiIntegracja wysyła dokument, dostaje błąd i zapisuje go tylko w logu, a o braku faktury dowiadujesz się przy zamknięciu miesiąca. Każde odrzucenie musi kończyć się powiadomieniem i widocznym statusem przy zamówieniu.
• Brak zabezpieczenia przed duplikatemPonowienie wysyłki bez klucza rozpoznającego powtórkę tworzy dwa dokumenty na jedną sprzedaż. Poprawka wymaga korekty, bo faktury przyjętej przez system nie da się wycofać.
• Numer KSeF zapisany tylko w UPONumer trzymaj przy zamówieniu i przy płatności, w osobnym polu. Od 1 stycznia 2027 r. trafia do komunikatu przelewu, a wyciąganie go wtedy z archiwum to praca, której da się dziś uniknąć jedną kolumną w bazie.
• Pominięte tryby offlineIntegracja obsługuje tylko sytuację, w której system odpowiada. Przy przerwie serwisowej albo ogłoszonej awarii sprzedaż staje, chociaż przepisy dają na dosłanie odpowiednio jeden dzień roboczy i 7 dni roboczych od zakończenia awarii.
• Uprawnienia przypisane do osoby, która odeszłaUprawnienia nadaje się ludziom i podmiotom, nie systemom, więc integracja działa na czyichś uprawnieniach. Gdy ta osoba odchodzi, wysyłka przestaje działać w dniu odebrania dostępu.
• Certyfikat bez przypomnienia o wygaśnięciuCertyfikat KSeF jest ważny nie dłużej niż 2 lata od wytworzenia. Bez alertu w monitoringu wygaśnięcie objawi się jako nagła seria błędów uwierzytelniania w losowy poniedziałek.
• Testy wyłącznie na środowisku produkcyjnymMinisterstwo udostępnia środowisko integracyjne i przedprodukcyjne z osobną dokumentacją OpenAPI. Faktura testowa wysłana na produkcję jest dokumentem w obrocie prawnym i zostaje w systemie.

Harmonogram przygotowań krok po kroku

Kolejność ma znaczenie, bo połowa pracy to formalności, które trwają niezależnie od tego, jak szybko piszesz kod.

Daty w tym harmonogramie to stan na 19 września 2026 r. Potwierdź je na ksef.podatki.gov.pl, bo pojedyncze terminy bywały przesuwane już po ogłoszeniu.

1. Ustal swoją datę i swój zakresSprawdź, do której grupy należysz i czy korzystasz jeszcze z wyłączenia do 10 000 zł miesięcznie, które kończy się 31 grudnia 2026 r. Wypisz typy dokumentów, jakie wystawiasz, i zaznacz objęte wyłączeniami.
2. Uporządkuj uprawnieniaPodmiot niebędący osobą fizyczną zaczyna od zgłoszenia ZAW-FA, potem nadaje uprawnienia osobom i biuru rachunkowemu. To krok administracyjny, zrób go przed programowaniem.
3. Wygeneruj certyfikaty i zaplanuj wymianęPobierz certyfikat typu pierwszego dla integracji i typu drugiego, jeśli będziesz oznaczać faktury kodem QR offline. Od razu wpisz do kalendarza datę wygaśnięcia, licząc najwyżej 2 lata.
4. Przejrzyj dane, zanim dotkniesz koduZrób raport z własnej bazy: kontrahenci bez poprawnego NIP-u, niekompletne adresy, nietypowe stawki i jednostki miary. Każdy taki przypadek wróci jako odrzucenie.
5. Zbuduj wysyłkę na środowisku testowymPracuj na środowisku integracyjnym i przedprodukcyjnym, korzystając ze specyfikacji OpenAPI i bibliotek Ministerstwa Finansów. Najpierw pojedyncza faktura, potem korekta, potem sesja wsadowa.
6. Dodaj obsługę błędów i trybów offlineZaprojektuj kolejkę z ponawianiem, powiadomienie o odrzuceniu i ścieżkę na wypadek ogłoszonej awarii, z terminem 7 dni roboczych od jej zakończenia. Ten etap trwa dłużej niż sama wysyłka.
7. Przećwicz pełen miesiąc z księgowościąPrzepuść przez nowy proces dokumenty z jednego miesiąca: sprzedaż firmową, konsumencką, korekty i dokumenty wyłączone. Uzgodnienie wyniku wychwytuje więcej niż testy jednostkowe.
8. Przygotuj się na przelewy z numerem KSeFOd 1 stycznia 2027 r. numer KSeF albo identyfikator zbiorczy trafia do komunikatu przelewu, także w podzielonej płatności. Identyfikator ma 35 znaków i agreguje co najmniej dwie faktury jednego sprzedawcy, więc zaplanuj miejsce na oba w eksportach do banku.

Ceny i stawki sprawdzone 19 września 2026. Dostawcy zmieniają cenniki, więc przed decyzją sprawdź aktualną kwotę u źródła.

Co warto zrobić, zanim termin zacznie naciskać

Najdroższe wdrożenia KSeF to te robione w ostatnim tygodniu, gdy nie ma już czasu na czekanie na uprawnienia i na poprawianie danych.

Jeśli masz zrobić tylko jedną rzecz, przejrzyj dane kontrahentów. Odrzucenia w pierwszych tygodniach po wdrożeniu prawie zawsze biorą się z tego samego: niepoprawnego numeru NIP, brakującego elementu adresu albo jednostki miary, której nikt nigdy nie sprawdzał. Ten przegląd zrobisz bez integracji i bez decyzji o narzędziu.

Drugą rzeczą jest test odbioru. Obowiązek odbierania faktur przez KSeF objął wszystkich 1 lutego 2026 r., więc dokumenty kosztowe już tam są, niezależnie od tego, czy Twój obieg je pobiera. Sprawdź, czy księgowość widzi komplet faktur zakupowych z systemu, a nie tylko te przysłane mailem; daty w tej sekcji to stan na 19 września 2026 r.

Trzecią jest decyzja o drodze. Firma wystawiająca kilkanaście faktur miesięcznie nie potrzebuje własnej integracji. Własne API ma sens wtedy, gdy faktura musi powstać automatycznie z konkretnego zdarzenia: opłaconego zamówienia, zakończonego okresu abonamentowego, rozliczonego projektu. Różnica to wtedy nie wygoda, tylko liczba godzin w miesiącu.

Pracuję sam, więc zaczynam od jednego pytania: w którym dokładnie momencie w Twoim systemie ma powstać faktura i co ma się stać, gdy KSeF ją odrzuci. Z tej odpowiedzi wynika zakres integracji, sposób obsługi błędów i to, czy w ogóle warto ją budować. Jeśli planujesz takie wdrożenie, napisz, skąd bierze się u Ciebie faktura i ile ich powstaje w miesiącu.

Pytania i odpowiedzi