Trzy node'y n8n, jedno archiwum gotowe na compliance

Najtrudniejszą częścią automatyzacji compliance rzadko są same przepisy. To hydraulika, która łączy te przepisy z systemami, na których Twój biznes już działa. Przepisy mówią, że faktura musi pozostać czytelna, autentyczna i nienaruszona przez cały okres przechowywania, razem z zapisem tego, co się z nią działo. Twoja skrzynka pocztowa mówi “masz nowy załącznik”. Zbudowanie mostu między tymi dwoma światami to miejsce, w którym większość zespołów się zatrzymuje.

Ten wpis prowadzi przez najmniejszy workflow, który zamyka tę lukę, zbudowany w n8n z node’em społecznościowym n8n-nodes-sealdoc. Trzy połączone node’y, zero własnego kodu.

Co budujemy

Workflow, który z każdym przychodzącym PDF-em wykonuje następujące kroki:

Pobiera plik z wybranego triggera: skrzynki pocztowej, uploadu do Slacka, dysku w chmurze, zewnętrznego webhooka, czegokolwiek, czego n8n może nasłuchiwać.
Przekazuje go do SealDoc, który konwertuje go do PDF/A-3, sprawdza zgodność z PDF/A, żąda znacznika czasu RFC 3161 i zapisuje każdy krok w audit trail opartym na łańcuchu hashy.
Zapisuje wynik tam, gdzie nakazuje Twoja polityka retencji.

Czego nie budujesz sam: konwersji do PDF/A-3, znakowania czasem wraz z ponowieniami, audit trail, evidence packa. SealDoc wykonuje tę pracę za jednym wywołaniem API.

Wymagania wstępne

Self-hosted instancja n8n z włączonymi node’ami społecznościowymi.
Obszar roboczy SealDoc w planie Starter lub wyższym. Od Startera dostępne są znaczniki czasu i evidence packi, a ten workflow opiera się na obu. Zobacz cennik.
Klucz API SealDoc, utworzony w aplikacji SealDoc w sekcji Integration → API Keys. Skopiuj go od razu: jest wyświetlany tylko raz.

Zainstaluj node w n8n w sekcji Settings → Community nodes → Install, podając nazwę pakietu n8n-nodes-sealdoc. Jeśli instalujesz node’y ręcznie, uruchom to polecenie w folderze node’ów n8n (zwykle ~/.n8n/nodes) i zrestartuj n8n:

npm i n8n-nodes-sealdoc

Utwórz dane uwierzytelniające w Credentials → New → SealDoc API i wklej swój klucz w pole API Key. Node SealDoc oferuje teraz pięć zasobów: Document, Invoice, Job, Peppol Check i Validator. Ten workflow korzysta z zasobu Job.

Node 1, trigger

Wybierz trigger pasujący do miejsca, w którym dziś lądują Twoje faktury. Używamy tu Gmail Trigger, bo to częsty punkt wyjścia; wzorzec jest taki sam dla IMAP, OneDrive, URL-a Webhooka n8n czy dowolnego innego źródła, które dostarcza plik.

Skonfiguruj Gmail Trigger tak, żeby uruchamiał się przy nowych wiadomościach z etykietą, np. incoming-invoices, i włącz Download Attachments. n8n umieszcza wtedy pierwszy załącznik we właściwości binarnej attachment_0.

Node 2, SealDoc · Job · Create

Dodaj node SealDoc, zmień jego nazwę na Archive i ustaw Resource na Job, a Operation na Create:

Input Binary Field: attachment_0. To nazwa właściwości binarnej z Node’a 1, wpisana jako zwykły tekst.
Run OCR: opcjonalnie. Włącz tę opcję dla zeskanowanych dokumentów, żeby PDF/A-3 otrzymał przeszukiwalną warstwę tekstową.

Znacznik czasu nie wymaga żadnego ustawienia: w planie Starter lub wyższym SealDoc żąda znacznika czasu RFC 3161 dla każdego joba.

Node przesyła plik i od razu zwraca ID joba:

{ "jobId": "8b1e4c3a-2f7d-4e9a-b6c5-0d4f2a7e9c13" }

