Przygotowanie systemu pod e-Doręczenia
Ten artykuł opisuje uruchomienie integracji z e-Doręczeniami: od założenia adresu do e-Doręczeń przez zakup certyfikatu i konfigurację serwisu pośredniczącego po ustawienia Navigatora. Kroki są ułożone w kolejności, w jakiej trzeba je wykonać. Sposób korzystania z akcji e-Doręczeń w procedurach obiegu opisuje artykuł Integracja z e-Doręczeniami.
Jak działa integracja¶
Navigator nie łączy się z e-Doręczeniami bezpośrednio. Komunikację obsługuje serwis pośredniczący dostarczany przez firmę Archman:
- Navigator wywołuje serwis, uwierzytelniając się kluczem API (ApiKey).
- Serwis pośredniczący łączy się ze skrzynką do e-Doręczeń firmy, używając certyfikatu systemu zarejestrowanego w skrzynce.
- e-Doręczenia sprawdzają, czy system jest dodany do skrzynki i ma ważny certyfikat.
Kolejność uruchomienia¶
- Założenie adresu do e-Doręczeń
- Zakup certyfikatu i dodanie systemu do skrzynki
- Instalacja serwisu pośredniczącego
- Połączenie Navigatora z serwisem
- Adres skrzynki firmy w Navigatorze
- Formularze i procedury obiegu
Krok 1: adres do e-Doręczeń¶
Jeżeli firma ma już adres do e-Doręczeń i aktywną skrzynkę, można przejść do kroku 2.
Firma wpisana do KRS składa wniosek o adres przez Konto Przedsiębiorcy w serwisie biznes.gov.pl. Potrzebny jest Profil Zaufany lub kwalifikowany podpis elektroniczny osoby uprawnionej do reprezentacji firmy.
- Osoba uprawniona loguje się do Konta Przedsiębiorcy na biznes.gov.pl.
- Wybiera usługę e-Doręczenia i wypełnia wniosek o adres do doręczeń elektronicznych.
- Podpisuje i wysyła wniosek. Po jego rozpatrzeniu adres zostaje wpisany do BAE, a skrzynka jest gotowa do użycia.
- Właściciel skrzynki może nadać uprawnienia administratora innym pracownikom w module Uprawnienia skrzynki.
System zewnętrzny (krok 2) może dodać tylko właściciel lub administrator skrzynki, dlatego warto od razu ustalić, kto w firmie będzie pełnił tę rolę.
Adres do e-Doręczeń ma postać identyfikatora, np. AE:PL-12345-67890-ABCDE-12. Będzie potrzebny w kroku 5.
Więcej informacji: Uzyskaj adres i skrzynkę do e-Doręczeń.
Krok 2: dodanie systemu do skrzynki¶
Aby serwis pośredniczący mógł pobierać i wysyłać pisma, w skrzynce trzeba zarejestrować system zewnętrzny z certyfikatem, którym serwis będzie się uwierzytelniał. System dodany do skrzynki ma uprawnienia do obserwowania wszystkich wiadomości firmy i zarządzania nimi.
Zakup certyfikatu kwalifikowanego¶
Firma, która założyła skrzynkę przez biznes.gov.pl, musi kupić certyfikat kwalifikowany, np. kwalifikowaną pieczęć elektroniczną, u kwalifikowanego dostawcy usług zaufania.
Certyfikat musi spełniać następujące warunki:
- klucz RSA, co najmniej 2048 bitów,
- użycie klucza „digital signature”,
- w polu Subject dane jednoznacznie identyfikujące firmę, np. NIP, REGON lub nazwa.
Certyfikat służy do podpisywania zapytań wysyłanych przez serwis do e-Doręczeń.
Serwis pośredniczący działa na serwerze bez udziału użytkownika, dlatego przy zamawianiu certyfikatu wybierz wersję w pliku (np. .pfx lub .p12 z kluczem prywatnym), a nie na karcie kryptograficznej. Certyfikat ma ograniczony okres ważności i przed jego upływem trzeba kupić nowy.
Rejestracja systemu w skrzynce¶
- Zaloguj się do skrzynki do e-Doręczeń jako właściciel lub administrator skrzynki.
- Otwórz moduł Uprawnienia, a następnie zakładkę Systemy.
- Kliknij Dodaj system.
- Wpisz Nazwę systemu „Navigator” i opcjonalnie opis (do 255 znaków).
- Jako środek uwierzytelniający wybierz certyfikat i wgraj jego część publiczną (plik certyfikatu bez klucza prywatnego).
- Zapisz formularz i potwierdź dodanie systemu.
Data ważności certyfikatu jest widoczna na liście systemów. Po zakupie nowego certyfikatu podmień go na stronie Szczegóły systemu i przekaż do serwisu pośredniczącego.
Pełny opis rejestracji systemu: Instrukcja dodania systemu zewnętrznego, rozszerzona (gov.pl).
Krok 3: serwis pośredniczący¶
Do instalacji serwisu potrzebne są:
- adres do e-Doręczeń firmy,
- certyfikat kwalifikowany z kluczem prywatnym (plik
.pfxlub.p12) i hasło do niego, - serwer z dostępem do internetu (HTTPS), do którego serwer Navigatora ma dostęp sieciowy.
Po instalacji warto wiedzieć, gdzie serwis przechowuje dane:
- Konfiguracja skrzynek (adres skrzynki, nazwa, odcisk palca certyfikatu) jest zapisywana w pliku bazy danych
database\eDelivery.dbw katalogu aplikacji serwisu. Uwzględnij go w kopiach zapasowych. - Certyfikaty są instalowane w magazynie certyfikatów Osobisty (My) konta, na którym działa serwis.
- Logi są zapisywane w katalogu
logsaplikacji.
Plik konfiguracyjny serwisu¶
Ustawienia serwisu znajdują się w pliku appsettings.json w katalogu aplikacji. Można je też przekazać zmiennymi środowiskowymi.
| Ustawienie | Opis |
|---|---|
ApiUrl:AuthUrl |
Adres usługi uwierzytelniania e-Doręczeń |
ApiUrl:UserAgentUrl |
Adres API skrzynki (User Agent API) |
ApiUrl:SearchEngineUrl |
Adres wyszukiwarki adresów w BAE (Search Engine API) |
Authorization |
Lista kluczy API (ApiKey), którymi mogą się uwierzytelniać aplikacje korzystające z serwisu. Jeden z tych kluczy wpisz w ustawieniach Navigatora |
Swagger:Enabled |
Włącza stronę Swagger z opisem i testowaniem metod serwisu. Domyślnie wyłączona |
Domyślne adresy w ApiUrl wskazują środowisko testowe e-Doręczeń (INT). Do pracy produkcyjnej trzeba je zmienić na adresy środowiska produkcyjnego. Wszystkie trzy adresy muszą wskazywać to samo środowisko, a jedna instalacja serwisu łączy się z jednym środowiskiem.
Konfiguracja skrzynki w serwisie¶
Dla każdej skrzynki, z której ma korzystać Navigator, w serwisie zapisuje się:
- adres do e-Doręczeń,
- odcisk palca (thumbprint) certyfikatu zainstalowanego w serwisie,
- opcjonalnie nazwę skrzynki, np. nazwę firmy.
Przy wielofirmowości każda firma z własną skrzynką ma w serwisie osobny wpis.
Adres skrzynki
Adres w konfiguracji serwisu musi być zapisany dokładnie tak samo jak w polu Adres e-doręczeń kontrahenta przypisanego do firmy w Navigatorze, bo po nim serwis wyszukuje konfigurację.
Metody serwisu (dla administratora serwera)¶
Metody można wywołać z dowolnego narzędzia HTTP albo ze strony Swagger serwisu (jeżeli jest włączona). Każde wywołanie musi zawierać nagłówek ApiKey z jednym z kluczy zapisanych w ustawieniu Authorization.
Konfiguracja skrzynki składa się z dwóch kroków: instalacji certyfikatu, która zwraca jego odcisk palca, i zapisu konfiguracji skrzynki z tym odciskiem.
Instalacja certyfikatu: POST /certificate/install
Metoda instaluje certyfikat z kluczem prywatnym w magazynie certyfikatów Osobisty konta, na którym działa serwis, i zwraca odcisk palca certyfikatu. Parametry (formularz multipart/form-data):
| Parametr | Opis |
|---|---|
certificate |
Plik certyfikatu z kluczem prywatnym (.pfx lub .p12) |
password |
Hasło do pliku certyfikatu |
Certyfikat można też zainstalować ręcznie w magazynie Osobisty konta serwisu, razem z kluczem prywatnym. Odcisk palca odczytasz wtedy z właściwości certyfikatu.
Utworzenie pliku PFX: POST /certificate/create
Jeżeli dostawca wydał certyfikat i klucz prywatny jako osobne pliki PEM, metoda łączy je w plik PFX, który potem zainstalujesz metodą POST /certificate/install. Parametry (formularz multipart/form-data):
| Parametr | Opis |
|---|---|
certificate |
Plik certyfikatu (PEM) |
privateKey |
Plik klucza prywatnego zaszyfrowanego hasłem (PEM) |
password |
Hasło do klucza prywatnego. Tym samym hasłem zostanie zabezpieczony zwrócony plik PFX |
Metoda zwraca plik certificate.pfx i niczego nie instaluje.
Zapis konfiguracji skrzynki: PUT /configuration/{mailboxAddress}
W ścieżce podaj adres do e-Doręczeń skrzynki, np. /configuration/AE:PL-12345-67890-ABCDE-12. Treść żądania (JSON):
| Pole | Opis |
|---|---|
name |
Nazwa skrzynki (informacyjnie) |
certificateThumbprint |
Odcisk palca certyfikatu zwrócony przez metodę instalacji certyfikatu. Pole wymagane |
Przykład:
{
"name": "Firma Sp. z o.o.",
"certificateThumbprint": "A1B2C3D4E5F60718293A4B5C6D7E8F9012345678"
}
Metoda dodaje nową konfigurację albo nadpisuje istniejącą dla tego adresu. Po zakupie nowego certyfikatu zainstaluj go i ponownie wywołaj tę metodę z nowym odciskiem palca.
Pozostałe metody:
| Metoda | Opis |
|---|---|
GET /configuration |
Lista skonfigurowanych skrzynek |
GET /configuration/{mailboxAddress} |
Konfiguracja jednej skrzynki: adres, nazwa, odcisk palca certyfikatu, daty dodania i zmiany |
DELETE /configuration/{mailboxAddress} |
Usunięcie konfiguracji skrzynki |
GET /version |
Wersja serwisu |
Klucz z ustawienia Authorization i adres serwisu będą potrzebne w kroku 4.
Krok 4: połączenie Navigatora z serwisem¶
W menu Ustawienia > Pozostałe > Ustawienia, w sekcji e-Doręczenia, uzupełnij:
| Pole | Wartość |
|---|---|
| Adres API e-Doręczenia | Adres, pod którym działa serwis pośredniczący |
| ApiKey API e-Doręczenia | Jeden z kluczy zapisanych w ustawieniu Authorization serwisu. Navigator przechowuje go w postaci zaszyfrowanej |
Oba ustawienia są wspólne dla całego systemu, także przy wielofirmowości.
Krok 5: adres skrzynki firmy¶
Akcje e-Doręczeń odczytują adres skrzynki firmy z kontrahenta przypisanego do firmy. Na formularzu tego kontrahenta uzupełnij pole systemowe Adres e-doręczeń adresem z kroku 1. Jeżeli pola nie ma na formularzu kontrahenta, dodaj je w edytorze formularza.
Przy wielofirmowości każda firma ma własnego kontrahenta i własny adres skrzynki. Akcje wybierają skrzynkę na podstawie firmy wskazanej w parametrze lub firmy dokumentu.
To samo pole na formularzach pozostałych kontrahentów przechowuje ich adresy do e-Doręczeń. Akcja Wyślij wiadomość może z niego pobrać adres odbiorcy, a akcje pobierające pisma rozpoznać po nim nadawcę.
Do wysyłki hybrydowej kontrahent firmy musi mieć dodatkowo nazwę i domyślny adres z uzupełnionym krajem, ulicą, kodem pocztowym i miejscowością.
Krok 6: formularze i procedury obiegu¶
Akcje e-Doręczeń umieszcza się w procedurach obiegu dokumentów. Na formularzach pism przychodzących i wychodzących potrzebne są atrybuty na dane z e-Doręczeń, które akcje odczytują lub uzupełniają:
- adres nadawcy i nazwa nadawcy,
- adres odbiorcy,
- temat i treść,
- ID wiadomości i ID wątku,
- data nadania i data doręczenia,
- znak sprawy,
- identyfikator zadania wysłania wiadomości,
- status wysyłki, najlepiej w tabeli, bo pismo wysłane do kilku odbiorców ma osobny status dla każdego z nich.
Opis akcji i ich parametrów: Integracja z e-Doręczeniami.
Najczęstsze błędy¶
| Objaw | Przyczyna i rozwiązanie |
|---|---|
| Komunikat „ApiKey API e-Doręczeń nie może być puste.” | Nie uzupełniono klucza w ustawieniach systemu (krok 4). |
| Komunikat o pustym adresie skrzynki | Kontrahent przypisany do firmy nie ma uzupełnionego pola Adres e-doręczeń (krok 5). |
| Komunikat „Pobieranie wiadomości z e-Doręczeń w trakcie.” | Poprzednie pobieranie dla tej skrzynki jeszcze trwa. Poczekaj na jego zakończenie. |
| Brak połączenia z serwisem | Błędny adres API albo serwer Navigatora nie ma dostępu sieciowego do serwisu pośredniczącego |
| Komunikat „Brak API Key.” lub „Niewłaściwy API Key.” | Klucz w ustawieniach Navigatora nie odpowiada żadnemu kluczowi w ustawieniu Authorization serwisu |
| Komunikat „Brak konfiguracji dla podanego numeru skrzynki.” | W serwisie nie ma konfiguracji skrzynki o adresie z kontrahenta firmy (sprawdź zapis adresu, patrz Konfiguracja skrzynki w serwisie). |
| Komunikat „Certyfikat '…' nie znaleziony.” | Certyfikatu o odcisku zapisanym w konfiguracji skrzynki nie ma w magazynie Osobisty konta serwisu |
| Komunikat „Certyfikat nie zawiera klucza prywatnego.” | Certyfikat zainstalowano bez klucza prywatnego albo ma klucz ECDSA. Zainstaluj plik PFX z kluczem RSA. |
| Skrzynka odrzuca wgrywany certyfikat | Certyfikat nie spełnia wymagań z kroku 2, np. nie ma użycia klucza „digital signature” albo nie jest kwalifikowany |
| Integracja przestała działać po dłuższym czasie | Najczęściej wygasł certyfikat. Kup nowy i podmień go w skrzynce oraz w serwisie pośredniczącym |
| Nie można dodać systemu w skrzynce | Zalogowany użytkownik nie jest właścicielem ani administratorem skrzynki |
| Wysyłka hybrydowa kończy się błędem o brakujących danych | Kontrahent firmy lub odbiorca nie ma kompletnego adresu (kraj, ulica, kod pocztowy, miejscowość) albo nazwy |
Informacje o usłudze i dokumentacja integracyjna: Integracja usługi e-Doręczeń (gov.pl).
Co dalej¶
- Integracja z e-Doręczeniami: akcje e-Doręczeń w procedurach obiegu.