← Back to all articles

Jak generować zgodną fakturę Peppol za pomocą n8n i SealDoc

SealDoc Team · · 5 min read

Generowanie zgodnej faktury Peppol składa się z większej liczby elementów niż się wydaje. Potrzebujesz prawidłowego dokumentu CII XML, właściwego profilu EN 16931, kontenera PDF/A-3, osadzonego załącznika XML i najlepiej sygnatury czasowej RFC 3161 przed trafieniem do archiwum. Zbudowanie tego wszystkiego od zera we własnej integracji to tygodnie pracy.

Ten tutorial pokazuje, jak złożyć ten sam wynik w n8n w około 30 minutach, używając węzła społeczności n8n-nodes-sealdoc. Bez własnego kodu. Przepływ obejmuje generowanie faktury, odpytywanie statusu zadania i przechowywanie wyniku.

Wymagania wstępne

Zanim zaczniesz, potrzebujesz:

  • Instancji n8n w wersji 1.0 lub nowszej, samodzielnie hostowanej lub na n8n Cloud. Węzeł społeczności działa na obu.
  • Konta SealDoc na planie Starter lub wyższym. Funkcje generowania faktur i sygnatur czasowych są dostępne od planu Starter.
  • Klucza API SealDoc. Wygeneruj go w panelu SealDoc w sekcji Ustawienia, następnie Klucze API. Skopiuj go od razu; pokazujemy go tylko raz.

Zainstaluj węzeł społeczności w swojej instancji n8n:

npm i n8n-nodes-sealdoc

Uruchom ponownie n8n po instalacji. W panelu węzłów w kategorii Community pojawi się węzeł SealDoc.

Co robi przepływ

Ten przepływ pobiera dane faktury (sprzedawca, nabywca, pozycje, kwoty) i produkuje w pełni zgodny Factur-X PDF/A-3 z osadzonym CII XML. Kroki są następujące:

  1. Wyzwalacz dostarcza dane faktury jako JSON (z webhooka, zapytania do bazy danych, zgłoszenia formularza lub innego źródła n8n).
  2. Węzeł SealDoc Invoice.Generate wysyła ustrukturyzowane dane do SealDoc API i zwraca identyfikator zadania.
  3. Węzeł SealDoc Job.Get odpytuje do momentu zakończenia zadania i zwraca URL pobierania wygenerowanego dokumentu.
  4. Końcowy węzeł przechowuje wynik w wybranej lokalizacji archiwum.

Krok 1: skonfiguruj wyzwalacz

Utwórz nowy przepływ. Dodaj węzeł wyzwalacza Webhook. Ustaw metodę HTTP na POST. Daje to URL, który możesz wywoływać z dowolnego systemu zdolnego do wykonania żądania HTTP.

Do testów możesz też użyć wyzwalacza Execute Workflow Trigger lub Manual Trigger ze statycznymi danymi. Ważne jest, aby wyzwalacz wystawiał obiekt JSON z polami faktury. Będziemy odwoływać się do tych pól w następnym kroku.

Minimalny przykład danych faktury, które wyzwalacz powinien dostarczać:

{
  "invoiceNumber": "INV-2026-00042",
  "issueDate": "2026-05-06",
  "dueDate": "2026-06-05",
  "seller": {
    "name": "Acme BV",
    "vatNumber": "NL123456789B01",
    "address": "Herengracht 1, 1000 AA Amsterdam, NL",
    "iban": "NL91ABNA0417164300"
  },
  "buyer": {
    "name": "Widget GmbH",
    "vatNumber": "DE987654321",
    "address": "Hauptstrasse 10, 10115 Berlin, DE"
  },
  "lines": [
    {
      "description": "Consulting services May 2026",
      "quantity": 10,
      "unitPrice": 150.00,
      "vatRate": 21
    }
  ],
  "currency": "EUR"
}

Krok 2: dodaj węzeł Invoice.Generate

Dodaj węzeł SealDoc do kanwy. Ustaw:

  • Resource: Invoice
  • Operation: Generate
  • Profile: EN 16931 (użyj EXTENDED, jeśli Twój nabywca lub mandat wymaga dodatkowych pól)
  • Embed timestamp: ON (dołącza sygnaturę RFC 3161 do dokumentu wyjściowego)
  • Input data: mapuj z wyjścia wyzwalacza za pomocą wyrażeń n8n, np. {{ $json.invoiceNumber }} dla numeru faktury, {{ $json.seller.vatNumber }} dla numeru VAT sprzedawcy itd.

W sekcji Credentials wybierz lub utwórz dane uwierzytelniające API SealDoc. Wklej swój klucz API w polu Secret.

