Konfiguracja modułu e-Doręczenia

Skrzynkę e-Doręczeń można obsługiwać nie tylko za pomocą interfejsu webowego, ale również za pomocą systemów zewnętrznych, takich jak np. Podatki. Aby udzielić dostępu do skrzynki dla systemu zewnętrznego, konieczne jest wygenerowanie pliku CSR (Certificate Signing Request), który zostanie wykorzystany w procesie rejestracji. Po zweryfikowaniu pliku CSR, system e-Doręczeń wygeneruje certyfikat X.509, który należy pobrać i zapisać wraz z kluczem prywatnym i publicznym.

Generowanie kluczy

Do wygenerowania kluczy najlepiej użyć narzędzia OpenSSL. Link do pobrania: https://slproweb.com/products/Win32OpenSSL.html

Generowanie klucza prywatnego

Aby utworzyć klucz prywatny, który będzie używany z certyfikatem, przy wykorzystaniu pakietu OpenSSL, należy wpisać poniższe polecenie w oknie terminala (podając **własną ścieżkę do katalogu, w którym mają być zapisane klucze**):

openssl genrsa -out "C:\Twoja_Sciezka\klucze\infosys_edor.key" 2048

Uwaga!

Wygenerowany klucz prywatny należy zachować w bezpiecznym miejscu i uniemożliwić dostęp do niego osobom trzecim. Należy również wykonać kopię bezpieczeństwa tego pliku — jest on niezbędny do późniejszego używania certyfikatu. Powtórne wygenerowanie identycznego klucza prywatnego nie jest możliwe, a jego utrata uniemożliwia korzystanie z certyfikatu.

Generowanie pliku żądania podpisania certyfikatu (CSR)

Aby utworzyć plik żądania podpisania certyfikatu (CSR) na podstawie wcześniej wygenerowanego klucza prywatnego, użyj polecenia (również wskazując **własną ścieżkę**):

openssl req -new -key "C:\Twoja_Sciezka\klucze\infosys_edor.key" -out "C:\Twoja_Sciezka\klucze\infosys_edor.csr"

W trakcie tworzenia pliku CSR, należy podać następujące informacje:

Country Name (C) – dwuliterowy kod kraju, np. [PL].
State or Province Name (ST) – nazwa województwa, w którym mieści się siedziba firmy, np. [Wojewodztwo].
Locality Name (L) – nazwa miejscowości, np. [Miejscowosc].
Organization Name (O) – pełna i dokładna nazwa firmy, zgodna z danymi rejestrowymi (CEIDG lub KRS), np. [Nazwa Firmy].
Organizational Unit Name (OU) – opcjonalnie nazwa działu, np. [Dzial IT].
Common Name (CN) – nazwa domeny, dla której ma być wystawiony certyfikat, np. [*.domena.pl].
Email Address [E] – pole nieobowiązkowe.

Po wypełnieniu tych danych pojawią się dwa dodatkowe pytania (extra attributes). Należy pozostawić pola puste i zatwierdzić klawiszem Enter:

A challenge password – pominąć (Enter).
An optional company name – pominąć (Enter).

Uwaga! Podczas udzielania odpowiedzi NIE NALEŻY używać polskich znaków diakrytycznych.

Poprawność pliku CSR zostanie sprawdzona podczas rejestracji integrowanego systemu.

Dodawanie integrowanego systemu do skrzynki e-Doręczeń

Rejestrację integrowanego systemu rozpocznij od zalogowania się do systemu e-Doręczeń w roli w właściciela skrzynki. Przejdź do strony z widokiem zakładki Systemy znajdującej się w sekcji Uprawnienia.

Następnie naciśnij przycisk Dodaj system w prawym górnym rogu ekranu. Przejedziesz do strony Dodaj system.

Dodawanie systemu

Uwaga! Przeprowadzanie procesu rejestracji systemu zewnętrznego może dokonać tylko użytkownik pełniący role właściciela skrzynki.

Dodawanie systemu

Wprowadź wymagane informacje:

Nazwę systemu, która umożliwi łatwe zidentyfikowanie go na liście - unikaj spacji;
Wgraj żądanie certyfikatu (CSR), jako środek uwierzytelniający;
Dodatkowo w polu Opis systemu możesz wprowadzić krótki opis systemu, maksymalnie 256 znaków.

