Jak podłączyć KSeF do własnych narzędzi: token, certyfikat, API

Większości firm wystarczy program księgowy albo fakturowy z wbudowanym KSeF: wklejasz mu token albo wgrywasz certyfikat i program sam pobiera faktury. Własne narzędzie podłącza się do API KSeF tokenem albo certyfikatem i ma to sens, gdy faktury mają trafiać dalej: do obiegu kosztów, do przelewów, do własnej kopii z wyszukiwaniem albo do zestawień.

Jakie są drogi podłączenia do KSeF?

Masz 3 drogi. Do ręcznej pracy Ministerstwo Finansów daje bezpłatnie Aplikację Podatnika, aplikację mobilną i e-mikrofirmę, więc integracja nie jest obowiązkowa (pytania i odpowiedzi MF).

W programie z KSeF generujesz token w Aplikacji Podatnika i wklejasz go do ustawień, a program loguje się do KSeF sam. Własne narzędzie wymaga pracy programisty, ale to Ty decydujesz, co dzieje się z fakturami po pobraniu. Szerzej opisuje to hasło integracja z KSeF.

Kiedy własna integracja z KSeF ma sens?

Z naszej praktyki własna integracja zaczyna się opłacać, gdy:

• faktury kosztowe mają wejść do obiegu akceptacji, na przykład na liście w SharePoint,
• numer KSeF faktury ma trafiać do tytułu przelewu,
• potrzebujesz własnej kopii faktur z wyszukiwaniem, niezależnej od aplikacji MF,
• zestawienia z faktur mają łączyć się z danymi z innych systemów.

Pobranie faktur to dopiero początek obiegu. Dla firmy usługowej zbudowaliśmy aplikację webową, w której wydatki są automatycznie zliczane, kategoryzowane, kierowane do zatwierdzenia i monitorowane na bieżąco. Jeśli Twoje faktury kosztowe wymagają takiej drogi, opisz nam, co ma się z nimi dziać krok po kroku.

Opisz obieg swoich faktur

Token czy certyfikat do własnego narzędzia?

Do samego pobierania faktur wystarczy token z jednym uprawnieniem, przeglądaniem faktur, spośród 6 do wyboru. Certyfikat sam nie niesie uprawnień (dokumentacja API), więc zakresu nie ograniczysz na poziomie certyfikatu. Hasło do jego klucza prywatnego ma od 15 do 32 znaków i nie da się go zresetować. Token wybierz, gdy narzędzie ma tylko pobierać faktury jednej firmy i zależy Ci na najwęższym zakresie. Certyfikat ma sens, gdy jedno narzędzie obsługuje kilka firm, bo jeden certyfikat działa w wielu kontekstach, albo gdy nie chcesz opierać integracji na zapowiadanych zmianach ważności tokenów.

Rozporządzenie dopuszcza tokeny do 31.12.2026, Ministerstwo Finansów zapowiada ich utrzymanie z terminem ważności od 1 do 365 dni (odpowiedź na interpelację 19230), a zespół API KSeF zapowiada, że tokeny wydane do końca 2026 r. będą działać do 30.11.2027 (wątek w dokumentacji API). Zanim oprzesz ważną integrację na tokenie, sprawdź aktualny komunikat na ksef.podatki.gov.pl.

Jak własne narzędzie rozmawia z API KSeF?

Dla zlecającego liczy się kilka rzeczy, resztę dopowie programista. Ogólnie o API pisze hasło API.

