Jak korzystać ze środowiska testowego KSeF?

Środowisko testowe KSeF ma własną wersję Aplikacji Podatnika pod adresem ap-test.ksef.mf.gov.pl/web/. Dokumenty, które tam wyślesz, nie są fakturami i nie wywołują skutków prawnych, a wpisywać możesz wyłącznie fikcyjne dane.

Stan na 12 listopada 2026 r.

MF: Aplikacja Podatnika KSeF 2.0 Podręcznik KSeF 2.0, cz. II, rozdz. 3.2.1

Czym różnią się TEST, DEMO i produkcja?

KSeF 2.0 ma trzy publiczne środowiska. TEST służy do testowania integracji i dostaje nowe wersje systemu jako pierwszy. DEMO (środowisko przedprodukcyjne) jest skonfigurowane jak produkcja i służy do końcowego sprawdzenia integracji. Na produkcji (PROD) wystawiasz i odbierasz faktury o pełnej mocy prawnej.

Adresy testowej i przedprodukcyjnej Aplikacji Podatnika podaje MF na stronach obu wersji. W starszych poradnikach krąży jeszcze adres web2te-ksef.mf.gov.pl, który już nie działa.

TEST przyjmuje też starszy schemat FA(2), a DEMO i produkcja już nie. Plik przyjęty w TEST nie musi więc przejść na produkcji.

CIRFMF: środowiska KSeF

Co wolno wpisać w środowisku testowym?

Wpisuj tylko wymyślone dane. Dokumentacja MF zabrania wysyłania do TEST i DEMO faktur produkcyjnych oraz rzeczywistych danych firm, a do testów każe używać losowych numerów NIP.

Powód jest praktyczny: TEST przyjmuje samopodpisane certyfikaty, więc wiele osób może zalogować się w kontekście tej samej firmy. Dane wpisane w TEST nie są odizolowane i mogą je zobaczyć inni użytkownicy. Nie wpisuj więc prawdziwego klienta ani jego adresu. MF zapowiada, że dane w testowej i przedprodukcyjnej Aplikacji Podatnika są okresowo usuwane, ale nie podaje terminów.

CIRFMF: środowiska KSeF, Uwaga MF: Aplikacja Podatnika KSeF 2.0, wersja testowa

Co jeszcze odróżnia TEST od produkcji:

• Przerwy serwisowe. Od 1 października 2025 r. w środowiskach testowych mogą być prowadzone cykliczne prace serwisowe w godzinach 16:00–18:00 i mogą wtedy wystąpić utrudnienia. Dodatkowe prace MF zapowiada w komunikatach technicznych (np. w komunikatach z 17 i 22 czerwca 2026 r.).
• UPO z dopiskiem. W UPO z TEST jako podmiot przyjmujący widnieje „Ministerstwo Finansów - środowisko testowe (TE)”, a z DEMO „Ministerstwo Finansów - środowisko przedprodukcyjne (TR)”. Na produkcji jest samo „Ministerstwo Finansów”.
• Kody QR prowadzą na testowy adres. Kod QR z faktury testowej prowadzi do qr-test.ksef.mf.gov.pl, a nie do weryfikacji na produkcji (qr.ksef.mf.gov.pl).

CIRFMF: historia zmian API, 2.0.0 RC6.0 CIRFMF: kody QR Podręcznik KSeF 2.0, cz. II, rozdz. 3.2.3

Jak zalogować się do środowiska testowego?

Do testowej Aplikacji Podatnika zalogujesz się bez certyfikatu kwalifikowanego. Na ekranie logowania wybierz „Zaloguj uwierzytelnieniem testowym”, podaj kontekst (np. NIP firmy) i wpisz NIP albo PESEL. Serwer sam podpisze żądanie certyfikatem testowym. Profilem Zaufanym w TEST się nie zalogujesz: ta opcja działa tylko w DEMO i na produkcji. Certyfikat kwalifikowany TEST przyjmie, ale MF odradza używanie tam podpisów z prawdziwymi danymi. Logowanie na produkcji opisujemy w poradniku o logowaniu do KSeF.

Samodzielnie wygenerowany certyfikat zamiast kwalifikowanego przyjmuje tylko TEST. Przy połączeniu przez API taki certyfikat tworzy m.in. program KSeF.Client.Tests.CertTestApp z oficjalnej biblioteki C# (o niej niżej). To narzędzie dla programistów.

DEMO wymaga faktycznych danych logowania i faktycznych uprawnień, tak jak produkcja: logujesz się np. Profilem Zaufanym, w kontekście NIP-u zgodnego z rejestrem właścicieli firm. Dlatego podręcznik MF nazywa DEMO niedostępnym publicznie, choć dokumentacja API wymienia je wśród środowisk publicznych. Uprawnienia i certyfikaty nadane w produkcyjnym Module Certyfikatów i Uprawnień (MCU) nie są w DEMO dostępne, a to, co zrobisz w DEMO, nie zmienia niczego na produkcji.

