Integracja systemu e-Doręczenia z platformą WEBCON na potrzeby obsługi procesu „Korespondencja przychodząca” – wersja 2025

WEBCON Redaktor Bez kategorii
Facebooktwitterpinterestlinkedinmail
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 e-Doręczeń. Gdy nadawca wysyła wiadomość za pośrednictwem systemu e-Doręczeń, odbiorca otrzymuje powiadomienie o nowej wiadomości od Operatora Wyznaczonego. Operator Wyznaczony jednocześnie dostarcza nadawcy dowód wysłania wiadomości. Po odczytaniu wiadomości przez odbiorcę Operator Wyznaczony przekazuje nadawcy dowód jej odebrania.

W ramach powyższego tematu przygotowano dwa artykuły prezentujące możliwy sposób integracji pomiędzy platformą WEBCON a systemem e-Doręczeń. Pierwszy artykuł opisuje konfigurację procesu „Korespondencja przychodząca”, natomiast drugi – konfigurację procesu „Korespondencja Wychodząca”. Rozwiązanie to umożliwia zarządzanie całą korespondencją w ramach jednej platformy. Niezbędne jest także przygotowanie kilku dodatków SDK, rozbudowanie konfiguracji o wymagane atrybuty oraz spełnienie kilku wymagań:

  • 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 certyfikat 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 artykułu utworzono prosty proces obsługi korespondencji przychodzącej. Dotychczasowo korespondencja rejestrowana była manualnie w systemie WEBCON. Po odebraniu listu przez kancelarię konieczne było ręczne uzupełnienie formularza, zeskanowanie dokumentu i przyporządkowanie odbiorcy. Proces pozwalał potwierdzić odbiór korespondencji, po czym była ona przekazywana do Archiwum.

W ramach integracji z systemem e-Doręczeń aplikację rozbudowano. Dzięki temu teraz aplikacja regularnie sprawdza firmową „skrzynkę”, a następnie automatycznie pobiera nowe wiadomości.

 

Rys. 1. Obieg „Korespondencja przychodząca”

 

Konfiguracja

Modyfikację procesu należy rozpocząć od utworzenia atrybutów, które będą wykorzystywane w rozszerzeniu e-Doręczeń. Należy utworzyć pola, do których po pobraniu wiadomości przepisany zostanie jej temat i treść.

Rys. 2. Widok fragmentu formularza startowego z danymi podstawowymi

 

W sekcji Szczegóły odbioru do słownika z formami doręczenia należy dodać nową wartość e-Doręczenie oraz pola wskazujące daty nadania i otrzymania wiadomości.

Rys. 3. Widok fragmentu formularza startowego ze szczegółami odbioru

 

Następnie trzeba utworzyć nową grupę atrybutów zawierającą podstawowe informacje o nadawcy pobrane z systemu e-Doręczeń, takie jak nazwa firmy, adres czy adres skrzynki e-Doręczeń.

Rys. 4. Widok fragmentu formularza startowego z danymi wysyłki

 

Ponadto należy uwzględnić atrybuty techniczne. Zostaną one użyte w systemie e-Doręczeń do jednoznacznej identyfikacji i śledzenia wiadomości oraz ich powiązań, sygnalizowania problemów, a także wspierania użytkowników w nawigowaniu i zarządzaniu wiadomościami w interfejsie aplikacji. Należy dodać pola pomagające w identyfikacji wiadomości, jak pokazano na poniższym zrzucie ekranu. Należy zwrócić uwagę na atrybut „_IDwiadomościPicker”, który jest Polem wyboru mającym na celu uzyskanie ID wiadomości w formacie ID#ID. Jako źródło danych zastosowano stałe wartości z pustymi wpisami.

Rys. 5. Atrybuty techniczne zawierające podstawowe dane niezbędne do identyfikacji

 

Rys. 6. Przykładowe źródło danych dla atrybutu technicznego „IDwiadomościPicker”

 

Następnie należy dodać trzy Listy pozycji. Pierwsza wyświetla informacje o ewentualnych błędach, które wystąpiły podczas pobierania wiadomości, druga uwzględnia dane o wszystkich załącznikach dołączonych do wiadomości, a trzecia przechowuje informacje o dowodach związanych z wiadomością, takich jak potwierdzenia doręczenia, odczytu i wysłania.

Rys. 7.  Atrybuty techniczne „Lista błędów”, „Lista załączników” i „Lista dowodów”

 

Kolejnym atrybutem, który należy dodać jest „_IDspółki” z ustawioną wartością domyślną „Powiązana spółka”. Jest to atrybut techniczny, który przypisuje ID powiązanej spółki z pobranej wiadomości z e-Doręczeń.

