Jak zintegrować własną aplikację z API KSeF 2.0 i ile to kosztuje?

Tekst wygenerowany przez AI · Wydawca: Tomasz Niedźwiecki · zawiera oznaczoną reklamę jego usług

Czy dostęp do API KSeF 2.0 kosztuje coś poza pracą?

Nie, samo API jest bezpłatne. Zestawienie Vatax, odczyt 26.10.2026, mówi wprost: „Dostęp do KSeF API Ministerstwa Finansów jest całkowicie bezpłatny”. Płacisz za godziny zespołu, który je podłączy, albo za komercyjną nakładkę, która robi to za Ciebie.

Cena nakładki zależy od dostawcy. Zestawienie Vatax podaje Symfonia API jako dodatkowy koszt „od 2340” zł rocznie, ale według jego przypisu cena ma stan na 3 września 2025 r., więc zweryfikuj ją u producenta. To oferta związana z programem Symfonia.

To samo zestawienie opisuje inFakt API, które pozwala tworzyć własne integracje, bez ceny samego API. Cennik fakturowania inFakt zaczyna się od 4,99 zł netto miesięcznie. W przeglądzie z odczytu 26.10.2026 nie znalazłem publicznego cennika neutralnej nakładki dla twórców aplikacji, więc cenę dopytaj u dostawcy.

Kontrakt API jest stabilny. Komunikat dla integratorów z 17.12.2025 zapowiada zamrożenie kontraktu, a lista endpointów, formaty żądań i odpowiedzi, kody odpowiedzi i reguły walidacji pozostają niezmienne. Integracja nie powinna więc zmieniać się pod Tobą co miesiąc.

Jak uwierzytelnić się w imieniu wielu firm-klientów?

Logujesz się w kontekście NIP klienta, a nie własnego. Dokumentacja, odczyt 26.10.2026, opisuje kontekst logowania jako element, który „określa podmiot, w imieniu którego wykonywane będą operacje w systemie”. Metody to podpis XAdES albo token KSeF, a certyfikat KSeF jest honorowany, choć nie jest kwalifikowany.

Każda operacja wymaga uprawnienia w tym kontekście. Jeśli Twój system nie ma aktywnego uprawnienia dla danego NIP-u, nie dostaje tokena dostępu. Przy 50 klientach oznacza to proces wdrożenia każdego z nich: klient albo jego administrator nadaje Twojej aplikacji uprawnienie do wystawiania faktur.

Dokumentacja uprawnień, odczyt 26.10.2026, zastrzega, że „Klient API, który nadaje te uprawnienia bezpośrednio, musi posiadać uprawnienie CredentialsManage lub rolę Owner.” Zaplanuj w aplikacji ekran, który prowadzi klienta przez nadanie uprawnienia i sprawdza jego status, bo nadanie jest operacją asynchroniczną.

Gdzie testować i czego nie mieszać między środowiskami?

Testujesz na środowisku testowym, a produkcji nie dotykasz, dopóki testy nie przejdą. Dokumentacja MF (repozytorium wskazane w komunikacie MF z 27.01.2026), odczyt 26.10.2026, podaje adres testowy api-test.ksef.mf.gov.pl. Strona KSeF z 29.01.2026 przypomina, że produkcja działa niezależnie od środowisk testowych i przedprodukcyjnych.

Z tej zasady wynika konkretna reguła dla Twojej konfiguracji. Zgodnie z odczytem strony KSeF z 26.10.2026: „Wykorzystywanie elementów ze środowisk testowych w środowiskach produkcyjnych będzie skutkować błędami technicznymi.” Trzymaj klucze, certyfikaty i tokeny każdego środowiska osobno i nie kopiuj ich między konfiguracjami.

Przetestuj trzy scenariusze, zanim wejdziesz do klienta: wysyłka poprawnej faktury, wysyłka faktury odrzuconej przez walidację i ponowienie po błędzie sieci. Pierwszy scenariusz sprawdza zgodność z FA(3), drugi obsługę komunikatów o błędach, a trzeci kolejkę ponowień.

Co zrobić, gdy KSeF albo Twoja aplikacja nie działa?

