Środowiska TEST, DEMO i PRD w KSeF: bezpieczny przewodnik

KSeF udostępnia trzy publiczne środowiska API, a każde służy do czegoś innego. TEST to współdzielone środowisko integracyjne do pracy z danymi syntetycznymi i symulowania błędów. DEMO korzysta z prawdziwej tożsamości i rzeczywistych uprawnień, więc pozwala sprawdzić integrację w warunkach zbliżonych do produkcji, ale treść faktur nadal musi być fikcyjna. PRD służy do wystawiania faktur wywołujących skutki prawne.

Bezpieczna integracja oddziela dane uwierzytelniające i rekordy każdego środowiska, a potem wdraża ten sam build z przypiętej rewizji kolejno w TEST, DEMO i PRD.

Ten przewodnik został zweryfikowany 28 sierpnia 2026 roku na podstawie dokumentacji Ministerstwa Finansów i CIRF. KSeF wdraża zmiany API osobno w poszczególnych środowiskach, dlatego przed każdym deployem sprawdzaj oficjalny changelog i aktualny kontrakt OpenAPI środowiska docelowego. To wskazówki techniczne, a nie porada podatkowa ani prawna.

Czym różnią się środowiska KSeF TEST, DEMO i PRD?

Nie chodzi wyłącznie o nazwę hosta. Każde środowisko ma własny model zaufania, zasady dotyczące danych, dane uwierzytelniające, wersję API i konsekwencje poprawnego wysłania dokumentu.

Te granice wynikają z informacji Ministerstwa o wsparciu dla integratorów oraz z zestawienia środowisk KSeF przygotowanego przez CIRF.

Warto znać również skróty, bo oficjalne materiały posługują się obiema formami: TEST występuje także jako TE lub środowisko integracyjne, a DEMO jako TR lub środowisko przedprodukcyjne.

Jedna reguła pozostaje aktualna niezależnie od wersji: nigdy nie przenoś między środowiskami rekordów ani danych uwierzytelniających. Przenoś sprawdzony kod i strukturę konfiguracji, a zasoby dla środowiska docelowego twórz od podstaw.

Jak skonfigurować adresy środowisk KSeF?

Wybieraj profil z krótkiej, zamkniętej listy środowisk, a nie dowolny adres URL. Proces produkcyjny nie powinien przyjmować bazowego hosta z parametru żądania, pola faktury ani ustawienia w bazie danych, które można zmienić w czasie działania.

Niewielka, niezmienna mapa sprawia, że wybór jest jawny:

KSEF_ENVIRONMENTS = {
  test: {
    api_base: "https://api-test.ksef.mf.gov.pl/v2",
    docs: "https://api-test.ksef.mf.gov.pl/docs/v2"
  },
  demo: {
    api_base: "https://api-demo.ksef.mf.gov.pl/v2",
    docs: "https://api-demo.ksef.mf.gov.pl/docs/v2"
  },
  production: {
    api_base: "https://api.ksef.mf.gov.pl/v2",
    docs: "https://api.ksef.mf.gov.pl/docs/v2"
  }
}.freeze

profile = KSEF_ENVIRONMENTS.fetch(ENV.fetch("KSEF_ENV").to_sym)

To tylko jawna część profilu. Poniższe wartości przechowuj osobno, jako jeden zestaw przypisany do konkretnego środowiska:

• odwołania do certyfikatu i klucza prywatnego;
• miejsce przechowywania tokenu KSeF oraz tokenów dostępu i odświeżania;
• cache kluczy publicznych KSeF i wybrany publicKeyId;
• przestrzeń nazw w bazie danych lub magazynie obiektowym dla plików XML i UPO;
• kolejkę, budżet ponowień i koordynator limitów żądań;
• dashboardy, alerty i etykiety logów;
• flagę zezwalającą na wysyłkę do PRD i wyłącznik awaryjny.

Ministerstwo w komunikacie o danych uwierzytelniających w środowisku produkcyjnym wyraźnie zaznacza, że klucze produkcyjne i dane uwierzytelniające KSeF należą do PRD. Token, certyfikat ani klucz szyfrujący ze środowiska TEST lub DEMO nie są danymi uwierzytelniającymi do produkcji.

Przewodnik po kluczach publicznych opisuje także ich rotację, więc nie przechowuj jednego globalnego klucza dla wszystkich trzech środowisk.

Nie zmieniaj adresów URL zwracanych przez KSeF

