Sandbox KSeF — jak testować integrację na środowisku testowym

Sandbox KSeF — jak testować integrację?

Ministerstwo Finansów udostępnia środowisko testowe KSeF (sandbox), na którym możesz testować integrację bez żadnych konsekwencji prawnych. Poniżej poradnik jak z niego korzystać.

Co to jest sandbox KSeF?

Sandbox (środowisko testowe) to oddzielna instancja systemu KSeF, działająca niezależnie od środowiska produkcyjnego. Operacje wykonane w sandboxie:

•Nie mają skutków prawnych ani podatkowych

•Nie są widoczne w systemie produkcyjnym

•Możesz bezpiecznie testować wszystkie funkcje API

URL środowiska testowego

•API: https://ksef-test.mf.gov.pl/api

•Portal: https://ksef-test.mf.gov.pl

Różnice między środowiskiem testowym a produkcyjnym

| Aspekt | Testowe | Produkcyjne |

|--------|---------|-------------|

| URL | ksef-test.mf.gov.pl | ksef.mf.gov.pl |

| Certyfikaty | Testowe (lub produkcyjne) | Produkcyjne |

| Konsekwencje | Brak | Prawne i podatkowe |

| Dostępność | Może być niestabilna | Objęta SLA |

| Dane | Można używać testowych NIP | Rzeczywiste dane firmy |

Jak zacząć testowanie?

Krok 1: Zarejestruj się na środowisku testowym

Wejdź na ksef-test.mf.gov.pl i zaloguj się profilem zaufanym lub certyfikatem kwalifikowanym.

Krok 2: Wygeneruj testowy token

Na środowisku testowym wygeneruj token tak samo jak na produkcji. Pamiętaj — token testowy działa tylko z URL testowym.

Krok 3: Skonfiguruj środowisko w kodzie

Dodaj flagę lub zmienną środowiskową do przełączania między testowym a produkcyjnym URL API.

// Zmienna środowiskowa
KSEF_ENV=test  →  https://ksef-test.mf.gov.pl/api
KSEF_ENV=prod  →  https://ksef.mf.gov.pl/api

Krok 4: Wyślij pierwszą testową fakturę

Wyślij fakturę z testowymi danymi. Sprawdź czy:

•Sesja otwiera się poprawnie

•Faktura przechodzi walidację

•Statusy są aktualizowane

•UPO jest generowane

Testowe NIP w sandboxie

Na środowisku testowym możesz używać fikcyjnych, ale poprawnych (pod kątem sumy kontrolnej) numerów NIP. Ważne: NIP musi być matematycznie poprawny — KSeF weryfikuje sumę kontrolną.

Co testować?

Lista przypadków testowych:

•Wysyłka poprawnej faktury → oczekiwany rezultat: przyjęcie

•Wysyłka faktury z błędem XML → oczekiwany rezultat: odrzucenie z kodem błędu

•Wygasła sesja → obsługa błędu 401

•Brak uprawnień → obsługa błędu 403

•Zapytanie o faktury zakupowe → pobieranie listy

•Duplikat faktury → obsługa odrzucenia

Automatyczne testy integracyjne

Możesz skonfigurować automatyczne testy integracyjne (CI/CD) korzystające z sandboxu KSeF. Środowisko testowe jest dostępne przez API tak samo jak produkcyjne.

Uwaga: sandbox może być niestabilny

Ministerstwo Finansów aktualizuje środowisko testowe częściej niż produkcyjne. Czasem może być niedostępne lub zachowywać się inaczej niż produkcja.

Potrzebujesz pomocy z testowaniem?

Nasze [proxy KSeF](/proxy-ksef) ma wbudowany tryb testowy. [Skontaktuj się z nas](/kontakt) lub sprawdź [dokumentację techniczną](/docs).

Sandbox KSeF — jak testować integrację na środowisku testowym