Integracja z KSeF
Integracja z KSeF to połączenie programu z Krajowym Systemem e-Faktur przez publiczne API KSeF 2.0. Może to być program do fakturowania, system księgowy, ERP albo narzędzie do analizy faktur. Dzięki integracji program sam wysyła faktury do KSeF albo je z niego pobiera, bez ręcznej pracy w Aplikacji Podatnika.
- Inaczej
- API KSeF, KSeF API 2.0, integracja systemu z KSeF, połączenie z KSeF, integracja ERP z KSeF
Jak działa integracja
- Uwierzytelnienie. Program loguje się do API w kontekście NIP-u firmy: tokenem KSeF, certyfikatem KSeF albo podpisem elektronicznym (XAdES). Może robić tylko to, na co pozwalają uprawnienia.
- Wysyłka faktur. Faktury trafiają do KSeF w sesji interaktywnej (pojedynczo) albo wsadowej (paczki). Po przetworzeniu program odbiera numery KSeF i UPO.
- Pobieranie faktur. Program wyszukuje faktury po dacie i roli firmy (sprzedawca, nabywca, podmiot trzeci), pobiera je pojedynczo albo eksportuje w paczkach. Do regularnej synchronizacji służy przyrostowe pobieranie (więcej w haśle automatyczne pobieranie faktur).
Każdy endpoint API ma limity wywołań na sekundę, minutę i godzinę, liczone dla kontekstu i adresu IP.
Środowiska
| Środowisko | Do czego | Dokumentacja API |
|---|---|---|
| TEST | testy integracji, wersje rozwojowe; dopuszcza też FA(2) | api-test.ksef.mf.gov.pl/docs/v2 |
| DEMO | końcowe testy w warunkach zbliżonych do produkcji | api-demo.ksef.mf.gov.pl/docs/v2 |
| PROD | faktury o pełnej mocy prawnej | api.ksef.mf.gov.pl/docs/v2 |
W praktyce
Większość firm nie buduje integracji sama, tylko korzysta z programu, który ją ma. Ministerstwo Finansów wskazuje programy zintegrowane z API KSeF jako główną drogę wystawiania faktur, a własne aplikacje jako bezpłatną alternatywę. Wybierając program, sprawdź, czy obsługuje rodzaje faktur, z których korzystasz, i tryby offline oraz jakich uprawnień potrzebuje.
Przykład
Sklep internetowy łączy platformę sprzedażową z KSeF przez program do fakturowania. Po każdym zamówieniu firmowym program wystawia fakturę w FA(3), wysyła ją w sesji interaktywnej, odbiera numer KSeF i dopisuje go do zamówienia. Biuro rachunkowe sklepu pobiera te same faktury do swojego systemu księgowego przez własną integrację.
Powiązane pojęcia
Token KSeF
Token KSeF to poufny ciąg znaków wygenerowany w KSeF, którym program uwierzytelnia się w systemie w imieniu firmy, bez podpisu kwalifikowanego przy każdym połączeniu. Token ma na stałe przypisane uprawnienia wybrane przy jego tworzeniu, np. tylko przeglądanie faktur. Obecnie token nie ma terminu ważności: działa, dopóki ktoś go nie unieważni.
Certyfikat KSeF
Certyfikat KSeF to certyfikat cyfrowy wydawany przez KSeF, który służy do uwierzytelniania się w systemie (typ 1) albo do oznaczania faktur wystawionych w trybie offline kodem QR potwierdzającym tożsamość wystawcy (typ 2). Jest ważny najwyżej 2 lata. W odróżnieniu od tokenu sam nie niesie żadnych uprawnień.
Uprawnienia w KSeF
Uprawnienia w KSeF określają, kto i co może robić w systemie w imieniu firmy: wystawiać faktury, przeglądać je, zarządzać uprawnieniami innych osób albo obsługiwać jednostki podrzędne. Nadaje je właściciel firmy albo osoba z uprawnieniem do zarządzania uprawnieniami, w Aplikacji Podatnika KSeF albo przez API.
UPO (Urzędowe Poświadczenie Odbioru)
UPO, czyli Urzędowe Poświadczenie Odbioru, to potwierdzenie wystawiane przez KSeF, że system przyjął wysłane faktury. Zawiera m.in. numery KSeF nadane fakturom. UPO można pobrać dla pojedynczej faktury albo zbiorczo dla całej sesji, w której wysłano faktury.
Automatyczne pobieranie faktur z KSeF
Automatyczne pobieranie faktur z KSeF polega na tym, że program regularnie łączy się z KSeF przez API, wyszukuje nowe faktury firmy i zapisuje je jako pliki XML, PDF albo dane w tabeli. Nikt nie musi ręcznie logować się do Aplikacji Podatnika. Do samego pobierania wystarczy uprawnienie do przeglądania faktur.
Odbieranie faktur kosztowych z KSeF
Od 1 lutego 2026 r. faktury kosztowe od dostawców, którzy wystawiają je w KSeF, firmy otrzymują w systemie, a nie mailem ani pocztą. Faktura jest otrzymana w dniu nadania jej numeru KSeF, a nabywca pobiera ją z KSeF: ręcznie w Aplikacji Podatnika albo automatycznie w programie połączonym z systemem.
Najczęstsze pytania
Czy integracja z KSeF jest płatna?
API KSeF jest publiczne i bezpłatne. Płaci się ewentualnie za program albo usługę, która z niego korzysta, albo za własną pracę programistów.
Czy na środowisku testowym można wysyłać prawdziwe faktury?
Nie. Środowiska TEST i DEMO służą wyłącznie do testów integracji. Ministerstwo Finansów zastrzega, żeby nie wysyłać do nich faktur produkcyjnych ani prawdziwych danych firm, a na środowisku testowym używać losowych NIP-ów.
Jakich uprawnień potrzebuje zintegrowany program?
Tylko tych, które wynikają z jego zadań. Program do fakturowania potrzebuje wystawiania faktur (często też przeglądania), a narzędziu do pobierania faktur wystarczy samo przeglądanie.
Źródła
- Dokumentacja KSeF API 2.0Ministerstwo Finansów, repozytorium CIRFMF/ksef-docs
- Środowiska KSeF API 2.0Ministerstwo Finansów, repozytorium CIRFMF/ksef-docs
- Uwierzytelnianie (dokumentacja KSeF API 2.0)Ministerstwo Finansów, repozytorium CIRFMF/ksef-docs
- Faktura ustrukturyzowana i struktura logiczna FAMinisterstwo Finansów, ksef.podatki.gov.pl
Treść sprawdzona ze źródłami: . Przepisy o KSeF często się zmieniają, więc przed decyzją podatkową sprawdź aktualny stan w źródłach.
Widzisz błąd albo nieaktualną informację? Daj nam znać, a poprawimy.
