Przejdź do treści

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

  1. Założenie adresu do e-Doręczeń
  2. Zakup certyfikatu i dodanie systemu do skrzynki
  3. Instalacja serwisu pośredniczącego
  4. Połączenie Navigatora z serwisem
  5. Adres skrzynki firmy w Navigatorze
  6. 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.

  1. Osoba uprawniona loguje się do Konta Przedsiębiorcy na biznes.gov.pl.
  2. Wybiera usługę e-Doręczenia i wypełnia wniosek o adres do doręczeń elektronicznych.
  3. Podpisuje i wysyła wniosek. Po jego rozpatrzeniu adres zostaje wpisany do BAE, a skrzynka jest gotowa do użycia.
  4. 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

  1. Zaloguj się do skrzynki do e-Doręczeń jako właściciel lub administrator skrzynki.
  2. Otwórz moduł Uprawnienia, a następnie zakładkę Systemy.
  3. Kliknij Dodaj system.
  4. Wpisz Nazwę systemu „Navigator” i opcjonalnie opis (do 255 znaków).
  5. Jako środek uwierzytelniający wybierz certyfikat i wgraj jego część publiczną (plik certyfikatu bez klucza prywatnego).
  6. 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 .pfx lub .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.db w 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 logs aplikacji.

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