Skip to content
Autenti / Blog / Automatyczna walidacja podpisów elektronicznych przez API - jak zintegrować ją z ERP i obiegiem dokumentów

Automatyczna walidacja podpisów elektronicznych przez API - jak zintegrować ją z ERP i obiegiem dokumentów

Firmy leasingowe, banki czy przedsiębiorstwa budowlane otrzymują setki podpisanych elektronicznie dokumentów od klientów, kontrahentów i podwykonawców. Ręczne przesyłanie każdego pliku do walidatora, pobieranie wyników i przypisywanie ich do odpowiedniej sprawy zajmuje czas. Utrudnia też zachowanie jednolitego sposobu weryfikacji.

Integracja przez API pozwala włączyć walidację podpisów i pieczęci elektronicznych bezpośrednio w system ERP lub system zarządzania dokumentami, czyli DMS. Sprawdzenie dokumentu może stać się stałym etapem jego obsługi, a wyniki i dokumenty potwierdzające walidację mogą zostać powiązane z właściwą umową, kontrahentem lub sprawą.

Jak zaprojektować taki proces? Trzeba uwzględnić nie tylko przesłanie pliku, ale również interpretację wyników, obsługę wyjątków i archiwizację.

Kluczowe wnioski przed integracją

  • API walidacji służy do sprawdzania podpisów i pieczęci w już podpisanych dokumentach. Wysyłanie dokumentów do podpisu jest odrębnym procesem.
  • Pozytywny wynik walidacji nie zastępuje oceny treści umowy, uprawnień osoby podpisującej ani wymagań dotyczących formy czynności prawnej.
  • Integracja powinna uwzględniać wyniki poszczególnych podpisów i pieczęci, a nie wyłącznie ogólne podsumowanie dla dokumentu.
  • Wynik negatywny, wynik nieokreślony i błąd techniczny wymagają odmiennych ścieżek obsługi.
  • Pobranie Raportu Walidacji w XML i Poświadczenia Walidacji w PDF powinno być częścią procesu, a nie dodatkową czynnością wykonywaną przez pracownika.

Dwa scenariusze: wysyłanie do podpisu i odbieranie podpisanych dokumentów

Przed rozpoczęciem integracji warto określić, w którym miejscu obiegu dokumentów potrzebna jest walidacja.

Wysyłasz dokumenty do podpisania

System ERP przygotowuje dokument, przekazuje go do procesu podpisywania, a następnie odbiera podpisany plik. W takim scenariuszu trzeba ustalić, jakie informacje i dowody dostarcza platforma podpisująca oraz czy proces wymaga dodatkowej walidacji.

Samo zakończenie procesu podpisywania nie powinno być utożsamiane z wykonaniem odrębnej kwalifikowanej usługi walidacji.

Odbierasz dokumenty podpisane poza Twoją organizacją

Kontrahent przesyła umowę przez portal B2B, e-mail lub platformę zakupową. Dokument został podpisany w zewnętrznym systemie, a Twoja organizacja chce sprawdzić podpisy i pieczęcie przed przekazaniem go do dalszej obsługi.

Właśnie w tym scenariuszu integracja walidacji z ERP lub DMS jest szczególnie przydatna. Pozwala wprowadzić powtarzalną kontrolę na wejściu i zachować jej wynik przy dokumencie.

Walidacja dotyczy jednak podpisów, pieczęci i integralności podpisanych danych. Nie rozstrzyga samodzielnie, czy umowa jest skuteczna, czy podpisujący miał odpowiednie pełnomocnictwo ani czy treść dokumentu spełnia wymagania organizacji.

Jak działa integracja API walidacji z ERP lub DMS

Na poziomie procesu biznesowego integrację można podzielić na cztery kroki. Szczegółowe wywołania, sposób uwierzytelniania i strukturę odpowiedzi należy wdrożyć zgodnie z dokumentacją API walidatora Autenti.

1. Przygotowanie dokumentu do walidacji