Zapisz wprowadzone informacje klikając na przycisk Zapisz.

Plik CSR jest weryfikowany – dostaniesz informację o tym, czy proces weryfikacji przebiegł prawidłowo. Jeśli tak, system tworzy certyfikat X.509. Kliknij Pobierz certyfikat, aby go pobrać.

Konfiguracja

Wymagane biblioteki

Na komputerze, na którym wprowadzamy konfiguracje, wymagane są następiujące komponenty umożliwiających uruchamianie w systemie Windows aplikacji stworzonych przy pomocy narzędzi programistycznych firmy Microsoft:

.NET Framework w wersji 4.8 lub wyższej,
Microsoft Visual C++ 2015-2022 Redistributable (wersja x86).
Microsoft Visual C++ 2015-2022 Redistributable (wersja x64).

Brak w/w bibliotek uniemożliwi zapisane parametrów modułu e-Doręczenia.

Synchronizacja czasu

W celu zapewnienia poprawnej pracy modułu e-Doręczenia, komputer powinien mieć włączoną automatyczną synchronizację czasu z serwerem NTP.

Parametry modułu e-Doręczenia

[Podatki] Menu: Konfiguracja -> Ustawienia -> Parametry modułu e-Doręczenia
[Egzekucje] Menu: Konfiguracja -> Konfiguracja modułu e-Doręczenia

Dla programów działających na wspólnej bazie danych konfigurację ustalamy tylko raz.

Środowisko produkcyjne

Parametry środowiska produkcyjnego usługi e-Doręczenia

Przygotowane w poprzednich krokach dane należy wprowadzić w zakładce Środowisko produkcyjne.

Przycisk Podaj domyślne uzupełni pola:
- Adres usług e-Doręczeń,
- Adres usług BAE,
- Adres serwera uwierzytelniającego,
Adres elektroniczny skrzynki - podajemy adres skrzynki e-Doręczeń,
Nazwa systemu - podajemy nazwę systemu ustawioną podczas dodawania systemu zewnętrznego do e-Doręczeń,
Klucz uwierzytelniający - wklejamy zawartość pliku z wygenerowanym wcześniej kluczem prywatnym .KEY (otwieramy notatnikiem).

Po uzupełnieniu danych zaznaczamy parametr Używaj środowiska produkcyjnego i zapisujemy wprowadzone parametry klikając na przycisk Zapisz.

Dane nadawcy i potwierdzenia odbioru

Parametry: dane nadawcy oraz typy zdarzeń uznawane za potwierdzenie odbioru

Testowanie konfiguracji i typowe problemy

Błąd przy przyspieszonym zegarze

Uwaga! Podczas testowania poprawności konfiguracji (np. przy próbie wyszukania adresu e-Doręczeń) może pojawić się błąd, jeśli czas na stacji roboczej jest przyspieszony względem czasu rzeczywistego. Zdarza się to szczególnie w środowiskach domenowych, gdzie stacje synchronizują się z kontrolerem domeny, a ten ma czas „śpieszący się”.

Objawy

Wyszukiwanie adresu e-Doręczeń kończy się błędem mimo poprawnych parametrów.

Dlaczego tak się dzieje

Mechanizmy uwierzytelniania usług powiązanych z e-Doręczeniami są wrażliwe na odchylenia czasu — gdy zegar jest do przodu, żądanie bywa traktowane jako „z przyszłości” i odrzucane.
Nawet niewielkie przyspieszenie (kilkadziesiąt sekund) może powodować problemy.

Jak sprawdzić i naprawić

Sprawdź aktualny czas systemowy oraz źródło synchronizacji.
Jeśli źródłem jest kontroler domeny z nieprawidłowym czasem, skoryguj czas na kontrolerze (PDC Emulator) lub tymczasowo przełącz synchronizację stacji na wiarygodne źródło NTP.
Wymuś natychmiastową resynchronizację czasu na stacji.
Upewnij się, że automatyczna synchronizacja czasu jest włączona i wskazuje poprawny serwer NTP (np. pula NTP lub inny zaufany czasomierz organizacyjny).
Ponów test wyszukiwania adresu e-Doręczeń.

