Dotyczy wersji: 2025.1.1 i powyżej, autor: Michał Bednarczyk, Lily Adamowicz
Dokumentacja powiązana
Szczegółowy opis funkcjonalności wymienionych w niniejszym artykule oraz ich konfiguracji można znaleźć w następujących sekcjach Pomocy WEBCON:
Wprowadzenie
e-Doręczenia to cyfrowy odpowiednik listu poleconego z potwierdzeniem odbioru. Usługa ta umożliwia instytucjom publicznym, obywatelom i firmom korzystanie z wygodnych i bezpiecznych doręczeń elektronicznych, które mają taką samą moc prawną, jak tradycyjne przesyłki polecone z potwierdzeniem odbioru. W procesie biorą udział trzy strony: nadawca, odbiorca i Operator Wyznaczony, tj. podmiot, który odpowiada za realizację usług pocztowych, w tym e-Doręczeń. Proces wysyłania wiadomości w systemie e-Doręczeń polega na tym, że nadawca loguje się do systemu, przygotowuje wiadomość, uzupełnia wszystkie wymagane pola i wysyła ją. Operator Wyznaczony generuje dowód wysłania i przekazuje go nadawcy, a odbiorca otrzymuje powiadomienie o nowej wiadomości. Po odczytaniu wiadomości przez odbiorcę Operator Wyznaczony dostarcza nadawcy dowód odbioru.
Poniższy artykuł jest drugim w cyklu prezentacji integracji między platformą WEBCON a systemem e-Doręczeń (w pierwszym artykule opisano korespondencję przychodzącą). Dzięki procesom opisanym we wspomnianych artykułach możliwe jest zarządzanie całą korespondencją w ramach jednej platformy. W tym celu należy przygotować kilka dodatków SDK, rozszerzyć konfigurację o wymagane atrybuty oraz spełnić kilka warunków:
- posiadanie platformy WEBCON w wersji min. 2025,
- złożenie wniosku przez Klienta o ADE (Adres do e-Doręczeń),
- rejestracja systemu w skrzynce e-Doręczeń przy użyciu certyfikatu pozwalającego na integrację systemu.
Certyfikat musi być kwalifikowany, a jego wydawca znajdować się na liście NC Cert. Dodatkowo musi przejść walidację za pomocą narzędzia udostępnionego przez Komisję Europejską. Szczegóły uzyskania certyfikatu kwalifikowanego można znaleźć na stronie biznes.gov.pl.
UWAGA: Dostęp do środowiska produkcyjnego e-Doręczeń wymaga zakupu certyfikatu kwalifikowanego. Do korzystania ze środowiska testowego można użyć bezpłatnie wygenerowanego certyfikatu, jednak konieczne jest wcześniejsze złożenie wniosku i uzyskanie autoryzacji. - Do przechowywania klucza zalecane jest użycie usługi Azure Key Vault.
Na potrzeby drugiego artykułu przygotowano prosty proces obsługi korespondencji wychodzącej. Celem tego procesu jest właściwe skatalogowanie wszystkich przesyłek opuszczających firmę. W podstawowym obiegu każda przesyłka jest rejestrowana w systemie z uwzględnieniem informacji o środku komunikacji, za pośrednictwem którego została wysłana.
W ramach integracji z systemem e-Doręczeń aplikację rozbudowano, dzięki czemu umożliwia teraz wysyłanie wiadomości do odbiorcy za pośrednictwem skrzynki e-Doręczeń, a także oferuje funkcje wyszukiwania adresów e-Doręczeń (ADE) odbiorcy oraz monitorowania statusu wiadomości. Z użyciem tych funkcji użytkownicy są w stanie efektywnie zarządzać procesem doręczeń. Co więcej, zapewnione jest dokładne śledzenie przesyłki i potwierdzanie jej odbioru.
Poniżej przedstawiono obieg zawierający krok Weryfikacja e-doręczenia służący do weryfikacji statusu wysłanych wiadomości oraz krok Niedostarczone, który jest wykorzystywany do zarządzania niewysłaną korespondencją.
Rys. 1. Obieg „Korespondencja wychodząca”
Konfiguracja
Modyfikację procesu należy zacząć od utworzenia atrybutów, które będą stosowane w rozszerzeniu e-Doręczenia. Do słownika Sposób wysyłki należy dodać nową pozycję E-Doręczenie, a następnie utworzyć pola do wpisania tematu i treści wiadomości.
Rys. 2. Widok fragmentu formularza startowego z podstawowymi danymi
Dodano sekcję do wyszukiwania adresu e-Doręczeń. Wyszukiwanie będzie odbywać się na podstawie typu podmiotu kontrahenta (np. podmiot publiczny, firma, organizacja) oraz jego identyfikatora (np. NIP, KRS, REGON). Do pola Kontrahent z e-doręczeń przypisane zostanie źródło danych z wyszukiwarką odbiorców. Szczegóły konfiguracji zostaną opisane w dalszej części artykułu.
Rys. 3. Widok fragmentu formularza startowego z danymi wysyłki
Podobnie jak przy konfiguracji procesu Korespondencja przychodząca należy uwzględnić atrybuty techniczne. Będą one stosowane w systemie e-Doręczeń do jednoznacznej identyfikacji i śledzenia wiadomości oraz ich powiązań. Dodatkowo atrybuty te będą służyć do sygnalizowania problemów oraz wspierania użytkowników w nawigowaniu i zarządzaniu wiadomościami w interfejsie aplikacji. Należy dodać pola ułatwiające identyfikację wiadomości, zgodnie z tym, co pokazano na poniższym zrzucie ekranu.
Rys. 4. Atrybuty techniczne z podstawowymi danymi
Następnie należy dodać dwie Listy pozycji. Pierwsza wyświetla informacje o ewentualnych błędach, które wystąpiły podczas wysyłania wiadomości. Druga służy do przechowywania informacji o dowodach związanych z wiadomością, takich jak potwierdzenia doręczenia, odczytu i wysłania.
Rys. 5. Atrybuty techniczne lista błędów oraz dowody
Poniżej znajduje się pełny widok formularza z zaznaczonymi wcześniej wspomnianymi atrybutami.
Rys. 6. Formularz wejściowy
Kolejnym krokiem jest zdefiniowanie dwóch źródeł danych. Konfiguracja jednego z nich została opisana w pierwszym artykule i dotyczy źródła odpowiedzialnego za integrację aplikacji z systemem e-Doręczeń (nazwa: „[eDORĘCZENIA] Agent public”).
Drugie źródło zapewnia połączenie z Bazą Adresów Elektronicznych (BAE) i odpowiada za wyszukiwanie adresu odbiorcy (nazwa: „[eDORECZENIA] BAE search public”). W źródłach danych należy dodać nowe połączenie typu REST Web Service, np. o nazwie „[eDORECZENIA] BAE search public”. W polach URL serwisu autoryzującego oraz URL bazowej instancji serwisu należy wpisać ten sam adres: https://int-ow.edoreczenia.gov.pl (środowisko testowe) lub https://ow.edoreczenia.gov.pl (środowisko produkcyjne).
Rys. 7. Tworzenie połączenia z „BAE search public”
Następnie należy utworzyć niestandardowe źródło danych dla aplikacji „Korespondencja wychodząca” o nazwie „[e-DORECZENIA] BAE KW”. Z listy rozwijanej po lewej stronie należy wybrać niestandardowe źródła danych i dodać źródło o nazwie „[e-DORECZENIA] BAE KW”.
Rys. 8. Tworzenie źródła danych „BaeSearch”
Po kliknięciu w przycisk Konfiguruj dodatek należy uzupełnić następujące sekcje:
1. Konfiguracja połączenia – przygotowano dodatek z możliwością obsługi wielu spółek. W pierwszym polu należy wpisać Identyfikator spółki, na podstawie którego zostanie dopasowany adres skrzynki e-Doręczeń. W kolejnym atrybucie Bazowe połączenie do serwisu należy wybrać wcześniej utworzone połączenie typu REST Web Service „[e-DORECZENIA] BAE search public”. W polu Źródło skrzynek należy wybrać tabelę z bazy MSSQL „[e-DORĘCZENIA] ADE Spółek”. Opis jej konfiguracji, podobnie jak kolejnych pól, zawarto w pierwszym artykule dotyczącym procesu korespondencji przychodzącej.
2. Konfiguracja obsługi błędów – należy wpisać treść komunikatu błędu oraz nazwę kolumny zwracanej przez źródło, w której ma zostać wyświetlony komunikat.
Rys. 9. Konfiguracja źródła danych BAE
3. Konfiguracja wyszukiwania – należy określić kryteria, według których będzie wyszukiwany odbiorca. Pole Kategorie wyszukiwania jest obowiązkowe. Poszczególne kategorie można wpisywać, oddzielając je przecinkami lub można stworzyć proces słownikowy z listą kategorii. W opisywanym przypadku wykorzystano atrybut Kategorie wyszukiwania w formie Pola wyboru, który jest powiązany ze wspomnianym słownikiem kategorii opisanym w dalszej części artykułu.
Rys. 10. Konfiguracja źródła danych BAE cd.
Następnym krokiem w konfiguracji jest zdefiniowanie dwóch słowników, które będą używane do wyszukiwania odbiorcy. Najpierw należy dodać słownik z podzestawami danych, do których przypisywane będą podstawowe informacje o odbiorcy.
Rys. 11. Przykładowa lista podzestawów danych
Drugi słownik będzie zawierać kategorie wyszukiwania, co pozwoli na zawężenie zakresu przeszukiwania w systemie e-Doręczeń, umożliwiając precyzyjne odnalezienie potrzebnych informacji na podstawie charakterystyki odbiorcy.
Rys. 12. Przykładowa lista kategorii
Każda kategoria będzie mieć przypisane odpowiednie podzestawy danych, jak pokazano na poniższym zrzucie ekranu. Jedna kategoria może zawierać wiele podzestawów danych.
Niezbędna jest wartość techniczna, która zostanie użyta w konfiguracji dodatku. Na poniższym przykładzie jest to pole „Nazwa EN”.
Rys. 13. Przykład przypisania podzestawów danych do kategorii
Na potrzeby konfiguracji rozszerzenia przygotowano paczkę dodatków SDK (istnieje możliwość ich zamówienia):
- CreateDraft – tworzy wiadomość roboczą w e-Doręczeniach.
- AddAttachment – wysyła duży załącznik i dodaje go do drafta.
- UpdateDraft – aktualizuje draft po dodaniu załącznika.
- SendDraft – wysyła draft za pomocą skrzynki e-Doręczeń.
- CheckTask – sprawdza status zadania wysyłki na podstawie taskID.
- GetEvidences – pobiera dowód wysłania wiadomości.
- CheckStatus – sprawdza status wysłania wiadomości na podstawie messageID.
- DeleteMessage – usuwa wiadomości ze skrzynki e-Doręczeń.
Pierwszym etapem konfiguracji jest utworzenie akcji CreateDraft, która posłuży do przygotowania draftu wiadomości. Akcję należy utworzyć na nowej ścieżce, jak pokazano na poniższym zrzucie.
Rys. 14. Automatyzacja CreateDraft
Do automatyzacji dodano dwie akcje walidacji formularza. Akcja “Sprawdź nazwę załączników” sprawdza czy w nazwie nie znajdują się spacje i znaki :~"#%&*<>?!/{|} Akcja “Sprawdź długość nazwy załącznika” kontroluje długość nazwy, która nie może przekraczać 128 znaków.
Poniżej pokazano konfigurację dodatku CreateDraft.
1. Konfiguracja załączników – umożliwia przypisywanie plików do wiadomości. Pole ID kategorii pozwala na organizowanie załączników w odpowiednie kategorie, co ułatwia zarządzanie nimi i późniejsze ich wyszukiwanie.
Podczas wykonywania akcji CreateDraft sprawdzane są również załączniki. Jeśli rozmiar załącznika przekracza 20 MB, zaznaczane jest pole Duże załączniki do wysłania, a metadane tych załączników są zapisywane w polu Metadane załączników. W kolejnym kroku system przechodzi do obsługi dużych załączników. Jeśli natomiast załączniki są mniejsze, zostają dodane bezpośrednio do wiadomości.
2. Konfiguracja wiadomości – umożliwia ustawienie kluczowych parametrów wysyłanej korespondencji, takich jak adres odbiorcy, temat, treść wiadomości oraz identyfikatory potrzebne do śledzenia i powiązania wiadomości z wątkiem konwersacyjnym. Pozwala na precyzyjne przygotowanie wiadomości do wysyłki przez system e-Doręczeń.
3. Konfiguracja wysyłki – odpowiada za przypisanie adresu do danej spółki nadawcy. Na podstawia pola Identyfikator spółki dopasowany zostanie adres skrzynki z pola Źródło adresów. Pole ID z kolejki wysyłania umożliwia śledzenie statusu wiadomości.
Rys. 15. Konfiguracja akcji CreateDraft
Po utworzeniu drafta element trafia do kroku sterowania obiegiem, w którym znajduje się następujący warunek:
Rys.16. Warunek sterowania obiegiem
Jeżeli podczas tworzenia lub aktualizacji drafta wystąpi błąd, element wraca do kroku edycji drafta, a informacje o błędach są zapisywane na formularzu. Dzięki temu użytkownik może je zweryfikować i poprawić dane wiadomości.
Sterowanie obiegiem sprawdza również, czy pole Duże załączniki do wysłania ma wartość true. Jeśli tak, element przechodzi do kroku technicznego odpowiedzialnego za wysyłkę dużych załączników. Wartość pola false oznacza, że element nie ma przypiętych dużych załączników, dlatego od razu uruchamiana jest akcja wysyłki SendDraft.
W przypadku, gdy do elementu dołączono duże załączniki, element trafia do kroku odpowiedzialnego za ich wysyłkę. W tym kroku akcja AddAttachment jest uruchamiana przez timer. Odpowiada ona za wysłanie dużego załącznika i dodanie go do drafta. Do działania wykorzystuje dane z konfiguracji dotyczącej metadanych załączników oraz wartość pola wskazującego, że pozostały jeszcze duże załączniki do wysłania.
Po każdym poprawnym przesłaniu załącznika element przechodzi ścieżką, na której uruchamiana jest akcja UpdateDraft, odpowiedzialna za aktualizację drafta po dodaniu załącznika. Akcje AddAttachment i UpdateDraft są więc wykonywane zawsze jedna po drugiej i służą obsłudze dużych plików załączników.
Po aktualizacji element wraca do kroku sterującego obiegiem. Warunek dotyczący dużych załączników jest sprawdzany ponownie, a następnie, jeśli nadal istnieją załączniki do obsłużenia, proces przechodzi przez kolejną iterację. Pętla powtarza się do momentu, aż wszystkie załączniki zostaną obsłużone, a pole Duże załączniki do wysłania zostanie odznaczone. Dopiero wtedy element przechodzi do kroku wysyłki drafta.
Na ścieżce przejścia wychodzącej z kroku sterowania obiegiem umieszczono akcję wysyłki drafta SendDraft. Wiadomości robocze bez załączników lub z małymi załącznikami są wysyłane od razu. Natomiast wiadomości z dużymi załącznikami są wysyłane dopiero po przesłaniu wszystkich załączników i odznaczeniu pola Duże załączniki do wysłania.
Rys. 17. Akcja SendDraft
W konfiguracji akcji wysyłania należy uzupełnić:
1. Konfiguracja połączenia – identyfikator spółki, bazowe połączenie do serwisu oraz źródło spółek.
Rys. 18. Konfiguracja połączenia w dodatku SendDraft
2. Konfiguracja załączników – w tej sekcji przechowywane są metadane załączników oraz informacja o dużych załącznikach dołączonych do wiadomości roboczej. Aby wiadomość mogła zostać wysłana, pole Duże załączniki do wysłania musi być odznaczone.
3. Konfiguracja odpowiedzi – pozwala monitorować status wysyłanych wiadomości oraz identyfikować ewentualne problemy. Zawiera kluczowe pola, takie jak Pole z identyfikatorem zadania wysyłki, Pole z identyfikatorem wiadomości, Ostrzeżenie oraz Lista z błędami, które umożliwiają śledzenie procesu doręczeń i zarządzanie nim.
Rys. 19. Konfiguracja załączników i odpowiedzi w dodatku SendDraft
Dodatkową akcją uruchamianą przez timer jest CheckTask, które sprawdza status zadania. Akcja działa na podstawie wartości taskID w okresie od wysłania wiadomości roboczej do potwierdzenia, że wiadomość została poprawnie wysłana.
Zalecanym ustawieniem jest uruchomienie tej akcji po 5 minutach od momentu wysłania wiadomości.
Rys. 20. Konfiguracja odpowiedzi akcji CheckTask
Wymagane jest także skonfigurowanie drugiej akcji weryfikującej status wysłania. Należy dodać krok sterowania obiegiem, który w zależności od statusu wiadomości, wybierze odpowiednią ścieżkę.
Rys. 21. Sterowanie obiegiem w zależności od wartości statusu wiadomości
Następnie należy dodać akcję dodatku SDK CheckStatus na ścieżce przejścia prowadzącej do kroku „Weryfikacja e-doręczenia”. Sekcję Konfiguracja połączenia należy uzupełnić analogicznie do poprzednich akcji. W rubryce Konfiguracja odpowiedzi należy wskazać atrybut, który wyświetli Status wiadomości z systemu e-Doręczeń oraz wyznaczyć Listę pozycji do zapisywania informacji o błędach. W Konfiguracji dodatku niezbędne jest wskazanie Identyfikatora wiadomości, dla której sprawdzany jest status, czyli ID nadanego przez system e-Doręczeń, a otrzymanego w akcji wysyłki wiadomości.
Rys. 22. Konfiguracja odpowiedzi i dodatku w akcji CheckStatus
W końcowym kroku procesu, w którym przechowywane są wysłane wiadomości, należy dodać przycisk do pobierania dowodu wysłania wiadomości oraz przycisk do usuwania wiadomości ze skrzynki e-Doręczeń. Do wykonania pierwszej akcji należy użyć dodatku SDK GetEvidences, a do drugiej dodatku SDK DeleteMessage. Sekcje Konfiguracja połączenia i Konfiguracja dodatku w obu przypadkach należy uzupełnić analogicznie do wcześniejszych ustawień akcji dodatków.
Rys. 23. Przyciski pobrania dowodu i usunięcia wiadomości w menu formularza
Dodatkowo w konfiguracji akcji pobierania dowodów w sekcji Konfiguracja pliku należy określić kategorię, do której mają zostać przypisane pobrane dowody. Należy również zaznaczyć, czy pobrane pliki mają zostać rozpakowane.
Rys. 24. Konfiguracja pliku w konfiguracji akcji dla dodatku GetEvidences
Zaznaczenie pola wyboru przy opcji Pobieraj listę dowodów w sekcji Lista dowodów dodatkowo daje możliwość pobrania oddzielnej listy.
Rys. 25. Konfiguracja pliku w konfiguracji akcji dla dodatku GetEvidences
Aplikacja
Poniżej opisano, w jaki sposób korzystać z aplikacji. W formularzu z listy rozwijanej należy wybrać e-Doręczenie jako sposób wysyłki. Wyświetlone zostaną pola umożliwiające uzupełnienie tematu i treści wiadomości. Następnie należy wyszukać kontrahenta, do którego zamierza się wysłać wiadomość. Po prawej stronie w zakładce Dane e-doręczeń należy wyszukać adres skrzynki odbiorcy, wybierając odpowiednie kryterium.
Rys. 26. Formularz wejściowy z wybraną formą wysyłki e-Doręczenia
Jeżeli niestandardowe źródło danych „[e-DORECZENIA] BAE KW” zostało poprawnie skonfigurowane, po rozwinięciu pola „Kontrahent z e-doręczeń” powinny załadować się dane odbiorcy.
Rys. 27. Wczytane dane odbiorcy w polu „Kontrahent z e-doręczeń”
Po kliknięciu we wczytane dane, pole „Adres e-doręczeń” zostanie uzupełnione.
Rys. 28. Wczytany „Adres e-doręczeń”
Po wyszukaniu ADE odbiorcy możliwe jest wysłanie wiadomości za pomocą systemu e-Doręczeń.
Rys. 29. Przycisk „Wyślij e-doręczenie"
Wiadomość robocza oczekuje na potwierdzenie wysłania, a następnie na uruchomienie akcji wysyłki i weryfikacji. Następnie wiadomość zostaje przekazana do Archiwum. Możliwe jest pobranie wszystkich dowodów dotyczących tej wiadomości oraz usunięcie wiadomości ze skrzynki e-Doręczeń.
Rys. 30. Odebrana wiadomość w Archiwum
Integracja systemu e-Doręczeń z korespondencją wychodzącą znacząco usprawnia proces zarządzania komunikacją elektroniczną. Automatyzacja wysyłki, możliwość śledzenia statusu doręczeń oraz archiwizacja wiadomości pozwalają na pełną kontrolę nad obiegiem dokumentów i poprawę efektywności pracy. Dzięki zastosowaniu certyfikowanych skrzynek e-Doręczeń oraz odpowiednim konfiguracjom systemu proces ten staje się bezpieczny, zgodny z wymogami prawnymi i bardziej przejrzysty. Zastosowanie tej integracji wspiera organizacje w spełnianiu obowiązków związanych z wymianą dokumentów z instytucjami publicznymi oraz kontrahentami.