System odbiera plik i przypisuje go do konkretnej sprawy. Przed wysłaniem sprawdza jego rozmiar, format i kompletność danych potrzebnych do walidacji.

Zgodnie z regulaminem usługi Autenti obsługuje formaty PAdES i XAdES. Maksymalna wielkość obsługiwanego pliku wynosi 20 MB. Korzystanie z usługi wymaga konta na Platformie Autenti, a limity mogą zależeć od wybranego pakietu.

W przypadku podpisu zewnętrznego należy uwzględnić również podpisane dane, do których ten podpis się odnosi. Sam plik zawierający podpis może nie wystarczyć do przeprowadzenia pełnej weryfikacji.

2. Zlecenie walidacji

Integracja przekazuje wymagane dane do usługi. Po stronie ERP lub DMS warto zapisać identyfikator sprawy, czas zlecenia oraz informację, której wersji dokumentu dotyczy operacja.

Dzięki temu wynik zostanie przypisany do właściwego pliku również wtedy, gdy kontrahent prześle kilka wersji tej samej umowy.

3. Odczyt i interpretacja wyniku

System odbiera wynik walidacji i odczytuje informacje potrzebne do dalszej obsługi dokumentu.

Należy rozróżnić podsumowanie dla dokumentu od wyników poszczególnych podpisów i pieczęci. Dokument może zawierać kilka podpisów o różnych wynikach weryfikacji. Autenti udostępnia zarówno informacje ogólne, jak i wyniki szczegółowe. Ich znaczenie opisuje przewodnik po wynikach walidacji.

Nie należy też zakładać, że każdy certyfikat zawiera PESEL, NIP lub komplet danych przydatnych w procesie biznesowym. Zakres dostępnych informacji zależy między innymi od rodzaju i zawartości certyfikatu.

4. Pobranie i zapis dokumentów wynikowych

Integracja powinna pobrać Raport Walidacji w XML oraz Poświadczenie Walidacji w PDF i powiązać je z dokumentem źródłowym.

W przypadku korzystania z API regulamin Autenti przewiduje możliwość pobrania tych dokumentów przez 24 godziny od ich wygenerowania. Warto więc zaplanować pobieranie bezpośrednio po zakończeniu walidacji oraz monitorować, czy zapis obu plików się powiódł.

Trzy podejścia do architektury integracji

Sposób włączenia walidacji w obieg dokumentów zależy od skali, oczekiwanego czasu obsługi i możliwości systemu.

Walidacja przy przyjęciu dokumentu

Przesłanie dokumentu do ERP lub DMS uruchamia jego sprawdzenie. Do czasu uzyskania wyniku dokument pozostaje oznaczony jako oczekujący na walidację.

Po zakończeniu procesu system zapisuje wynik, pobiera raport i poświadczenie oraz stosuje ustalone reguły dalszego obiegu.

Takie podejście sprawdza się, gdy wynik jest potrzebny przed kolejną czynnością, na przykład przekazaniem umowy do akceptacji. Warto zachować otrzymany plik także w przypadku wyniku negatywnego lub błędu technicznego, aby umożliwić wyjaśnienie sytuacji.

Walidacja w kolejce zadań

System zapisuje przychodzące dokumenty i umieszcza zadania walidacji w kolejce. Osobny komponent przetwarza je w tle, na bieżąco lub w określonych godzinach.

Pozwala to oddzielić przyjęcie dokumentu od czasu potrzebnego na jego sprawdzenie. Ułatwia też kontrolowanie liczby równoległych operacji, ponawianie nieudanych prób i obsługę większych wolumenów.

Kolejka jest elementem architektury po stronie organizacji. Sama w sobie nie oznacza, że API dostawcy działa asynchronicznie lub udostępnia osobną operację przetwarzania wsadowego.

Integracja przez platformę obiegu dokumentów lub low-code

Jeśli firma korzysta z platformy BPM, DMS lub narzędzi automatyzacji, może rozważyć wykorzystanie ich możliwości komunikacji z API.