Kliknij Execute Node, aby przetestować. Jeśli klucz API jest ważny, a dane faktury kompletne, otrzymasz odpowiedź podobną do:

{
  "jobId": "job_9kxQr2mPLv",
  "status": "pending",
  "estimatedSeconds": 4
}

Zadanie zostało dodane do kolejki. SealDoc API przetwarza je asynchronicznie, aby powolne renderowanie PDF nie blokowało wykonania przepływu.

Krok 3: dodaj węzeł Job.Get z odpytywaniem

Dodaj drugi węzeł SealDoc. Ustaw:

  • Resource: Job
  • Operation: Get
  • Job ID: {{ $node["SealDoc Invoice Generate"].json.jobId }}

Owiń ten węzeł w węzeł n8n Wait ustawiony na interwał 3 sekund, z pętlą sprawdzającą, czy status wynosi completed lub failed. Większość faktur kończy się w mniej niż 5 sekund. Ustaw maksymalną liczbę iteracji na 10, aby uniknąć nieskończonej pętli przy naprawdę zablokowanym zadaniu.

Gdy status wynosi completed, odpowiedź Job.Get zawiera:

  • downloadUrl: ograniczony czasowo URL (ważny przez 10 minut) wskazujący na wygenerowany dokument PDF/A-3.
  • evidencePackUrl: archiwum ZIP zawierające oryginalne dane wejściowe, wyjściowy PDF/A-3, osadzony Factur-X XML, token sygnatury RFC 3161 i plik skrótu manifestu. To właśnie wręczasz audytorowi.
  • facturXProfile: faktycznie użyty profil (potwierdza EN 16931 lub EXTENDED).
  • timestampedAt: sygnatura UTC tokenu RFC 3161, czyli prawnie znaczący czas utworzenia.

Jeśli status wynosi failed, sprawdź pole failureReason. Typowe wartości to validation_failed (brak wymaganego pola w danych wejściowych), unsupported_currency (SealDoc obsługuje EUR, USD, GBP, CHF, PLN, CZK i rosnącą listę) oraz quota_exceeded (osiągnięto miesięczny limit zadań).

Krok 4: przechowaj wynik

Dodaj węzeł magazynowy odpowiedni do Twojego stosu. Typowe opcje:

  • Węzeł HTTP Request do umieszczenia pliku w Twoim systemie zarządzania dokumentami lub zasobniku MinIO.
  • Węzeł Google Drive lub Dropbox, jeśli używasz magazynu w chmurze do archiwum.
  • Węzeł FTP/SFTP do magazynowania on-premise.
  • Move Binary Data plus Write Binary File, jeśli n8n jest samodzielnie hostowane i chcesz pisać bezpośrednio do ścieżki systemu plików.

Użyj downloadUrl z odpowiedzi Job.Get, aby pobrać plik binarny, a następnie przekaż go do węzła magazynowego. Przechowuj też evidencePackUrl oddzielnie, jeśli Twoja polityka retencji tego wymaga, a powinna w przypadku faktur powyżej określonej wartości lub w regulowanych branżach.

Co otrzymujesz w wyniku

Wygenerowany plik to dokument PDF/A-3B. Otwarcie go w dowolnej przeglądarce PDF pokazuje wyrenderowaną fakturę. Osadzony załącznik factur-x.xml zawiera pełny CII XML, czytelny przez oprogramowanie księgowe obsługujące import Factur-X lub ZUGFeRD. Sygnatura RFC 3161 jest osadzona w słowniku informacji o dokumencie PDF i jest niezależnie weryfikowalna.

Jeśli przepuścisz wynik przez walidator (nasze bezpłatne narzędzie Validator przyjmuje plik bezpośrednio), zobaczysz zielony wynik dla zgodności PDF/A-3B, ważności schematu EN 16931 i obecności załącznika Factur-X.

Następne kroki

Ten tutorial obejmuje podstawowy przepływ generowania. SealDoc API obsługuje również:

  • Wyszukiwanie Peppol: przed generowaniem faktury sprawdź, czy nabywca jest osiągalny w Peppol przez zasób Peppol w węźle SealDoc.
  • Tylko walidacja: prześlij istniejący plik Factur-X lub XRechnung do walidacji schematu bez generowania nowego dokumentu.
  • Generowanie wsadowe: prześlij wiele ładunków faktur w jednym wywołaniu API dla scenariuszy dużych wolumenów.

Pełna dokumentacja API znajduje się na naszej stronie dla deweloperów, wraz ze specyfikacją OpenAPI i przykładami curl gotowymi do skopiowania dla każdego punktu końcowego.

← Back to all articles