Rys. 8.  Atrybut techniczny „_IDspółki”

 

Poniżej znajduje się pełny widok formularza uwzględniający wcześniej wspomniane atrybuty.

Rys. 9. Formularz wejściowy

 

Kolejnym krokiem w konfiguracji jest zdefiniowanie odpowiednich źródeł danych. Integracja z usługą e-Doręczeń możliwa jest nie tylko dla jednej spółki, ale także dla wielu, z wykorzystaniem dwóch głównych wariantów połączenia: opartego na Azure Key Vault lub na połączeniach REST.

 

Wariant I połączenie REST

Niezależnie dla ilu spółek tworzymy połączenie REST należy najpierw utworzyć w zakładce Źródła danych połączenie bazowe “[eDoręczenia] Agent baza”, które nie zawiera w sobie klucza Client Secret.

Rys. 10. Połączenie bazowe “REST [eDoreczenia] Agent baza”

 

Należy także utworzyć połączenie REST Web Service odpowiedzialne za integrację aplikacji z systemem e-Doręczeń o następujących parametrach:

  • nazwa: “[eDORĘCZENIA] Agent public”,
  • URL serwisu autoryzującego: https://int-ow.edoreczenia.gov.pl,
  • URL bazowej instancji serwisu: https://uaapi-int-ow.poczta-polska.pl,
  • Client Secret: w wersji BPS 2023 i wyższych można wkleić wielowierszowy klucz uzyskany w procesie rejestracji systemu. Zaleca się przechowywanie klucza w usłudze Azure Key Vault.

Rys. 11. Konfiguracja źródła danych skrzynki e-Doręczeń w wersjach BPS 2025 i 2026

 

Dla jednej spółki należy utworzyć jedno bazowe połączenie REST “[eDoręczenia] Agent baza” bez klucza Client Secret oraz drugie połączenie REST “[eDORĘCZENIA] Agent public” z kluczem (jak wyżej).

W przypadku wielu spółek należy utworzyć jedno bazowe połączenie REST “[eDoręczenia] Agent baza” oraz połączenia REST “[eDORĘCZENIA] Agent public” dla każdej spółki osobno. Tych połączeń będzie tyle, ile danych spółek biorących udział w integracji. ID tych połączeń należy zapisać, gdyż przydadzą się w dalszej konfiguracji.

Rys. 12. Przykładowe połączenie REST dla spółki z ID 4

 

Wariant II połączenie Azure Key Vault AKV

W tym wariancie analogicznie, jak przy połączeniu REST także należy utworzyć połączenie bazowe “[eDoręczenia] Agent baza” bez klucza Client Secret.

Należy także utworzyć źródło REST, z którego pobrany zostanie klucz prywatny. Nie ma konieczności zapamiętywania numeru ID, jednak w dalszej konfiguracji potrzebna będzie nazwa klucza użyta w Azure Key Vault. BPS korzystając z połączenia AKV i nazwy klucza pobierze klucz prywatny z AKV.

Należy uzupełnić URL serwisu autoryzującego, Client ID, Client Secret oraz URL bazowej instancji serwisu.

Rys. 13. Źródło “[eDORECZENIA] AzureKeyVault”

 

Drugie źródło danych stosowane do synchronizacji wiadomości utworzono w źródłach BPS. Należy nadać mu nazwę, a w konfiguracji wybrać proces „Korespondencja przychodząca” z wszystkimi dostępnymi krokami. Następnie należy dodać kolumny „ID”, „Sygnatura”, „_IDwiadomości” i „_IDspółki”.

Rys. 14. Dodawanie źródła danych BPS

 

Konieczne jest także zastosowanie źródła do mapowania ID spółki na adres skrzynki e-Doręczeń. Dla jednej spółki wystarczy utworzyć źródło z zastosowaniem stałych, zaś przy wielu spółkach najlepiej zastosować słownik, do którego wprowadzi się dane i utworzy źródło SQL (przykład poniżej).

W źródle nazwy wszystkich kolumn są istotne. W pierwszej kolumnie CompanyId źródło powinno zwracać ID spółki, a w drugiej kolumnie ADE – adres skrzynki e-Doręczeń. Trzecia kolumna System jest nazwą systemu nadaną przy wgrywaniu certyfikatu do skrzynki e-Doręczeń. Czwarta kolumna ConnectionId dotyczy połączeń REST danej spółki (powyżej pokazano przykład źródła z ID 4). Ostatnia kolumna Secret zawiera nazwę klucza nadaną w Azure Key Vault.