Przykładowy przepływ obejmuje odebranie pliku, zlecenie walidacji, zapis wyniku i skierowanie dokumentu do odpowiedniej kolejki.

Przed wyborem rozwiązania należy sprawdzić, czy konkretny konektor obsługuje usługę walidacji. Dostępność integracji Autenti do wysyłania dokumentów do podpisu nie oznacza automatycznie dostępności funkcji walidacji. Może być potrzebne własne wywołanie API lub rozszerzenie konektora.

Jak obsługiwać wyniki walidacji

Logika biznesowa powinna odróżniać wynik sprawdzenia podpisu od decyzji o zaakceptowaniu dokumentu.

Poniższe określenia opisują znaczenie wyników. Konkretne nazwy pól i wartości wykorzystywane w integracji należy odwzorować zgodnie z aktualną dokumentacją API.

Wynik pozytywny

Oznacza, że weryfikacja podpisu lub pieczęci zakończyła się pozytywnie według zastosowanych kryteriów walidacji.

System może zapisać wynik i przekazać dokument do kolejnego etapu, jeżeli spełnione są również pozostałe wymagania procesu.

Nie należy automatycznie oznaczać każdego pozytywnie zweryfikowanego podpisu jako kwalifikowanego. Rodzaj podpisu i wynik jego walidacji to odrębne informacje. Podobnie ważny podpis nie potwierdza samodzielnie uprawnienia danej osoby do reprezentowania kontrahenta.

Przykładowa etykieta w ERP może brzmieć: „Walidacja podpisów zakończona pozytywnie”. Informację o rodzaju podpisu warto przechowywać oddzielnie.

Wynik negatywny

Oznacza, że weryfikacja wykazała nieprawidłowość. Przyczyną może być na przykład niepoprawny podpis kryptograficzny lub problem z integralnością podpisanych danych.

Dokument powinien trafić do obsługi wyjątku wraz ze szczegółową przyczyną wyniku. Na tej podstawie można zdecydować o kontakcie z nadawcą, pozyskaniu właściwego pliku lub ponownym podpisaniu dokumentu.

Sam wynik negatywny nie uzasadnia automatycznego stwierdzenia, że doszło do oszustwa ani że cała umowa jest nieważna.

Wynik nieokreślony

Oznacza, że nie można jednoznacznie potwierdzić ani wykluczyć prawidłowości podpisu na podstawie dostępnych danych. Powodem może być między innymi brak danych potwierdzających ważność certyfikatu lub brak dowodów pozwalających ustalić, czy podpis został złożony w okresie jego ważności.

Taki wynik wymaga odrębnej ścieżki obsługi. Zależnie od przyczyny może być potrzebne uzupełnienie danych, ponowienie walidacji lub konsultacja z dostawcą.

Decyzja biznesowa o dalszym procedowaniu dokumentu nie zmienia wyniku walidacji na pozytywny. W systemie warto zachować zarówno wynik techniczny, jak i informację o osobie, która podjęła decyzję, oraz jej uzasadnieniu.

Błąd techniczny

Brak odpowiedzi, problem z uwierzytelnieniem czy przerwa w komunikacji nie są wynikiem negatywnym walidacji.

System powinien oznaczyć taką operację jako niedokończoną lub zakończoną błędem technicznym. Ponawianie żądań należy zaprojektować zgodnie z dokumentacją API, z uwzględnieniem limitów oraz ryzyka powielenia operacji.

W monitoringu warto osobno śledzić błędy komunikacji, wyniki negatywne, wyniki nieokreślone oraz nieudane pobrania raportów.

Archiwizacja wyników walidacji

Wynik walidacji jest najbardziej użyteczny wtedy, gdy można łatwo powiązać go z konkretnym dokumentem i odtworzyć przebieg jego obsługi.

