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

Dotyczy wersji: 2023.1.1 i powyżej, autor: Michał Puchalski
Artykuł zaktualizowany: 09.12.2025, autor: Michał Puchalski, Lily Adamowicz

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 BPS 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 BPS w wersji min. 2023 (wcześniejsze wersje nie są w pełni wspierane, m.in. nadal konieczne jest użycie Azure Key Vault AKV),
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.
Zalecane jest użycie usługi Azure Key Vault do przechowywania klucza. Dla wersji BPS 2021 oraz 2022 w przypadku obsługi wielu spółek usługa Azure Key Vault jest wymagana.

Na potrzeby artykułu utworzono prosty proces obsługi korespondencji przychodzącej. Dotychczasowo korespondencja rejestrowana była manualnie w systemie WEBCON BPS. 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 CommpanyId ź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ń i pobiera dane do tabeli SDKTemporaryEntities.
StartDocumentsForMessages – uruchamia ścieżkę startową na podstawie wpisów w tabeli SDKTemporaryEntities.
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ń. 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. W przypadku błędu synchronizacji, np. z powodu wygaśnięcia certyfikatu albo potrzeby pobrania zaległych wiadomości, warto wyczyścić tabelę SDKTemporaryEntities.
Synchronizuj po dacie z – należy wybrać czy jako data ostatniej pobranej wiadomości ma być używane SubmissionDate (data wysłania) czy EventData (wartość Event Time (G05) z dowodu A1).
Sprawdzane godziny wstecz – używane przy synchronizacji po SubmissionDate.
Maksymalny czas wykonania – maksymalny czas wykonania akcji w sekundach.

Rys. 18. Konfiguracja synchronizacji w „SyncMessages”

Dodano osobną akcję cykliczną, która będzie uruchamiać ścieżkę startową pobierającą zsynchronizowane wiadomości. Należy skorzystać z dodatku SDK StartDocumentsForMessages. Poniżej objaśniono istotne elementy konfiguracji.

Rys. 19. Cykliczna akcja uruchamiająca pobieranie wiadomości

1. 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. 20. Konfiguracja pól w „StartDocumentsForMessages”

2. Konfiguracja synchronizacji

Ź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 „_IDwiadomości”.
Nazwa kolumny z id spółki – z atrybutów formularza należy wybrać nazwę pola w bazie „_IDspółki”.
Maksymalny czas wykonania (w sekundach)

Rys. 21. Konfiguracja synchronizacji w „StartDocumentsForMessages”

3. 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 BPS.

Rys. 22. Konfiguracja startowania dokumentu w „StartDocumentsForMessages”

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. 23. Ś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 GetMessage) na wartość z pola „_IDwiadomości”.

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

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

Rys. 25. 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. 26. Konfiguracja połączenia w dodatku GetMessage

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

Rys. 27. Konfiguracja odpowiedzi w dodatku GetMessage

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. Na końcu w sekcji Konfiguracja dodatku należy uzupełnić Pole z identyfikatorem wiadomości tym samym atrybutem, który został zastosowany w pierwszej akcji na obecnej ścieżce.

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 uzpeł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.
Sekcje Konfiguracja połączenia i Konfiguracja dodatku 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.