Przejść na tryb offline24 albo awaryjny i dosłać fakturę w terminie. Strona KSeF o trybie offline24, odczyt 26.10.2026, wymaga, aby podatnik „niezwłocznie przesyła fakturę do KSeF – najpóźniej w następnym dniu roboczym”. Przy awarii ogłoszonej w BIP MF i w oprogramowaniu interfejsowym termin to 7 dni roboczych od dnia zakończenia awarii.

Przy całkowitej awarii, ogłoszonej w środkach społecznego przekazu, faktury nie przesyła się do KSeF. Dla aplikacji to oznacza trzy rzeczy do zbudowania:

• kolejkę niewysłanych faktur z terminem wysyłki przy każdej pozycji,
• automatyczne ponawianie wysyłki po przywróceniu połączenia,
• widok dla klienta z listą faktur, którym kończy się termin.

Bez kolejki klient przekracza terminy, a odpowiedzialność za to zrzuci na Twoją aplikację. Dlatego tryb offline planujesz od pierwszej wersji, a nie po pierwszej awarii.

Jakie limity API wpływają na wystawianie faktur?

Limity decydują, czy wysyłasz faktury pojedynczo, czy paczkami. Dokumentacja limitów, odczyt 26.10.2026, podaje dla wysyłania faktur w sesji interaktywnej 10 żądań na sekundę, 30 na minutę i 180 na godzinę. Dla żądań przesyłających części paczki w sesji wsadowej limitów nie ma.

Dokumentacja podaje, że żądania są grupowane według pary: kontekst (NIP klienta) i adres IP. Przy jednym adresie IP serwera każdy NIP klienta ma więc osobny limit, a 50 firm nie zużywa sobie nawzajem limitów.

Szacunek własny na tej podstawie: hurtownia, która rano wystawia kilkaset faktur naraz, w sesji interaktywnej przekroczy godzinowy limit, więc potrzebuje sesji wsadowej. Mały gabinet z kilkunastoma fakturami dziennie zmieści się w interaktywnej bez problemu.

Nie rozpraszaj ruchu jednego klienta na wiele adresów IP. Ta sama strona mówi, że system zwraca uwagę na wzorce wskazujące na próby obchodzenia limitów, na przykład równoległe używanie wielu adresów IP w ramach jednego kontekstu. Limity mają też charakter dynamiczny, więc sprawdź je przed projektem.

Ile godzin i złotych kosztuje integracja bezpośrednia, a ile przez nakładkę?

Bezpośrednio z API Ministerstwa Finansów to szacunkowo 150–270 godzin, a przez nakładkę 60–102 godziny. Poniższa tabela to szacunek własny, nie cennik: godziny dla programisty, który zna API REST, ale nie zna KSeF.

Źródło: szacunek własny na podstawie zakresu opisanego w dokumentacji uwierzytelniania, odczyt 26.10.2026; stawka przyjęta do przeliczenia: 150 zł za godzinę.

Szacunek własny z tabeli powyżej (odczyt 26.10.2026): przy stawce 150 zł za godzinę bezpośrednia integracja to 22,5–40,5 tys. zł, a przez nakładkę 9–15,3 tys. zł plus licencja. Nakładka wygrywa, gdy zależy Ci na czasie. Integracja bezpośrednia wygrywa, gdy nie chcesz zależeć od cudzego cennika i cudzego limitu faktur.

Od kiedy klienci muszą wystawiać faktury w KSeF?

Zależy od wielkości firmy. Strona KSeF, odczyt 26.10.2026, podaje obowiązek od 1 lutego 2026 r. dla przedsiębiorców ze sprzedażą powyżej 200 mln zł w 2024 r., od 1 kwietnia 2026 r. dla pozostałych oraz od 1 stycznia 2027 r. dla tych, których miesięczna sprzedaż nie przekracza 10 tys. zł brutto.

Dla aplikacji branżowej to ważne, bo klienci z grupy najmniejszych firm dopiero się podłączają. Wymagania KSeF dla hurtowni opisuje tekst Co musi umieć program dla hurtowni. Dla biur rachunkowych jest osobny tekst: Co musi umieć aplikacja dla biura rachunkowego pod KSeF 2.0.

Koszt utrzymania całej aplikacji z KSeF policzysz w tekście Ile kosztuje miesięcznie utrzymanie aplikacji dla 50 płacących firm. Inne interfejsy branżowe, od BDO po e-Doręczenia, są w dziale Z czym to musi się połączyć.