W elektronicznej teczce sprawy warto przechowywać:

  1. Oryginalny podpisany dokument, a przy podpisie zewnętrznym także odpowiedni plik podpisu.
  2. Raport Walidacji w XML.
  3. Poświadczenie Walidacji w PDF.
  4. Metadane procesu: identyfikator walidacji, datę i czas jej wykonania, wyniki poszczególnych podpisów i pieczęci oraz powiązanie z dokumentem źródłowym.
  5. Informacje o obsłudze wyjątków i podjętych decyzjach biznesowych.


Raport XML służy do maszynowego przetwarzania szczegółowych informacji o walidacji. Poświadczenie PDF prezentuje wynik w formie czytelnej dla człowieka.

Polityka usługi Autenti przewiduje przechowywanie Raportu Walidacji w XML przez sześć lat, a Poświadczenia Walidacji w PDF przez 24 godziny. Okres przechowywania raportu przez dostawcę nie oznacza jednak, że pozostaje on przez cały ten czas dostępny do samodzielnego pobrania przez API.

Dlatego organizacja powinna zadbać o własne archiwum. Okres przechowywania dokumentów należy dopasować do ich rodzaju, obowiązujących wymagań i przyjętej polityki retencji. Dostęp do plików i danych z certyfikatów powinien być ograniczony do uprawnionych osób.

Kiedy wybrać interfejs użytkownika, a kiedy API

Interfejs przeglądarkowy sprawdzi się przy sporadycznej walidacji lub wtedy, gdy pracownik analizuje każdy dokument indywidualnie.

API warto rozważyć, gdy dokumenty regularnie trafiają do ERP, DMS lub portalu B2B, a organizacja potrzebuje powtarzalnego procesu i automatycznego zapisywania wyników.

Można również połączyć oba podejścia: zautomatyzować standardową obsługę dokumentów, a wyjątki kierować do pracowników analizujących raporty. W takim modelu automatyzacja ogranicza pracę ręczną, pozostawiając miejsce na ocenę przypadków wymagających wyjaśnienia.

O wyborze powinny decydować nie tylko wolumeny, ale również znaczenie dokumentów, koszt ich obsługi oraz wymagania dotyczące audytowalności.

Jak przygotować wdrożenie

Przed uruchomieniem integracji ustal:

  • które dokumenty mają podlegać walidacji i w którym momencie procesu;
  • jakie rodzaje podpisów i pieczęci są wymagane w poszczególnych sprawach;
  • jakie wyniki pozwalają na automatyczne przejście do kolejnego etapu;
  • kto odpowiada za wyjaśnianie wyjątków;
  • gdzie będą zapisywane dokumenty, raporty i poświadczenia;
  • jak system zareaguje na niedostępność usługi lub nieudane pobranie wyników.


Następnie przetestuj integrację na reprezentatywnych dokumentach. Uwzględnij pliki z wieloma podpisami, podpisy zewnętrzne, wyniki nieokreślone oraz błędy komunikacji.

API kwalifikowanej walidacji pozwala włączyć sprawdzanie podpisów i pieczęci w codzienny obieg dokumentów. Wartość takiego wdrożenia wynika z połączenia walidacji, właściwej interpretacji wyników i zachowania dokumentacji procesu.

Zapoznaj się z dokumentacją API walidatora Autenti i warunkami świadczenia usługi. Jeśli chcesz omówić integrację z systemami swojej organizacji, skontaktuj się z nami przez stronę Walidatora Kwalifikowanego Autenti.


Artykuł ma charakter informacyjny i edukacyjny. Nie stanowi porady prawnej ani indywidualnej rekomendacji wdrożeniowej. Wynik walidacji dotyczy podpisów lub pieczęci elektronicznych w zakresie określonym polityką usługi i nie zastępuje oceny ważności ani skuteczności czynności prawnej, umocowania osoby podpisującej czy wymaganej formy dokumentu. W konkretnych sprawach należy uwzględnić obowiązujące przepisy, aktualną dokumentację i warunki usługi, a w razie wątpliwości skonsultować się z prawnikiem lub specjalistą odpowiedzialnym za wdrożenie.