Uwaga! Jeżeli stacje robocze są w domenie, zadbaj o prawidłowy czas na kontrolerze domeny (PDC Emulator). To on stanowi referencję czasu dla pozostałych komputerów w sieci.

Błąd: w polu „Klucz uwierzytelniający” wklejono plik .CSR lub .PEM zamiast .KEY

Uwaga! W polu Klucz uwierzytelniający należy wkleić zawartość pliku z kluczem prywatnym o rozszerzeniu .KEY.

Wklejenie zawartości pliku .CSR lub .PEM spowoduje błąd uwierzytelnienia podczas próby połączenia z usługą e-Doręczeń.

Objawy

Po zapisaniu konfiguracji operacje w e-Doręczeniach kończą się błędem autoryzacji lub brakiem odpowiedzi.
W logach pojawiają się komunikaty o błędnym kluczu, nieprawidłowym podpisie lub problemie z identyfikatorem systemu.

Dlaczego tak się dzieje

Plik .CSR zawiera jedynie żądanie certyfikatu (publiczne dane).
Plik .PEM może zawierać sam certyfikat X.509, ale bez klucza prywatnego nie umożliwia uwierzytelnienia.
Tylko plik .KEY zawiera właściwy klucz prywatny potrzebny do podpisywania i autoryzacji.

Jak rozpoznać typ pliku

.KEY – prawidłowy plik klucza prywatnego. Zaczyna się od `-----BEGIN PRIVATE KEY-----`
.CSR – błędny plik żądania certyfikatu. Zaczyna się od `-----BEGIN CERTIFICATE REQUEST-----`
.PEM – błędny plik certyfikatu. Zaczyna się od: `-----BEGIN CERTIFICATE-----`

Jak naprawić

Otwórz w Notatniku plik klucza prywatnego (np. `D:\klucze\infosys_edor.key`).
Skopiuj **całą** jego zawartość – łącznie z liniami nagłówka i stopki `BEGIN/END ...`.
Wklej tę treść do pola Klucz uwierzytelniający w zakładce Środowisko produkcyjne.
Zapisz ustawienia i ponów próbę.

Zawsze przechowuj pliki `.KEY`, `.CSR` i `.PEM` w jednej lokalizacji, z czytelnymi nazwami – ułatwi to późniejszą identyfikację, który plik odpowiada któremu certyfikatowi.

Linki

Jak skutecznie wdrożyć e-Doręczenia? Przewodnik dla podmiotów publicznych

E-Doręczenia - informacje ogólne

Log [opcja serwisowa]

Krok nie jest wymagany do skonfigurowania integracji. Służy jedynie do włączenia logowania w celu diagnostyki i rozwiązywania problemów.

Aby włączyć pełne logowanie w systemie, należy dodać odpowiedni rekord do tabeli `EDO_PARAMS`.

Zaloguj się do bazy danych z odpowiednimi uprawnieniami.
Dodaj nowy rekord do tabeli `EDO_PARAMS` z poniższymi wartościami:
- ID_SYSTEMU – wyliczany na podstawie daty (szczegóły niżej),
- PARAM – stała wartość: uwagi

Log będzie zapisywany w lokalizacji: C:\infosys_pity

Sposób wyliczenia wartości ID_SYSTEMU

Wartość 'ID_SYSTEMU' generowana jest na podstawie daty w formacie 'RRMMDD'. Następnie z poszczególnych cyfr tej daty tworzona jest 6-cyfrowa liczba według określonego schematu:

Schemat konstrukcji ID_SYSTEMU

Z daty w formacie `RRMMDD` wybieramy:

pierwszą cyfrę roku (R1)
pierwszą cyfrę miesiąca (M1)
pierwszą cyfrę dnia (D1)
drugą cyfrę roku (R2)
drugą cyfrę miesiąca (M2)
drugą cyfrę dnia (D2)

ID_SYSTEMU = R1M1D1R2M2D2

Przykłady

Data: 23 kwietnia 2025 → 250423
- Rozbicie: 2 5 0 4 2 3
- ID_SYSTEMU: 202543

Data: 18 kwietnia 2025 → 250418
- Rozbicie: 2 5 0 4 1 8
- ID_SYSTEMU: 201548