Krajowy System e-Faktur (KSeF) to centralny rejestr faktur ustrukturyzowanych zarządzany przez Ministerstwo Finansów, który realnie przyspiesza i porządkuje procesy fakturowania w Polsce.
Integracja własnego systemu ERP lub sprzedażowego z API KSeF umożliwia automatyczne wysyłanie, odbieranie i walidację faktur bez ręcznego logowania do platformy rządowej. Ma to kluczowe znaczenie po wprowadzeniu obowiązku raportowania: od 1 lutego 2026 r. dla dużych przedsiębiorstw (obrót powyżej 200 mln zł w 2024 r.) oraz od 1 kwietnia 2026 r. dla pozostałych firm.
Artykuł wyjaśnia krok po kroku, jak przeprowadzić integrację zgodnie z wytycznymi Ministerstwa Finansów, strukturą FA(3) i dobrymi praktykami, aby uniknąć błędów oraz kar finansowych od 1 stycznia 2027 r.
Czym jest API KSeF i dlaczego integracja jest niezbędna?
API KSeF to interfejs komunikacyjny (oparty o zasady REST API i protokół HTTPS), który łączy systemy ERP z centralnym rejestrem KSeF. Pozwala na bezpośrednią komunikację z serwerami MF (ksef.mf.gov.pl), eliminując ręczne wgrywanie plików XML do aplikacji webowej.
Zgodnie z modelem scentralizowanego raportowania faktury przekazuje się w formacie XML zgodnym z FA(3), który definiuje m.in. dane sprzedawcy i nabywcy, pozycje, stawki VAT oraz załączniki. Integracja nie jest literalnie wymagana przepisami, ale w praktyce jest niezbędna dla firm przetwarzających więcej niż kilka faktur dziennie – ręczne operacje generują opóźnienia i ryzyko błędów.
Najważniejsze korzyści integracji to:
- automatyzacja obiegu faktur w tle, bez logowania użytkowników,
- weryfikacja danych w czasie rzeczywistym – po pozytywnej walidacji system zwraca numer KSeF i UPO (Urzędowe Poświadczenie Odbioru) lub listę błędów,
- bezpośredni odbiór faktur przez kontrahentów w ich systemach ERP.
Brak integracji zwiększa ryzyko sankcji za niedopełnienie obowiązków raportowania e-faktur.
Podstawy prawne i terminy wdrożenia
Wdrożenie integracji wynika z ustawy o Krajowym Systemie e-Faktur oraz rozporządzeń Ministra Finansów definiujących strukturę logiczną faktur (obecnie FA(2), docelowo FA(3) m.in. dla dokumentów z załącznikami). Dokumentacja techniczna, w tym specyfikacja OpenAPI i interfejs Swagger UI, jest dostępna w serwisach Ministerstwa Finansów oraz w środowisku testowym.
Poniżej zebrano kluczowe daty wejścia w życie obowiązków:
- 1 lutego 2026 r. – obowiązek dla dużych firm (obrót powyżej 200 mln zł);
- 1 kwietnia 2026 r. – obowiązek dla pozostałych przedsiębiorców;
- 1 stycznia 2027 r. – start kar finansowych za brak zgodności.
Ministerstwo Finansów udostępnia środowisko integracyjne (testowe) – jego użycie przed uruchomieniem produkcyjnym zdecydowanie minimalizuje ryzyko błędów.
Schemat działania integracji ERP z API KSeF
Proces polega na wymianie żądań HTTP między Twoim ERP a KSeF. Oto uproszczony schemat kroków:
- Generowanie faktury w ERP – system tworzy dokument w formacie XML zgodnym z FA(3);
- Uwierzytelnienie – użyj mechanizmu podpisu/certyfikatu lub tokenu zgodnie z dokumentacją MF;
- Wysyłka – wyślij żądanie POST do właściwego endpointu (np.
/api/invoices/ImportXmlInvoice) z plikiem XML; - Walidacja – KSeF weryfikuje poprawność techniczną i biznesową (zgodność z przepisami VAT);
- Odpowiedź – odbierz numer KSeF i UPO lub szczegółową listę błędów;
- Odbiór – wykonaj GET, aby pobrać faktury otrzymane od kontrahentów.
Cały proces jest rejestrowany w logach ERP (np. w bazie MS SQL), a dane nie są utrzymywane na zewnętrznych serwerach poza infrastrukturą KSeF.
Dla przejrzystości poniżej znajduje się skrócona mapa etapów, działań i odpowiedzi API:
| Etap | Działanie w ERP | Odpowiedź API KSeF | Przykładowy endpoint |
|---|---|---|---|
| Wystawienie | generuj XML FA(3) | weryfikacja + numer KSeF + UPO | POST /invoices |
| Odbiór | pobierz listę faktur | plik XML + metadane | GET /invoices |
| Walidacja | wyślij szkic | lista błędów lub akceptacja | POST /validate |
Kroki integracji – praktyczny przewodnik
1. Przygotowanie i dokumentacja
Na start zaplanuj zakres i narzędzia, korzystając z oficjalnych materiałów MF:
- pobierz specyfikację OpenAPI i przetestuj metody w Swagger UI z dokumentacji MF,
- skorzystaj ze środowiska testowego API KSeF 2.0 (ksef.podatki.gov.pl),
- zidentyfikuj kluczowe endpointy: wysyłanie faktur, import XML, pobieranie UPO.
2. Uwierzytelnienie i bezpieczeństwo
Zadbaj o spójne i bezpieczne procesy autoryzacji oraz zgodność z regulacjami:
- używaj oficjalnych mechanizmów MF: kwalifikowanych certyfikatów lub tokenów,
- zapewnij szyfrowanie HTTPS i pełne logowanie żądań dla audytu (zgodnie z RODO),
- unikaj nieoficjalnych pośredników – stawiaj na zweryfikowane biblioteki integracyjne.
3. Implementacja w systemie ERP
Zaimplementuj logikę przetwarzania dokumentów oraz solidną obsługę błędów:
- konwersja do XML – automatycznie mapuj pola ERP na FA(3) (np. NIP, stawki i kwoty VAT),
- obsługa błędów – wprowadź walidacje wejściowe i mechanizm ponawiania (retry),
- przykład: aplikacja webowa – faktury z ERP wysyłane są przez API do KSeF z automatycznym pozyskaniem UPO,
- dostępne są gotowe moduły dla popularnych systemów (np. Comarch ERP, Symfonia) wspierające konwersję i wysyłkę w tle.
Dobre praktyki przed uruchomieniem produkcyjnym:
- testuj integrację w środowisku integracyjnym MF,
- monitoruj limity zapytań API i komunikaty błędów,
- zapisuj statusy i logi w lokalnej bazie danych dla pełnej kontroli.
4. Testowanie i wdrożenie
Zapewnij wydajność i stabilność procesu na produkcji:
- symuluj wysyłkę setek faktur dziennie i analizuj czasy odpowiedzi,
- zweryfikuj obsługę faktur z załącznikami (funkcja dostępna wyłącznie przez API),
- po uruchomieniu włącz automatyczne raportowanie bez ingerencji użytkownika.
Wyzwania i dobre praktyki
Najczęstsze błędy w integracjach, których warto unikać:
- niezgodność XML ze strukturą FA(3) – skutkuje odrzuceniem,
- nieprawidłowe lub brakujące uwierzytelnienie – żądania są blokowane,
- ręczne wgrywanie dokumentów – niepraktyczne przy dużych wolumenach.
Rekomendacje ułatwiające wdrożenie i utrzymanie:
- wybierz dostawcę lub bibliotekę z udokumentowanym doświadczeniem w REST API,
- w mniejszych firmach rozważ narzędzia komercyjne skracające czas integracji,
- zabezpiecz dane i utrzymuj pełną transparentność logów operacyjnych.
Integracja z API KSeF usprawnia księgowość, minimalizuje błędy i zapewnia zgodność z prawem – w dużych firmach staje się standardem, automatyzując procesy end‑to‑end. W razie wątpliwości sięgnij do dokumentacji MF lub skonsultuj się ze specjalistą – to inwestycja w efektywność i ograniczenie ryzyka kar.