Ważne: Nie można mieszać wariantów połączenia poprzez REST i Azure Key Vault. Jeżeli utworzono wiele połączeń REST, to kolumna Secret musi pozostać pusta. Jeżeli zastosowano Azure Key Vault, to kolumna ConnectionId musi być pusta.

 

W poniższym przykładzie zastosowano typ źródła MSSQL, który odczytuje wartości ze słownika.

Rys. 15.  Źródło danych do mapowania ID spółki na adres skrzynki e-Doręczeń

 

W celu konfiguracji rozszerzenia przygotowano paczkę dodatków SDK (istnieje możliwość ich zamówienia):

  • SyncMessages – synchronizuje wiadomości ze skrzynką e-Doręczeń, pobiera dane, a następnie od razu startuje elementy.
  • GetMessage – pobiera wiadomość ze skrzynki e-Doręczeń.
  • GetAttachments – pobiera załączniki wiadomości ze skrzynki e-Doręczeń.
  • GetEvidences – pobiera wszystkie dowody dotyczące wiadomości ze skrzynki e-Doręczeń.
  • DeleteMessage – usuwa wiadomość ze skrzynki e-Doręczeń.

Pierwszym etapem konfiguracji akcji SDK jest przygotowanie dodatku do synchronizacji danych ze skrzynką e-Doręczeń i startowania elementów. W globalnej konfiguracji procesu dodano cykl, w ramach którego wstawiana będzie akcja dodatku SDK SyncMessages. W ustawieniach akcji cyklicznej należy określić nazwę, interwał czasowy, liczbę dopuszczalnych prób oraz datę pierwszego uruchomienia. Natomiast w akcji dodatku SDK należy uzupełnić nazwę i wybrać odpowiedni dodatek.

Rys. 16. Tworzenie cyklicznej akcji z wykorzystaniem dodatku SDK

 

W konfiguracji należy uzupełnić poszczególne sekcje:

1. Konfiguracja połączenia – należy ustawić połączenie dodatków SDK ze skrzynką e-Doręczeń. Wszystkie akcje będą mieć taką samą konfigurację połączenia.

  • Bazowe połączenie do serwisu – należy wybrać utworzone wcześniej połączenie z serwisem e-Doręczenia – w omawianym przypadku jest to „[e-DORECZENIA] Agent baza”.
  • Źródło skrzynek – należy wybrać utworzone wcześniej źródło, które służy do mapowania ID spółki na adres skrzynki e-Doręczeń.
  • Opcjonalne połączenia do Azure Key Vault – połączenie używane do pobrania klucza prywatnego z AKV.
  • Reużywaj klucza – po pierwszym pobraniu klucz będzie przechowywany w pamięci. Włączenie tej opcji ogranicza liczbę pobrań klucza z Azure Key Vault.
  • Czas ważności tokena – czas ważności tokena w sekundach, na INT i PROD: 300 s.
  • Użyj proxy – dane proxy pobierane z proxy skonfigurowanego w BPS.
  • Użyj niestandardowego proxy – dane proxy definiowane w konfiguracji dodatku.

Rys. 17. Konfiguracja połączenia

 

2. Konfiguracja synchronizacji

  • Data pierwszej synchronizacji – data, od której mają być synchronizowane wiadomości, używana przy pierwszym uruchomieniu. Jeśli nie zostanie podana, użyta będzie data bieżąca. Można wprowadzić datę wcześniejszą, aby zsynchronizować zaległe wiadomości.
  • Sprawdzane godziny wstecz
  • Maksymalny czas wykonania – maksymalny czas wykonania akcji w sekundach.
  • Źródło z pobranymi wiadomościami – źródło zwracające dwie kolumny, pierwsza z ID wiadomości e-Doręczenia i druga z ID spółki. Powinno zwracać dane z ograniczonego przedziału czasu, np. z ostatniego miesiąca. Należy wybrać wcześniej utworzone źródło „[e-DORĘCZENIA] Źródło do Sync”.
  • Nazwa kolumny z id wiadomości – z atrybutów formularza należy wybrać nazwę pola w bazie „_MessageId”.
  • Nazwa kolumny z id spółki – z atrybutów formularza należy wybrać nazwę pola w bazie „_IDspółki”.

Rys. 18. Konfiguracja synchronizacji akcji „SyncMessages”

3. Konfiguracja pobranych wiadomości

  • Źródło z pobranymi wiadomościami 
  • Nazwa kolumny z id wiadomości 
  • Nazwa kolumny z id spółki 
  • Maksymalny czas wykonania 