1. Logowanie. Program prosi KSeF o wyzwanie i odsyła je z tokenem zaszyfrowanym kluczem publicznym MF albo z podpisem certyfikatu. W zamian dostaje token dostępowy ważny kilkanaście minut oraz odświeżający, ważny do 7 dni (dokumentacja).
2. Pobieranie przyrostowe. Program pobiera faktury kosztowe od ostatniego pobrania i pilnuje punktu, do którego dotarł, żeby żadna nie przepadła ani nie wróciła dwa razy (opis MF).
3. Limity. Zapytania liczą się dla pary NIP i adresu IP. Lista faktur ma limit 20 zapytań na godzinę, a po przekroczeniu API zwraca kod 429 z informacją, kiedy ponowić. Powtarzane przekroczenia mogą skończyć się blokadą. Ministerstwo zaleca synchronizację do lokalnej bazy nie częściej niż co 15 minut (limity API). Pytania o faktury kieruj więc do lokalnej kopii, a nie do API, a w skrypcie ustaw blokadę ponownego pobrania przed upływem tych 15 minut.
4. Środowisko testowe. Najpierw próby na środowisku testowym, na fikcyjnych danych. Prawdziwe faktury idą wyłącznie na produkcję (środowiska).
5. Dokumentacja i biblioteki. Ministerstwo publikuje na GitHubie dokumentację z przykładami w C# i Javie oraz biblioteki open source w obu językach (README).

Jak zabezpieczyć token i certyfikat?

• Najmniejszy możliwy zakres. Do odczytu zaznacz tylko przeglądanie faktur. Dla każdej integracji zrób osobny token, żeby dało się odciąć jedną bez psucia pozostałych.
• Poza kodem. Dokumentacja nazywa token poufnym sekretem do przechowywania w zaufanym magazynie. Nie trzymaj go w repozytorium, arkuszu ani mailu. Klucz prywatny certyfikatu i jego hasło też są sekretami.
• Odejście pracownika albo wykonawcy. Unieważnij jego token na liście tokenów w Aplikacji Podatnika. Certyfikat wystawiony na osobę fizyczną nie może przejść na inną osobę.
• Adresy IP. Przy logowaniu można ograniczyć użycie tokenu dostępowego do wskazanych adresów IP (dokumentacja).
• Zmiany w API. Ministerstwo publikuje je z datami wycofania w historii zmian. Ktoś musi ją śledzić i poprawiać integrację, gdy coś zostanie wycofane.

Ile kosztuje integracja z KSeF i ile trwa?

Automatyzacja zaczyna się u nas od 2 tys. zł, a rozbudowana, z integracjami z innymi programami, kosztuje zwykle 4–12 tys. zł. Prosta trwa 1–2 tygodnie, a z integracją z innym programem 3–6 tygodni. Co wpływa na cenę, opisujemy w artykule ile kosztuje automatyzacja jednego procesu. Gdy łączysz kilka programów, zajrzyj do hasła integracja systemów.

Jeśli nie wiesz, czy wystarczy Ci program z KSeF, opisz, co dzieje się dziś z fakturami po ich otrzymaniu. Odpowiemy, czy własne narzędzie ma sens i co by robiło.

Zapytaj o integrację z KSeF

To opis praktyczny, nie porada podatkowa. W konkretnej sprawie zapytaj księgowego albo doradcę podatkowego.

Pytania i odpowiedzi

Czy muszę pisać własną integrację z KSeF?

Nie. Ministerstwo Finansów udostępnia bezpłatnie Aplikację Podatnika, aplikację mobilną i e-mikrofirmę, a program księgowy albo fakturowy z wbudowanym KSeF podłącza się tokenem. Własne narzędzie ma sens, gdy faktury mają trafiać dalej, na przykład do obiegu akceptacji kosztów.

Jakie uprawnienie nadać tokenowi, który tylko pobiera faktury?

Samo przeglądanie faktur. Token dostaje tylko te uprawnienia, które zaznaczysz przy tworzeniu, i nie da się ich potem zmienić. Szczegóły generowania opisuje hasło token KSeF.

Jak często można pobierać faktury z API KSeF?

Lista faktur ma limit 20 zapytań na godzinę dla pary NIP i adresu IP. Ministerstwo zaleca synchronizację do lokalnej bazy nie częściej niż co 15 minut i wyszukiwanie w tej kopii.

Co zrobić z tokenem, gdy odejdzie osoba, która go wygenerowała?

Unieważnić go na liście tokenów w Aplikacji Podatnika. Zrób to też po zakończeniu współpracy z wykonawcą, który generował token dla Twojej firmy.

Pojęcia z tego artykułu

• Token KSeF
• Integracja z KSeF
• API
• Integracja systemów
• Aplikacja webowa
• SharePoint
• Numer KSeF
• Certyfikat KSeF