KSeF API środowisko testowe
Środowisko testowe KSeF
Ministerstwo Finansów udostępnia środowisko testowe KSeF API 2.0 pod adresem https://ksef-test.mf.gov.pl/. Pozwala ono na testowanie integracji przed wdrożeniem produkcyjnym.
Otwarte testy API KSeF 2.0 ruszyły 30 września 2025 r. Środowisko testowe jest stale dostępne dla integratorów, programów księgowych oraz dostawców rozwiązań IT.
W środowisku testowym dopuszcza się użycie samodzielnie wygenerowanych certyfikatów będących odpowiednikiem certyfikatów kwalifikowanych, co umożliwia wygodne testowanie bez ponoszenia kosztów.
Dokumentacja interaktywna (OpenAPI, Swagger) dostępna jest pod adresem https://ksef-test.mf.gov.pl/docs/v2/index.html. Zawiera schematy wywołań endpointów, przykładowe payloady oraz opis autoryzacji.
Oprócz środowiska testowego dostępne jest środowisko przedprodukcyjne (demo) pod adresem https://ksef-demo.mf.gov.pl/ – służy do testowania z rzeczywistymi danymi bez skutków prawnych.
Instrukcja krok po kroku
1. Wybierz właściwe środowisko
TE (ksef-test.mf.gov.pl/api/v2) obsługuje FA(2), FA(3) i PEF, TR (ksef-demo.mf.gov.pl/api/v2) odzwierciedla produkcję i przyjmuje FA(3), a PRD (ksef.mf.gov.pl/api/v2) służy do realnych dokumentów.
2. Przygotuj certyfikaty i klucze
Na TE możesz używać certyfikatów self-signed opisanych w dokumentacji MF. W TR/PRD wymagany jest kwalifikowany podpis, certyfikat KSeF lub token KSeF przypisany do kontekstu NIP/InternalId/NipVatUe.
3. Utwórz dane testowe
Wykorzystaj /v2/testdata/person, /subject, /permissions i /attachment, aby zasymulować JDG, komorników, grupy VAT oraz włączanie załączników. Dzięki temu zasady uprawnień odzwierciedlają produkcję.
4. Uwierzytelnij się i generuj tokeny
Przeprowadź proces challenge → AuthTokenRequest (XAdES) lub token KSeF → status → redeem i wygeneruj accessToken. Na TE możesz wielokrotnie odświeżać testowe tokeny.
5. Monitoruj okna serwisowe
Na TE od 1 października 2025 r. prowadzone są prace serwisowe 16:00–18:00. Zaplanuj testy poza tym czasem i pamiętaj, że dane w TE są współdzielone przez innych integratorów.
Najczęstsze problemy i rozwiązania
Środowisko TE nie odpowiada w godzinach popołudniowych
To planowe prace serwisowe (16:00–18:00). Poczekaj do zakończenia lub przenieś testy na TR. Informacje o zmianach trafiają do changelogu MF.
Błąd uprawnień mimo poprawnego payloadu
Na TE dane są współdzielone – inny integrator mógł odebrać Twoje uprawnienia. Użyj /testdata/permissions, aby ponownie nadać prawa lub generuj nowe identyfikatory.
Self-signed certyfikat nie działa w TR/PRD
Self-signed jest obsługiwany tylko na TE. Do TR/PRD potrzebujesz kwalifikowanego podpisu, certyfikatu KSeF lub wygenerowanego tokena KSeF z prawdziwymi danymi.
Adresy i formaty na TE/TR/PRD
| Kod | URL | Dostępne struktury |
|---|---|---|
| TE | https://ksef-test.mf.gov.pl/api/v2 | FA(2), FA(3), FA_PEF(3), FA_KOR_PEF(3) |
| TR | https://ksef-demo.mf.gov.pl/api/v2 | FA(3), FA_PEF(3), FA_KOR_PEF(3) |
| PRD | https://ksef.mf.gov.pl/api/v2 | FA(3), FA_PEF(3), FA_KOR_PEF(3) |
Dokumentacja i biblioteki
Interaktywna dokumentacja znajduje się pod https://ksef-test.mf.gov.pl/docs/v2/index.html, a plik JSON OpenAPI pod /docs/v2/openapi.json. Oficjalne biblioteki ksef-client-csharp i ksef-client-java są rozwijane na GitHub i publikowane w NuGet/Maven.
Certyfikaty i logowanie
Na TE możesz używać self-signed X.509, co przyspiesza prototypowanie. TR i PRD wymagają kwalifikowanego podpisu, certyfikatu KSeF lub tokena KSeF wygenerowanego po zgłoszeniu ZAW-FA. System zawsze weryfikuje kontekst (NIP, InternalId, NipVatUe).
Okna serwisowe i współdzielenie danych
Od 1 października 2025 r. MF prowadzi codzienne prace serwisowe na TE w godzinach 16:00–18:00. Dane są współdzielone przez integratorów, dlatego należy używać losowych identyfikatorów i nie przesyłać rzeczywistych informacji biznesowych.
Pomocnicze API testowe
Endpointy /v2/testdata/person, /subject, /permissions, /attachment umożliwiają tworzenie scenariuszy z JDG, komornikiem, grupą VAT czy obsługą załączników. Pozwalają też nadać Owner/CredentialsManage/SubunitManage bez udziału urzędu.
FAQ
Jaki jest adres środowiska testowego KSeF?
Środowisko testowe dostępne jest pod adresem https://ksef-test.mf.gov.pl/. Dokumentacja API: https://ksef-test.mf.gov.pl/docs/v2/index.html.
Czy muszę mieć certyfikat kwalifikowany do testów?
Nie, w środowisku testowym można używać samodzielnie wygenerowanych certyfikatów (self-signed). Certyfikaty kwalifikowane wymagane są tylko na produkcji.
Gdzie znajdę dokumentację OpenAPI?
Dokumentacja interaktywna dostępna jest pod adresem https://ksef-test.mf.gov.pl/docs/v2/index.html. Plik JSON OpenAPI: https://ksef-test.mf.gov.pl/docs/v2/openapi.json.
Czym różni się środowisko testowe od demo?
Środowisko testowe (ksef-test.mf.gov.pl) służy do testów integracji. Środowisko demo (ksef-demo.mf.gov.pl) pozwala na testy z rzeczywistymi danymi i uprawnieniami, ale bez skutków prawnych.
Czy są dostępne gotowe dane testowe?
Tak. Skorzystaj z endpointów /v2/testdata/*, aby automatycznie wygenerować podmioty, jednostki, grupy VAT i nadać uprawnienia. To najprostszy sposób na odtworzenie scenariuszy z dokumentacji MF.
Dlaczego TE bywa chwilowo niedostępne?
Ministerstwo Finansów prowadzi cykliczne prace serwisowe TE między 16:00 a 18:00. W tym czasie dostęp może być ograniczony – to normalne zachowanie środowiska testowego.