Rys. 19. Konfiguracja pobranych wiadomości

4. Konfiguracja startowania dokumentu – dane używane do wystartowania nowego elementu z pojedynczą wiadomością. 

  • ID typu formularza 
  • ID obiegu 
  • ID ścieżki startowej – użytkownik może wybrać ścieżkę „[eDoręczenia] Pobierz wiadomość MINIMUM” lub „[eDoręczenia] Pobierz wiadomość FULL”. Ścieżka minimum pobiera tylko metadane wiadomości, zaś ścieżka FULL zawiera dodatki, które pobierają wiadomości, załączniki i dowody. Opisano w dalszej części artykułu. 
  • ID pola na ręczne ID spółki – w tym polu dodatek zapisuje ID spółki na podstawie tabeli ID spółki i adresu ADE. Spośród atrybutów formularza należy wybrać to samo pole, które zostało użyte wcześniej w konfiguracji synchronizacji, ale tym razem wskazać kolumnę ID „_IDspółki”. Używane tylko jeżeli nie są używane spółki WEBCON. 

Rys. 20. Konfiguracja startowania dokumentu

 

5. Konfiguracja pól  – metadane wiadomości, które zostaną uzupełnione na formularzu przy starcie.

  • ID pola na ID wiadomości – w tym polu dodatek zapisuje ID wiadomości pobranej ze skrzynki e-Doręczeń. Z atrybutów formularza należy wskazać to pole, które wybrano powyżej w konfiguracji synchronizacji, przy czym tym razem należy użyć kolumny ID „_IDwiadomości”.

Rys. 21. Konfiguracja pól 

 

Przed konfiguracją kolejnych dodatków SDK, dodano nowe ścieżki przejścia. Można utworzyć domyślną ścieżkę „[eDoręczenia] Pobierz wiadomość MINIMUM”, która pobierze minimum danych wiadomości z e-Doręczeń bez oznaczania wiadomości jako odczytanej oraz ścieżkę „[eDoręczenia] Pobierz wiadomość FULL” pobierającą pełną zawartość wiadomości z e-Doręczeń wraz z dowodami i załącznikami. Wiadomość zostanie oznaczona jako odczytana.

Tworzenie zadania należy przypisać opiekunom aplikacji. Po dodaniu nowych ścieżek należy również dodać odpowiednie akcje, które obsłużą te operacje, takie jak pobieranie wiadomości, przetwarzanie załączników oraz weryfikacja dowodów.

Rys. 22.  Ścieżka przejścia, która pobiera wiadomości ze skrzynki e-Doręczeń

 

Opis każdej akcji zaprezentowano poniżej.

  • [eDOR] ID wiadomości – picker dla SDK – akcja zmienia wartość pola „_IDwiadomościPicker” (używanego w dodatku ReadMessage) na wartość z pola „_IDwiadomości”.

Rys. 23. Konfiguracja akcji zmień wartość pola „_IDwiadomościPicker”

 

  • [eDOR] Forma dostarczenia – akcja zmienia wartość pola „Forma dostarczenia” na wartość „E-doręczenie”.

Rys. 24. Konfiguracja akcji zmień wartość pola „Forma dostarczenia”

 

  • [eDOR] Pobieranie wiadomości e-Doręczenie – akcja, która pobiera wiadomość ze skrzynki e-Doręczeń, korzystając z dodatku SDK.
    W sekcji Konfiguracja połączenia należy wpisać te same dane, które wstawiono w poprzednich dodatkach SDK. Na samej górze znajduje się dodatkowe pole Identyfikator spółki, na podstawie którego zostanie dopasowany adres skrzynki e-Doręczeń. O tej zmiennej wspomniano już wcześniej – musi ona pasować do nazwy pierwszej kolumny tabeli Źródło adresów.

Rys. 25. Konfiguracja połączenia w dodatku ReadMessage

 

W sekcji Konfiguracja wiadomości należy uzupełnić Pole z identyfikatorem wiadomości tym samym atrybutem, który został zastosowany w pierwszej akcji na obecnej ścieżce.

Rys.26. Konfiguracja wiadomości w dodatku ReadMessage

 

W sekcji Konfiguracja odpowiedzi należy wskazać miejsca do zapisywania informacji o załącznikach oraz błędach.

Rys. 27. Konfiguracja odpowiedzi w dodatku ReadMessage

 

Następnie należy przypisać atrybuty do pól z podstawowymi informacjami wiadomości zgodnie z poniższą instrukcją. Wówczas dane te zostaną uzupełnione po pobraniu wiadomości.

