Trzecia część cyklu o możliwościach integracyjnych ePUAP. Podsumowanie usług web-service i komunikacji przez skrytki.
Skrytki i składy
Skrytki są podstawową metodą komunikacji w sprawach urzędowych na platformie. Każdy nowy użytkownik systemu otrzymuje konto zaopatrzone we własną skrytkę.
W uproszczeniu, skrytki można porównać do kont e-mail, a skład do folderów klienta pocztowego. Takie uproszczone traktowanie skrytek może być wystarczające dla obywatela komunikującego się z urzędami.
Każda skrytka powiązana jest ze składem, do którego trafiają dokumenty nadesłane na skrytkę.
Użytkownik otrzymujący dokumenty na skrytkę odbiera je w podsystemie front-end ePUAP (w zakładce Moje dokumenty) lub w zewnętrznym systemie obiegu dokumentów.
Patrząc od strony integratora/wdrożeniowca, skrytka to podstawowy punkt komunikacyjny pomiędzy usługami, oferujący szereg funkcji wspierających walidację i przepływ dokumentów:
- autoryzacja nadawcy i odbiorcy
- akceptowany format dokumentów odbieranych przez skrytkę: tylko w formacie XML lub dowolnych binariów (plików); warto pamiętać, że format XML również pozwala na przesyłanie binariów – można to osiągnąć wykorzystując standardowe kodowanie załączników do Base64
- przyjmowanie tylko dokumentów zgodnych z przypisanymi do skrytki regułami XML (pozwala na weryfikację ze względu na treść dokumentu)
- przyjmowanie tylko dokumentów zgodnych z przypisanym do skrytki schematem XSD (pozwala na weryfikację ze względu na strukturę dokumentu )
- przyjmowanie tylko dokumentów podpisanych (certyfikatem lub Profilem Zaufanym) wraz z archiwizacją podpisu; kwalifikowany podpis elektroniczny na dokumentach składany jest w formacie XadES
- konfiguracja skrytki możliwa do eksportu (jako plik XML)
- rodzaj automatycznej odpowiedzi nadawcy (Urzędowe Poświadczenie Przedłożenia, status lub przygotowany wcześniej dokument)
- definiowalny adres skrytki (nie mylić z identyfikatorem w systemie bezpieczeństwa)
- przekierowanie odebranych dokumentów i Urzędowych Potwierdzeń (do składu Moje Dokumenty, Koordynatora (aplikacja złożona) lub bezpośrednio do systemu zewnętrznego)
- tryb pracy: PULL/PUSH
- typ: synchroniczna/asynchroniczna
Dokument opisujący konfigurację skrytki po stronie front-end to pdf: Instrukcja Użytkownika Podsystem Komunikacyjny
Skrytka a skrzynka podawcza
Dygresja na temat nazewnictwa. Podczas pierwszych rozmów nt. aplikacji ePUAP łatwo pomylić dwa pojęcia: skrytka i skrzynka podawcza.
Elektroniczna Skrzynka Podawcza to aplikacja ePUAP, przeznaczona dla urzędów zobowiązanych ustawowo do przyjmowania dokumentów w postaci elektronicznej. Fizycznie zapisywana jako XML do zainstalowania w Środowisku Budowy Aplikacji. Zawiera w sobie definicje składu, skrytki, wzór odpowiedzi, formularz, dane urzędu itd.. Skrytka stanowi element komunikacyjny w aplikacji.
Więcej informacji o skrzynce podawczej opisuje dokument:
Podręcznik instalacji aplikacji „Elektroniczna Skrzynka Podawcza” i zamieszczenia usługi w Katalogu Usług.
Nawiązywanie połączenia z usługami web service ePUAP
Komunikacja ze skrytką odbywa się przez oferowane w środowisku usługi web service. W zależności od trybu pracy skrytki i ew. wymóg potwierdzenia, należy wybrać odpowiednią usługę do nadawania i odbierania.
Autoryzacja i bezpieczeństwo komunikacji wykorzystuje standard WS-Security i opiera się na infrastrukturze klucza publicznego.
Aby uzyskać połączenie zewnętrznego systemu obiegu z ePUAP, potrzebna jest para kluczy: publiczny i prywatny. Klucz publiczny należy zarejestrować w podsystemie bezpieczeństwa (https://konsolahetman.epuap.gov.pl/DracoConsole) podmiotu (urzędu). Klucz prywatny należy wykorzystać do podpisywania koperty SOAP, w praktyce dla Javy użyć certyfikatu w Java Key Store do połączeń za pomocą Axis.
Dla połączeń testowych administratorzy ePUAP udostępniają certyfikaty w Microsoft'owym formacie pfx. Aby dokonać konwersji z pfx do jks, należy użyć biblioteki jetty.jar w poleceniu konsoli:
java -classpath <ścieżka do biblioteki>\jetty-6.1.1.jar org.mortbay.jetty.security.PKCS12Import źródłowy.pfx docelowy.jks
Usługi - web service
Pełna lista interfejsów, pliki wsdl i adresy usług dostępne są na stronie „Specyfikacja interfejsów WSDL”
Na dzień, w którym pisany jest ten tekst są to następujące usługi:
- Skrytka – wysyłanie dokumentów na skrytkę ePUAP
- Doreczyciel - doręczanie dokumentów w trybie UPD (zwrotne potwierdzenie odbioru)
- Pull - odbieranie dokumentów w trybie PULL.
- Odbiorca – odbieranie dokumentów w trybie PUSH
- Płatności – pobranie EPO (Elektronicznego Potwierdzenia Opłaty), weryfikacja EPO
- Słowniki referencyjne – dostęp do danych w słownikach referencyjnych (np. słowniki Teryt)
- Subskrypcje – subskrybowanie powiadomień o określonych zdarzeniach w ePUAP
- Zarządzanie dokumentami – operacje na składzie dokumentów (listowanie zawartości, dodanie, pobranie i usuwanie)
- Zarządzanie podmiotami – dostęp do danych profilu podmiotu
- Katalog usług publicznych – utworzenie, pobranie, aktualizacja i prezentacja karty usługi, opisy usług
- Profil zaufany – podpisywanie dokumentów podpisem potwierdzonym Profilem Zaufanym, weryfikacja dokumentów podpisanych, weryfikacja posiadania PZ przez użytkownika
- Pesel – weryfikacja danych obywatela w rejestrze PESEL (poprawne - niepoprawne)
Punkty integracji
Podsumowując, możliwości integracyjne systemu zewnętrznego z ePUAP to przede wszystkim komunikacja web service z poszczególnymi podsystemami, w tym bardziej złożony przypadek płatności.
Dostawcy zewnętrznych systemów mają możliwość odtworzenia funkcji dostępnych we front-end ePUAP w swoich produktach, wyposażając ją w dostarczaną wartość dodaną (obieg dokumentów, usability). Możliwa jest również integracja na poziomie kont użytkowników na mocy standardu Single Sign-On (SSO) i wykorzystanie uprawnień zdefiniowanych w podsystemie bezpieczeństwa ePUAP do uwierzytelniania i autoryzacji użytkowników w systemie zewnętrznym.
Środowisko testowe
Do testowania wyników integracji platforma oferuje bliźniaczą do epuap.gov.pl testową wersję portalu pod: test.epuap.gov.pl
Konta i uprawnienia utworzone na testowym ePUAP należy używać do połączeń nawiązywanych za pomocą testowych wersji web service , używając do połączeń testowych certyfikatów (pary kluczy publiczny-prywatny) - produkcyjne usługi web service posiadają swoje odpowiedniki dla środowiska testowego.
Przydatne linki: