Grzegorz Giewon · UnitSoftware

Środowisko testowe bramki JPK — strona MF jest z 2020 roku, a zasady zmieniły się w styczniu

3.09.2026

Stronę „Środowisko testowe dla wysyłki plików JPK”, od której wszyscy zaczynają, Ministerstwo opublikowało 28 lutego 2020. Mówi o JPK_V7M i JPK_V7K, o autoryzacji danymi kwotowymi i o tym, że UPO z testu nie jest podpisane. W zarysie wciąż prawdziwa — ale to nie jest dokument, na którym da się oprzeć integrację w 2026.

Aktualne zasady żyją w Specyfikacji interfejsów usług JPK na Portalu podatkowym. Dziś to wersja 5.2.0 z 20 stycznia 2026, a numer zmienia się średnio co kilka tygodni — samo 5.1.0 dostało cztery wydania między sierpniem a listopadem 2025. Przy każdej zmianie w pipelinie warto zacząć od sprawdzenia, czy pracujecie na tej wersji, co bramka.

Co środowisko testowe obejmuje dzisiaj

Adres bez zmian: https://test-e-dokumenty.mf.gov.pl (REST: /api/Storage/InitUploadSigned, /FinishUpload, /Status/{referenceNumber}). Poza JPK_V7M/JPK_V7K przyjmuje na teście:

  • JPK_KR_PD(1) i JPK_ST_KR(1) — księgi i środki trwałe (JPK CIT), schematy produkcyjne od 1 stycznia 2025;
  • JPK_EWP(4), JPK_PKPIR(3), JPK_ST(1) — dodane w 5.1.0, produkcyjnie od 1 stycznia 2026;
  • JPK_V7M(3) / JPK_V7K(3) — warianty dostosowane do KSeF, dodane w 5.2.0, produkcyjnie od 1 lutego 2026.

Części plików lądują w innej puli magazynów niż na produkcji — taxdocumentstorage{00..02,97..99}tst.blob.core.windows.net. Reguła na firewallu wypuszczająca ruch tylko na adresy produkcyjne zablokuje wysyłkę testową i nie jest to oczywiste w logu.

Zmiana, którą łatwo przegapić: weryfikacja podpisu

Komunikatami z listopada i grudnia 2025 (aktualizacja w styczniu 2026) MF zmieniło sposób weryfikacji podpisów elektronicznych w e-dokumenty.mf.gov.pl — „w celu dostosowania do obowiązujących standardów”. Najpierw na teście, potem na produkcji. Termin dla integratorów na potwierdzenie, że ich systemy działają na środowisku testowym: 15 stycznia 2026. Datę wdrożenia produkcyjnego Ministerstwo zastrzegło do osobnego komunikatu. Konsekwencja jest w komunikacie napisana wprost: „brak dostosowania do nowych standardów będzie powodowało odrzucenie przesyłanych plików przez system na środowisku produkcyjnym”.

Konkret ze specyfikacji: prawidłowy podpis XAdES-BES (dopuszczalny też BES-T ze znacznikiem czasu) musi mieć dwie referencje w ds:SignedInfo — do elementu SignedProperties i do całego dokumentu XML. Brak którejkolwiek → odrzucenie. Tryb enveloped albo enveloping; detached nie przejdzie (kod 130). Funkcja skrótu RSA-SHA256. Jeśli wasza biblioteka podpisu generuje jedną referencję albo domyślnie robi detached — to jest do sprawdzenia teraz, nie pod terminem złożenia.

Trzy rzeczy, których środowisko testowe wam nie powie

  1. Certyfikat kwalifikowany domyślnie nie jest sprawdzany. Na teście InitUploadSigned przyjmie plik podpisany certyfikatem self-signed — MF sam publikuje taki przykładowy plik. Autentyczność podpisu kwalifikowanego test zweryfikuje dopiero po wywołaniu z parametrem ?enableValidateQualifiedSignature=true. Na produkcji jest sprawdzana zawsze. Bez tego parametru zielony wynik na teście nie mówi nic o tym, czy wasz produkcyjny podpis jest poprawny.
  2. Pełnomocnictwo na teście jest symulowane, nie sprawdzane. Środowisko testowe nie odpytuje rejestru pełnomocnictw. Zgodnie z komunikatem MF o wyniku decyduje ostatnia cyfra NIP z deklaracji: „Jeżeli NIP z deklaracji kończy się na cyfrę 0, 1, 3, 4 – to pełnomocnictwo jest prawidłowe” — każda inna cyfra to odrzucenie „brak aktualnego pełnomocnictwa” (kod 420), nawet jeśli macie w MF ważne UPL-1. Tak samo dane autoryzujące: parzysta ostatnia cyfra NIP/PESEL przechodzi, nieparzysta nie; usługa CRL zawsze odpowiada pozytywnie. Ścieżkę pełnomocnika realnie zweryfikujecie dopiero na produkcji.
  3. UPO z testu nie jest podpisane. Jeśli po swojej stronie walidujecie podpis Urzędowego Poświadczenia Odbioru — na teście ta ścieżka nie zadziała. Trzeba ją wyłączać warunkowo dla środowiska testowego, a nie „na oko”.

Certyfikaty i okna serwisowe

Certyfikaty SSL i klucze publiczne bramki — testowej i produkcyjnej — są wymieniane po kilka razy w roku (klucz publiczny testu: lipiec 2025; klucz szyfrujący produkcji: lipiec 2025; SSL produkcji: 28 kwietnia 2026, ważny do 7 listopada 2026). Jeśli pinujecie certyfikat albo macie własny truststore, każda taka wymiana to nagła awaria wysyłki bez jednej linijki zmiany u was. W kodzie musi być ścieżka na odświeżenie klucza publicznego z Portalu podatkowego.

Samo środowisko testowe też bywa niedostępne niezależnie od produkcji i ma własne przerwy serwisowe. Stan bramki najszybciej widać pod test-e-dokumenty.mf.gov.pl (przy działającej usłudze odpowiada Swagger UI) oraz na niezależnym monitorze ealerty.pl/e-dokumenty.

Co z tego wynika

Strona MF, od której wszyscy zaczynają, jest sześć lat za specyfikacją. Jedyne wiarygodne źródło to Specyfikacja interfejsów usług JPK na Portalu podatkowym — i jej numer wersji. A „przechodzi na teście” i „przejdzie na produkcji” to dwa różne zdania, głównie przez podpis: wywołujcie InitUploadSigned z enableValidateQualifiedSignature=true i podpisujcie test tym samym certyfikatem, którym podpiszecie produkcję.

Jeśli macie pipeline JPK, który formalnie jest „gotowy”, a i tak co miesiąc generuje zgłoszenia — napiszcie. Powiem, gdzie to pęka i czy to robota na tydzień, czy na kwartał.

Podłączam firmowe systemy do KSeF i JPK. Umów bezpłatną rozmowę, jeśli mierzysz się z podobnym problemem.