MF: instrukcja uwierzytelnienia w Aplikacji Podatnika KSeF 2.0, wersja testowa MF: Aplikacja Podatnika KSeF 2.0, wersja przedprodukcyjna (Demo) CIRFMF: uwierzytelnianie Podręcznik KSeF 2.0, cz. II, rozdz. 3.2.2

Jak przećwiczyć wystawienie faktury?

1. Otwórz ap-test.ksef.mf.gov.pl/web/ i sprawdź adres w przeglądarce: ma zawierać „ap-test”. Zaloguj się uwierzytelnieniem testowym z wymyślonym NIP-em.
2. Wystaw fakturę z wymyślonym nabywcą i kwotą. Formularz krok po kroku pokazujemy w poradniku o pierwszej fakturze w Aplikacji Podatnika.
3. Pobierz UPO i sprawdź dopisek „środowisko testowe (TE)”.

Jeśli fakturujesz w programie, a nie w przeglądarce, przełącz go na środowisko testowe i wyślij z niego fakturę testową. Gdy masz już plik XML, możesz go przed wysyłką sprawdzić w walidatorze według schematu FA(3), którego wymaga produkcja.

Jak połączyć program z API środowiska testowego?

Marek łączy system ERP z KSeF. Bazowy adres API w TEST to https://api-test.ksef.mf.gov.pl/v2 (ścieżka /v2, nie /api/v2). Oficjalne biblioteki MF łączą się z DEMO i produkcją przez hosty api-demo.ksef.mf.gov.pl i api.ksef.mf.gov.pl z tymi samymi ścieżkami /v2/.... Adresy URL, które zwraca API, zawsze wskazują środowisko, do którego trafiło żądanie.

Specyfikację TEST pobierzesz jako openapi.json, a interaktywną dokumentację znajdziesz pod docs/v2/index.html.

CIRFMF: open-api.json (2.9.0)

Jak przygotować dane testowe?

Endpointy /testdata/* przygotowują dane do scenariuszy testowych:

• POST /testdata/person: osoba fizyczna z uprawnieniami właścicielskimi. Z isBailiff: false odpowiada JDG: osoba logująca się PESEL-em lub NIP-em dostaje uprawnienie Owner. Z isBailiff: true dochodzi EnforcementOperations (komornik).
• POST /testdata/subject: grupa VAT albo JST z jednostkami podrzędnymi, potem uprawnienia przez POST /testdata/permissions.
• POST /testdata/attachment i /revoke: włączenie i wyłączenie załączników.
• POST /testdata/context/block i unblock: zablokowany kontekst, uwierzytelnienie kończy się błędem 480.
• PUT /testdata/certificates/{serialNumber}: skrócenie ważności certyfikatu.
• Endpointy /testdata/limits/* i /testdata/rate-limits: zmiana limitów, bez wpływu na produkcję.

Część z nich ma w specyfikacji dopisek „Tylko na środowiskach testowych”. Dokumentacja nie definiuje, czy obejmuje to DEMO. POST /testdata/rate-limits/production działa wyłącznie w TEST.

CIRFMF: dane testowe, scenariusze

Jakie limity obowiązują w TEST?

Dokumentacja MF przeczy sama sobie. Strona o limitach podaje, że limity w TEST są dziesięciokrotnie wyższe niż na produkcji, a historia zmian wersji 2.5.0 mówi, że zrównano je z produkcją. W DEMO limity są takie same jak na produkcji. Aktualne wartości odczytasz z GET /rate-limits.

CIRFMF: limity API

Co jeszcze działa w środowiskach testowych?

• Nagłówek X-Test-System-Warning wymusza ostrzeżenie systemowe w odpowiedzi.
• Nagłówek X-KSeF-Feature: subject-identifier-validation włącza sprawdzanie numerów NIP i identyfikatorów wewnętrznych na fakturach (dokumentacja nie precyzuje, czy działa też w DEMO).
• Nowe wersje API trafiają najpierw do TEST, potem do DEMO i produkcji. Wersja 2.9.0 weszła do TEST i DEMO 13 października 2026 r., a na produkcję 15 października.

MF utrzymuje dwie biblioteki open source: ksef-client-csharp (C#) i ksef-client-java (Java). Środowisko wybierasz w ich konfiguracji, a przykładowe aplikacje z obu repozytoriów domyślnie łączą się z TEST. CertTestApp z biblioteki C# wymaga .NET 10 SDK i domyślnie losuje NIP.

CIRFMF: historia zmian API CIRFMF: testowe certyfikaty i podpisy XAdES

Gdy faktura testowa przejdzie, a UPO ma dopisek „(TE)”, prawdziwą fakturę wystawisz w produkcyjnej aplikacji na ap.ksef.mf.gov.pl.