Konwersja odbywa się w tle, więc wolny PDF nigdy nie blokuje Twojej kolejki.

Node 3, SealDoc · Job · Get

Dodaj node Wait na kilka sekund, a po nim kolejny node SealDoc z Resource Job, Operation Get i Job ID {{ $('Archive').item.json.jobId }}. Za nim umieść node IF sprawdzający status:

queued lub processing: wróć pętlą do node’a Wait. Prowadź w pętli licznik, żeby zablokowany job nie mógł jej napędzać w nieskończoność.
completed: PDF/A-3 jest gotowy.
failed: skieruj job na opisaną niżej ścieżkę błędów.

Zakończony job pokazuje swoje dowody w odpowiedzi: timestampedAt i timestampTokenBase64 dla znacznika czasu, outputHash dla wyniku, isPdfACompliant dla sprawdzenia zgodności.

Aby pobrać plik, dodaj node HTTP Request: GET https://api.sealdoc.eu/api/download/{{ $json.id }}, z Header Auth (X-Api-Key i Twój klucz) oraz Response Format File. Następnie przekaż plik do swojego node’a magazynującego.

Każdy job ma też Legal Evidence Pack: GET /api/jobs/{id}/evidence-pack, z tym samym nagłówkiem. Ten ZIP zawsze zawiera compliance_passport.json, MANIFEST.json i manifest.sha256, a tam, gdzie istnieją, także dokument, chain_of_custody.json, ledger.json z public-keys.jwk oraz token RFC 3161 timestamp_token.tsr. Jest samodzielny i weryfikowalny offline: urzędnik skarbowy może sprawdzić jego integralność bez kontaktu z naszymi serwerami. SealDoc składa go zaraz po zakończeniu joba; jeśli zapytasz w pierwszych chwilach, API odpowie kodem 409 z nagłówkiem Retry-After.

A co z błędami

Dwa rodzaje, w dwóch momentach:

Przy wysyłaniu. Brak pliku lub nieprawidłowe języki OCR dają 400, plan bez danej funkcji daje 402, a wyczerpany miesięczny limit daje 409 quota_reached. W takich przypadkach job nie powstaje, a node SealDoc zatrzymuje workflow. Jeśli chcesz kierować te błędy dalej, ustaw jego opcję On Error na kontynuowanie z wyjściem błędu.
W trakcie przetwarzania. Job kończy się statusem failed, a errorMessage podaje przyczynę, na przykład plik, którego nie da się otworzyć. Skieruj gałąź failed node’a IF do Slacka lub na e-mail, żeby człowiek wiedział, że coś wymaga uwagi.

Urząd znakowania czasem, który nie odpowiada, nie powoduje niepowodzenia joba. Job zostaje ukończony, a compliance.rfc3161Timestamp w odpowiedzi Get pokazuje, czy znacznik czasu jest obecny.

Dlaczego trzy node’y wystarczą

Ten workflow nie zawiera własnej logiki konwersji, znakowania czasem ani archiwizacji. To jest właśnie sens. API SealDoc to granica; Twój workflow n8n to tkanka łączna między tą granicą a Twoimi systemami biznesowymi. Gdy przepisy lub formaty ewoluują, SealDoc ewoluuje za tym samym wywołaniem API, a Ty aktualizujesz wersję node’a.

Ten workflow archiwizuje dokumenty, które otrzymujesz. Dla faktur, które wysyłasz, ten sam node ma zasób Invoice, który zamienia ustrukturyzowane dane w fakturę Factur-X, XRechnung lub Peppol BIS. Zobacz, jak wygenerować zgodną fakturę elektroniczną za pomocą n8n.

Poza n8n

Wszystko z tego tutoriala jest dostępne także bezpośrednio przez REST API SealDoc. Od planu Growth webhooki wysyłają job.processing, job.completed i job.failed do Twojego własnego endpointu, więc możesz całkowicie zrezygnować z pętli pollingu. Wszystkie sposoby połączenia znajdziesz na naszej stronie integracji.

Hydraulika compliance jest rozwiązana. Co zrobisz z zaoszczędzonym czasem, zależy od Ciebie.