Rys. 28. Konfiguracja odpowiedzi w pobieraniu wiadomości ze skrzynki e-Doręczeń cd.

 

  • [eDOR] Pobieranie załączników z e-Doręczeń – akcja, która pobiera załączniki wiadomości za pomocą dodatku GetAttachments. Załączniki są pobierane na podstawie zapisanych informacji w polu listy załączników. W konfiguracji akcji należy uzupełnić pole ID kategorii załączników identyfikatorem kategorii, do której zostaną przypisane pobrane załączniki.

Rys. 29. Fragment konfiguracji dodatku GetAttachments

 

 

Na ścieżce dodano warunek „Czy jest Treść?”, który sprawdza, czy dołączone są dowody do pobrania.

Rys. 30. Akcja „[eDOR] Pobieranie dowodów” na ścieżce

 

Rys. 31. Warunek „Czy jest Treść?”

 

  • [eDOR] Pobieranie dowodów – akcja, która zostanie wykonana, jeżeli powyższy warunek zostanie spełniony. Pobiera dowody wiadomości za pomocą dodatku GetEvidences.
    Sekcję Konfiguracja połączenia należy uzupełnić w taki sam sposób, jak w poprzednich akcjach. W sekcji Konfiguracja pliku możliwe jest przypisanie pobranych dowodów do konkretnej kategorii załączników. Można także pobrać je jako archiwum w formacie ZIP lub jako pojedyncze pliki XML i załadować na formularz.

Rys. 32. Konfiguracja pliku w konfiguracji dodatku GetEvidences

 

W sekcji Lista dowodów zaznaczenie pola wyboru przy opcji Pobieraj listę dowodów umożliwi pobranie oddzielnej listy.

Rys. 33. Lista dowodów w konfiguracji dodatku GetEvidences

 

  • [eDOR] MessageID – akcja zmienia wartość pola „_IDwiadomości” na wartość z pola „_IDwiadomościPicker”.

Rys. 34. Konfiguracja akcji zmień wartość pola „_IDwiadomości”

 

  • Kontrahent – akcja uzupełnia pole „Kontrahent” na podstawie numeru NIP pobranego z wiadomości w systemie e-Doręczeń. Jeżeli wartość NIP jest pusta, akcja uzupełnia pole „Kontrahent” Nazwą firmy.

Rys. 35.  Konfiguracja akcji zmień wartość pola „Kontrahent”

 

  • Ustaw datę odebrania wiadomości – akcja ustawia atrybut „Data odebrania” na dzień dzisiejszy.

 

W końcowym kroku, gdzie archiwizowane są pobrane wiadomości, można dodać przycisk z akcją umożliwiającą usuwanie wiadomości ze skrzynki e-Doręczeń, aby zapobiec jej zapełnieniu. Do utworzenia tej akcji należy użyć dodatku SDK DeleteMessage, uzupełniając sekcje Konfiguracja połączenia i sekcje Konfiguracja dodatku analogicznie jak we wcześniejszych akcjach SDK.

Rys. 36. Przycisk menu do usuwania wiadomości ze skrzynki e-Doręczeń

 

Aplikacja

Na koniec warto opisać, w jaki sposób korzystać z aplikacji. Po wykryciu przez akcję cykliczną nowej wiadomości w skrzynce e-Doręczeń system uruchamia ścieżkę do pobierania wiadomości, załączników oraz dowodów. Odbiorca wiadomości znajdzie odpowiednio wypełniony formularz na liście swoich zadań lub w raporcie korespondencji przychodzącej.

Poniżej zaprezentowano widok wspomnianego formularza. Po lewej stronie w szczegółach odbioru uzupełnione jest pole „Data nadania” oraz „Data odebrania”. W szczegółach dokumentu uzupełnione są pola „Temat” i „Treść”. Po prawej stronie w zakładce Dane z e-Doręczenia znajduje się pole „ADE Nadawcy”. Proces można kontynuować jak w przypadku standardowej korespondencji, uzupełniając sprawę, przypisując właściciela i przekazując dokument do wybranej osoby.

 

Rys. 37. Formularz wejściowy wyświetlany po wykonaniu akcji cyklicznej pobierania wiadomości ze skrzynki e-Doręczeń

 

System e-Doręczenia umożliwia użytkownikom bezpieczne odbieranie wiadomości elektronicznych. Opisany powyżej proces zapewnia bezpieczne, przejrzyste i efektywne zarządzanie komunikacją elektroniczną, umożliwiając użytkownikom łatwe odbieranie i przeglądanie wiadomości oraz ich załączników, a także zarządzanie nimi.