KSeF może zwrócić podpisane adresy URL do wysyłania lub pobierania plików. CIRF podaje, że ich hosty odpowiadają wywołanemu środowisku. Sprawdź zwrócony host względem listy dozwolonej dla wybranego środowiska, a potem użyj pełnego adresu URL bez zmian. Nie zastępuj hosta, nie dodawaj /v2 ani nie dołączaj produkcyjnego tokenu uwierzytelniającego do adresu prowadzącego do magazynu obiektowego.

Taki błąd łatwo przeoczyć, gdy metoda pomocnicza do zwykłych tras API otrzyma podpisany adres z magazynu obiektowego. Bazowe adresy API i zwracane adresy zasobów traktuj jako dwa różne typy.

Co testować w środowisku KSeF TEST?

W TEST sprawdzasz na danych syntetycznych, czy klient poprawnie obsługuje kontrakt i błędy. Dostęp do tego środowiska jest celowo łatwiejszy niż do produkcji, dlatego nie potwierdzi ono, że tożsamość ani uprawnienia przeznaczone dla produkcji zadziałają.

TEST przyjmuje certyfikaty samopodpisane i symulowane dane uwierzytelniające. Endpointy /testdata/* pozwalają tworzyć testowe osoby fizyczne, struktury podmiotów i uprawnienia, włączać scenariusze z załącznikami, blokować kontekst, skracać ważność certyfikatu oraz zmieniać profile limitów.

CIRF publikuje gotowe przykłady w przewodniku po scenariuszach danych testowych.

Wykorzystaj te mechanizmy do sprawdzenia stanów, które trudno wywołać w naturalny sposób:

1. poprawnego i niepoprawnego uwierzytelniania;
2. odmowy uprawnień po udanym uwierzytelnieniu;
3. wygaśnięcia i rotacji certyfikatu;
4. błędów wysyłki online i wsadowej;
5. obsługi HTTP 429 oraz wstrzymania wysyłki w całym systemie po wyczerpaniu limitu;
6. restartu procesu, gdy faktura nadal jest przetwarzana asynchronicznie;
7. nieznanych pól odpowiedzi i nowych nagłówków ostrzegawczych;
8. pobrania UPO po zniknięciu workera, który rozpoczął operację.

Celem nie jest jedna udana ścieżka. Potrzebujesz dowodu, że integracja pozostaje w stanie, który potrafisz rozpoznać i obsłużyć, gdy KSeF przyjmuje dokument, opóźnia odpowiedź, odrzuca żądanie, ogranicza ruch albo rozszerza odpowiedź o nowe pole.

Dlaczego prawdziwe dane są niebezpieczne w TEST?

TEST nie jest prywatnym, odizolowanym środowiskiem jednego integratora. Wielu integratorów może uwierzytelnić się w tym samym syntetycznym kontekście firmy, więc twoje dane testowe mogą zobaczyć inni. CIRF zaleca używanie losowych identyfikatorów i całkowitą rezygnację z prawdziwych danych podmiotów.

To ostrzeżenie nie dotyczy wyłącznie nazw. Nie wysyłaj prawdziwych numerów faktur, adresów, opisów pozycji, danych rachunków bankowych, adresów e-mail, odwołań do klientów ani produkcyjnego XML, w którym zmieniono tylko NIP. Wygeneruj kompletny zestaw syntetycznych danych testowych.

Odtwarzaj go w razie potrzeby, ponieważ dane w TEST są okresowo usuwane, a żadne aktualne oficjalne źródło nie gwarantuje konkretnego czasu przechowywania.

Kod aplikacji powinien odrzucać produkcyjne identyfikatory klientów i znane prefiksy numerów faktur produkcyjnych jeszcze przed serializacją. Taka kontrola nie może pozostać tylko punktem na checkliście przed deployem.

Co sprawdzić w KSeF DEMO?

DEMO weryfikuje elementy celowo symulowane w TEST: prawdziwą tożsamość używaną do uwierzytelniania, rzeczywiste relacje między podmiotami i prawdziwe łańcuchy uprawnień. To ostatnia próba przed wdrożeniem wersji produkcyjnej, a nie drugie środowisko do swobodnego tworzenia fikcyjnych tożsamości.

Ministerstwo w komunikacie o uruchomieniu DEMO podaje, że środowisko korzysta z rzeczywistych danych uwierzytelniających oraz uprawnień odpowiadających produkcji.

To tutaj wychodzi na jaw różnica między „nasz kod XAdES działa” a „ten certyfikat rzeczywiście uprawnia do działania w imieniu tego podatnika”. Szczegóły znajdziesz w przewodniku po uwierzytelnianiu w KSeF.

Przed deployem DEMO powinno odpowiedzieć na pięć pytań:

• Czy prawdziwa organizacja może uwierzytelnić się planowaną ścieżką z użyciem certyfikatu?
• Czy docelowi operatorzy i systemy mają rzeczywiste uprawnienia KSeF?
• Czy wersja gotowa do wdrożenia działa z formatami faktur obsługiwanymi w PRD?
• Czy pozostaje stabilny przy limitach żądań zbliżonych do produkcyjnych?
• Czy po restarcie potrafi wznowić odpytywanie o status i zapisywanie dowodów?

Użyj dokładnie tego buildu, który planujesz wdrożyć. Unikaj gałęzi przeznaczonych tylko dla DEMO i ręcznych poprawek. Jeśli potrzebujesz różnicy w konfiguracji, umieść ją w profilu środowiska, a nie w kodzie, który po cichu zmienia zachowanie.

Prawdziwy login nie oznacza prawdziwej treści faktury

DEMO łączy prawdziwą tożsamość z fikcyjną treścią faktur. Ministerstwo informuje, że wystawione tam faktury nie wywołują skutków prawnych i są później usuwane. Zastrzega też, że środowisko może zawierać niezanonimizowane dane przeniesione ze środowiska produkcyjnego lub z niego pochodzące, dlatego jest chronione na poziomie produkcyjnym.

Oba stwierdzenia są prawdziwe. Dane wejściowe twoich testów muszą być fikcyjne, natomiast dane już zapisane w DEMO mogą nadal być wrażliwe. Stosuj produkcyjną kontrolę dostępu i maskowanie logów. Nie opisuj DEMO jako bazy nieszkodliwych rekordów przykładowych.

Dlaczego nawet smoke test w PRD oznacza prawdziwą fakturę?

PRD nie ma nieszkodliwego trybu „faktury testowej”. Jeśli KSeF przyjmie dokument i nada mu numer KSeF, faktura wchodzi do obrotu prawnego.

Ministerstwo w Podręczniku KSeF 2.0, części II ostrzega, że przypadkowa faktura testowa wystawiona na produkcji może wywołać konsekwencje w VAT.

Artykuł 108 ust. 1 ustawy o VAT mówi jasno: wystawca, który wykazał na fakturze kwotę podatku, ma obowiązek go zapłacić.

Pierwsza kontrolowana wysyłka musi więc dotyczyć prawdziwej transakcji gospodarczej. Zanim ją uruchomisz:

• utwórz produkcyjne dane uwierzytelniające bezpośrednio w PRD, zamiast kopiować je z DEMO;
• sprawdź kontekst podatnika i uprawnienia za pomocą wywołań, które nie wystawiają faktur;
• potwierdź, że faktura jest prawdziwa, zatwierdzona i gotowa do ujęcia w księgach;
• zacznij z pustą lub ściśle kontrolowaną kolejką;
• zapewnij operatora, który będzie obserwować status, numer KSeF i UPO;
• przygotuj sposób na zatrzymanie nowych wysyłek bez utraty odwołań do przyjętych dokumentów.

Nie twórz automatycznego przełączenia awaryjnego z TEST ani DEMO do PRD. Ponowienie nie może zmieniać wybranego środowiska. Zapisuj środowisko obok każdego odwołania do sesji, odwołania do faktury, numeru KSeF i klucza obiektu UPO, żeby uzgadnianie danych nie przekroczyło tej granicy.

Przewodnik po UPO i odpytywaniu o status wyjaśnia, jakie dowody trzeba przechowywać dla każdej przyjętej faktury. Odpowiedź HTTP 202 ani odwołanie do sesji nie oznaczają jeszcze ostatecznego przyjęcia.

Jak różnice wersji API KSeF wpływają na wdrożenie?

TEST może korzystać z nowszej wersji niż DEMO i PRD. Zapowiada dzięki temu nadchodzącą zmianę, ale oznacza też, że zielony wynik w jednym środowisku może dotyczyć innego kontraktu niż w środowisku docelowym.

Oficjalny changelog odnotowuje API 2.7.1 w TEST od 26 sierpnia 2026 roku, a wdrożenia w DEMO i PRD planuje odpowiednio na 15 i 23 września. W dniu weryfikacji najnowszą wersją oznaczoną jako wdrożona w PRD była 2.6.1. Te numery szybko stracą aktualność, ale kolejność wdrażania zmian pozostanie ważna.

Przed każdym deployem zapisz:

Nie generuj klienta z gałęzi main repozytorium i nie zakładaj, że odpowiada ona produkcji. Przypnij sprawdzoną wersję kontraktu, toleruj udokumentowane dodatkowe pola odpowiedzi i przed deployem uruchom testy zgodności ze środowiskiem docelowym.

Limity żądań dobrze pokazują, dlaczego to ważne. Starsze oficjalne materiały podawały, że wartości domyślne w TEST są dziesięciokrotnie wyższe niż w produkcji. Późniejszy changelog API 2.5.0 informuje o zrównaniu domyślnych limitów TEST z PRD, przy zachowaniu endpointów symulacyjnych w TEST.

Bezpieczna reguła jest prosta: sprawdzaj obowiązujące limity w czasie działania i korzystaj ze szczegółowego przewodnika po ponowieniach żądań KSeF, zamiast wpisywać mnożnik na stałe w kodzie.

Jak wygląda bezpieczna checklista wdrożenia KSeF?

Wdrażaj na podstawie dowodów, nie założeń. Poniższa checklista jest podsumowaniem praktyk inżynierskich, a nie procedurą nakazaną przez Ministerstwo.

W testach lokalnych i CI

• Przypnij schematy FA(3) i deterministyczne dane testowe.
• Sprawdź dokładne bajty, dla których obliczasz skrót, a następnie szyfrujesz i wysyłasz.
• Trzymaj wybór środowiska poza danymi faktury.
• Odrzucaj każdy host spoza trzech oficjalnych list dozwolonych adresów.
• Testuj nieznane pola i przerwane operacje asynchroniczne.

W TEST

• Twórz od nowa syntetyczne tożsamości i treści dokumentów.
• Przećwicz udane i odrzucone wysyłki, ograniczenie ruchu, wygaśnięcie danych uwierzytelniających oraz restart.
• Potwierdź, że żadne produkcyjne identyfikatory ani sekrety nie trafiają do logów lub magazynu danych.
• Zapisz wersję OpenAPI TEST używaną podczas testu.

W DEMO

• Uwierzytelnij się za pomocą prawdziwej tożsamości organizacji przeznaczonej dla środowiska docelowego.
• Sprawdź rzeczywisty graf uprawnień.
• Wysyłaj wyłącznie fikcyjne lub zanonimizowane treści faktur.
• Uruchom wersję gotową do wdrożenia z limitami zbliżonymi do produkcyjnych.
• Po wymuszonym restarcie uzgodnij status, odwołania i UPO.

Przed przejściem do PRD i w jego trakcie

• Porównaj aktualny dokument OpenAPI środowiska PRD z wersją kontraktu przypiętą do klienta.
• Utwórz nowe certyfikaty, tokeny, uprawnienia i cache kluczy publicznych przeznaczone dla PRD.
• Włącz zabezpieczenia blokujące testowe konteksty podatników i dane testowe.
• Najpierw sprawdź operacje, które nie wystawiają faktur.
• Wyślij jedną prawdziwą fakturę, a następnie uzgodnij jej ostateczny status i UPO.
• Stopniowo zwiększaj liczbę dokumentów, obserwując odpowiedzi 429, błędy i wiek zadań w kolejce.

Trzymaj przewodnik po strukturze FA(3) obok tej checklisty. Przejście walidacji XSD i testów w TEST potwierdza strukturę XML oraz zachowanie klienta, a nie rozliczenie podatkowe ani prawną kompletność prawdziwej faktury. Przy błędach korzystaj z przewodnika po rozwiązywaniu problemów z walidacją KSeF, nie ponawiając bez zastanowienia wysyłki o niejednoznacznym wyniku.

Jak KSeF Kit chroni granice między środowiskami?

Najbezpieczniej przełączać środowisko w sposób, którego zespół nie musi samodzielnie utrzymywać. KSeF Kit to osobny produkt dla zespołów, których źródłem faktur jest Stripe. Mapuje sfinalizowane faktury Stripe do FA(3), wysyła je, czeka na wynik KSeF, przechowuje UPO i zapisuje numer KSeF z powrotem w rekordzie źródłowym.

Publiczny przewodnik po połączeniu z KSeF opisuje konfigurację TEST i produkcji. Dla rozliczeń w Stripe jest to gotowa alternatywa dla własnej integracji, bez obietnicy obsługi każdego systemu księgowego, typu faktury czy decyzji podatkowej.

Niezależnie od tego, czy korzystasz z gotowego rozwiązania, czy z własnego klienta, trzymaj się tej samej granicy: w TEST pracuj na danych syntetycznych, w DEMO używaj prawdziwej tożsamości i fikcyjnych faktur, a do PRD wysyłaj wyłącznie prawdziwe, zatwierdzone dokumenty. Między środowiskami przenoś kod. Nigdy nie przenoś ich sekretów ani danych.