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 każda faktura B2B musi być w ustrukturyzowanym formacie elektronicznym, archiwizowana przez dziesięć lat i powiązana z odporną na manipulację chain of custody. Twoje oprogramowanie księgowe mówi “masz nowy załącznik we współdzielonej skrzynce”. 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 naprawdę zamyka tę lukę, zbudowany w n8n z node’em społecznościowym n8n-nodes-sealdoc. Trzy połączone node’y. Mniej więcej 200 linii JSON-a po wyeksportowaniu workflow. Zero własnego kodu.

Co budujemy

Workflow, który dla każdego przychodzącego PDF-a wykonuje:

1. Pobiera plik z wybranego triggera (skrzynka pocztowa, watch folder, upload do Slacka, zewnętrzny webhook, wszystko, czego n8n może nasłuchiwać).
2. Przekazuje go do SealDoc, który konwertuje go do PDF/A-3, osadza XML Factur-X obok wyrenderowanej faktury, dołącza znacznik czasu RFC 3161 i pakuje całość w archiwum do pobrania.
3. Zapisuje wynik tam, gdzie nakazuje Twoja polityka retencji.

Czego nie musisz budować sam: konwersji do PDF/A-3, ekstrakcji XML Factur-X, znakowania czasem, audit trail, hasha manifestu evidence pack, logiki ponowień dla urzędu znakowania czasem. API SealDoc robi tę pracę za jednym endpointem HTTP.

Wymagania wstępne

• Instancja n8n, self-hosted albo n8n Cloud. Node społecznościowy działa na obu.
• Konto SealDoc co najmniej w planie Starter (moat-feature’y, na których opiera się ten workflow, custody, znaczniki czasu i evidence pack, są dostępne od Startera).
• Klucz API SealDoc. Wygeneruj go w dashboardzie pod API keys, skopiuj secret jednorazowo (nie pokażemy go ponownie).

Zainstaluj node społecznościowy:

npm i n8n-nodes-sealdoc

Zrestartuj n8n. Node SealDoc pojawia się teraz pod Nodes z trzema zasobami: Job, Validator i Peppol.

Node 1, trigger

Wybierz trigger pasujący do miejsca, w którym dziś lądują Twoje faktury. W tym przewodniku użyjemy Gmail Trigger, bo to najczęstsza forma, jaką widzimy, ale wzorzec jest identyczny dla IMAP, OneDrive, SharePoint, URL-a Webhooka n8n czy obserwowanego folderu.

Skonfiguruj Gmail Trigger tak, żeby uruchamiał się przy nowych wiadomościach z załącznikiem PDF w konkretnej etykiecie, np. incoming-invoices. Wyjściem tego node’a jest binarny PDF w attachments[0].data.

Node 2, SealDoc Job · Create

Przeciągnij node SealDoc na canvas, ustaw Resource na Job i Operation na Create. Skonfiguruj:

• File: zbinduj do {{ $binary.attachments_0 }} (PDF z Node’a 1).
• Embed Factur-X: ON. SealDoc automatycznie wykrywa pola faktury i generuje ustrukturyzowany XML; jeśli źródłowy PDF zawiera już załącznik XML, SealDoc go respektuje i waliduje zamiast nadpisywać.
• Timestamp: ON. Wyjściowy PDF/A-3 będzie miał znacznik czasu RFC 3161 z TSA, którą sami operujemy, później do odpytania jako dowód, kiedy dokument istniał.
• Retention category: wybierz tę, którą nakazuje Twoje prawo podatkowe (kategoria dla polskiej ordynacji podatkowej jest na liście).

Node zwraca natychmiast jobId i status pending. Nie czekaj tu synchronicznie. Konwersja Factur-X plus znacznik czasu zwykle kończy się w mniej niż pięć sekund dla zwykłej faktury, ale przetwarzanie PDF nie jest deterministyczne i nie chcesz, żeby wolny PDF z deklaracji podatkowej zablokował całą Twoją kolejkę.

Node 3, SealDoc Job · Get

Dodaj kolejny node SealDoc. Ustaw Resource na Job i Operation na Get. Zbinduj Job ID do {{ $node["SealDoc Create"].json.jobId }}. Owiń node prymitywem Wait w n8n z opóźnieniem 2 sekund i maksymalnie 10 iteracjami, polling do momentu, aż status będzie completed albo failed.

Przy completed odpowiedź zawiera downloadUrl ważny pięć minut. URL prowadzi do skonwertowanego PDF/A-3, który teraz jest zgodny z Factur-X, oznaczony znacznikiem czasu i zarejestrowany w naszej chain of custody.

Dostajesz też evidencePackUrl, jeśli Twój plan zawiera evidence packi. Ten ZIP zawiera oryginalny PDF, skonwertowany PDF/A-3, XML Factur-X, token RFC 3161, plik hasha manifestu oraz pokwitowanie JSON wyliczające każdy krok. Audytorzy to uwielbiają, bo jest samodzielny i weryfikowalny offline; możesz wręczyć kopię urzędnikowi skarbowemu, a on zweryfikuje integralność bez dzwonienia do naszych serwerów.

A co z błędami

SealDoc zwraca ustrukturyzowane przyczyny niepowodzenia w polu failureReason. Cztery, które zobaczysz w praktyce:

• validation_failed, źródłowy PDF jest uszkodzony albo zabezpieczony hasłem. Skieruj do zespołu, który go wgrał.
• unsupported_source, np. faktycznie zaszyfrowany PDF, którego nie potrafimy otworzyć. Odeślij do nadawcy.
• timestamp_unavailable, nasza TSA miała awarię. Ponawiamy automatycznie; jeśli budżet ponowień się wyczerpie, job kończy się jako failed i możesz go uruchomić ponownie.
• quota_exceeded, miesięczny limit jobów Twojego planu został wyczerpany. Albo upgrade, albo czekaj na reset.

W n8n skieruj gałąź failed node’a Get do powiadomienia Slack lub e-mail, żeby człowiek wiedział, kiedy coś naprawdę utknęło.

Dlaczego trzy node’y wystarczą

Zauważysz, że ten workflow sam w sobie nie wykonuje logiki walidacji, podpisywania 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 belgijskie rozporządzenie B2B wejdzie w życie, nie musisz przebudowywać tego workflow. Gdy ruszy francuski obowiązek z września 2026, nie musisz go przebudowywać. Gdy regulator zaktualizuje profil Factur-X w 2027, podnosisz wersję node’a SealDoc.

To wartość wzorca connector: regulacyjny zamęt mieszka w naszej codebase, nie w Twojej.

Poza n8n

Jeśli nie używasz n8n, każda operacja z tego tutoriala jest dostępna także bezpośrednio przez REST API SealDoc, albo przez Webhooki, jeśli wolisz powiadomienia push od pollingu. Pełne menu znajdziesz na naszej stronie integracji, z gotowymi do skopiowania przykładami dla każdej powierzchni. Konektory Make, Zapier i Exact Online są w aktywnej budowie; jeśli Twój stack korzysta z któregoś z nich, napisz do nas po wczesny dostęp.

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