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

Generowanie zgodnej faktury elektronicznej składa się z większej liczby elementów, niż się wydaje. Potrzebujesz prawidłowej faktury XML, właściwego profilu EN 16931, kontenera PDF/A-3 z osadzonym w nim plikiem XML, a najlepiej także sygnatury czasowej RFC 3161, zanim dokument trafi do archiwum. Zbudowanie tego wszystkiego we własnej integracji to tygodnie pracy.

Ten tutorial pokazuje, jak złożyć ten sam wynik w n8n za pomocą węzła społeczności n8n-nodes-sealdoc. Bez własnego kodu. Przepływ generuje fakturę, pobiera XML i PDF/A-3, a następnie zapisuje oba pliki.

Wymagania wstępne

Samodzielnie hostowana instancja n8n z włączonymi węzłami społeczności.
Obszar roboczy SealDoc z dostępem do API: bezpłatny plan Developer lub dowolny plan płatny. Zobacz cennik.
Klucz API SealDoc. Utworzysz go w aplikacji SealDoc w sekcji Integration → API Keys. Skopiuj go od razu: jest wyświetlany tylko raz.
Dane Twojej firmy. Sprzedawcą na fakturze jest Twoja własna firma, a jej numer VAT musi być zgodny z numerem VAT Twojego obszaru roboczego SealDoc.

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

npm i n8n-nodes-sealdoc

Następnie utwórz dane uwierzytelniające: Credentials → New → SealDoc API, i wklej swój klucz w pole API Key. W polu Base URL pozostaw wartość https://api.sealdoc.eu.

Co robi przepływ

Wyzwalacz dostarcza dane faktury jako JSON: webhook, wiersz z bazy danych, zgłoszenie formularza lub dowolne inne źródło n8n.
SealDoc · Invoice · Generate tworzy fakturę elektroniczną, waliduje ją i pieczętuje jako PDF/A-3. Dzieje się to w ramach jednego wywołania: węzeł zwraca zakończone zadanie.
SealDoc · Invoice · Get XML zwraca XML faktury elektronicznej jako plik.
Węzeł HTTP Request pobiera PDF/A-3.
Węzeł magazynowy umieszcza oba pliki w Twoim archiwum.

Krok 1: skonfiguruj wyzwalacz

Utwórz nowy przepływ i dodaj wyzwalacz Webhook z metodą HTTP POST. Otrzymujesz w ten sposób URL, który każdy system może wywołać z danymi faktury. Do testów równie dobrze sprawdzi się Manual Trigger ze stałymi danymi.

Minimalny przykład danych, które może dostarczyć wyzwalacz:

{
  "invoiceNumber": "INV-2026-00042",
  "invoiceDate": "2026-05-06",
  "dueDate": "2026-06-05",
  "buyer": {
    "name": "Widget BV",
    "vatNumber": "NL987654321B01",
    "address": "Keizersgracht 10",
    "postalCode": "1015 CN",
    "city": "Amsterdam",
    "country": "NL"
  },
  "line": {
    "description": "Consulting services May 2026",
    "quantity": 10,
    "unitPriceExclVat": 150.00
  }
}

Sprzedawcy nie ma w tym ładunku. To Twoja własna firma, więc ustawiasz ją raz, bezpośrednio w węźle.

Krok 2: dodaj Invoice · Generate

Dodaj węzeł SealDoc, zmień jego nazwę na Generate invoice i ustaw:

Resource: Invoice. Operation: Generate.
Invoice Number Source: Own Number. Invoice Number: {{ $json.invoiceNumber }}. Wolisz, żeby to SealDoc numerował Twoje faktury? Wybierz wtedy SealDoc Numbering Series.
Invoice Date: {{ $json.invoiceDate }}. Due Date: {{ $json.dueDate }}.
Currency: EUR.
VAT Rate: 0.21. Stawkę podaje się jako ułamek, więc 21% to 0.21. W polu VAT Category pozostaw “derive from the rate”, a pole VAT Label zostaw puste: przy stawce standardowej SealDoc sam wpisuje opis VAT.
Seller: Twoja firma, z polami Name, VAT Number, Address, Postal Code, City i Country (kod dwuliterowy).
Buyer Source: Buyer Details. Buyer: zmapuj każde pole z wyzwalacza, na przykład {{ $json.buyer.name }} i {{ $json.buyer.postalCode }}. Klientów zapisanych w SealDoc możesz użyć bezpośrednio, wybierając Buyer Profile.
Lines: dodaj pozycję z Description {{ $json.line.description }}, Quantity {{ $json.line.quantity }}, Unit Hour oraz Unit Price (Excl. VAT) {{ $json.line.unitPriceExclVat }}.
Profile: Basic (Factur-X 1.0). Węzeł oferuje też XRechnung DE, który wymaga Buyer Reference (Leitweg-ID) i danych kontaktowych sprzedawcy, oraz Peppol BIS 3.0 (UBL 2.1), który wymaga identyfikatorów punktów końcowych Peppol obu stron.
RFC 3161 Timestamp: włączony, co jest ustawieniem domyślnym.

Wybierz swoje dane uwierzytelniające SealDoc API i uruchom węzeł. Odpowiedź wygląda tak:

{
  "jobId": "3f6c2a9e-8d41-4b7a-9c0e-5a2b1d7e4f10",
  "status": "completed",
  "statusUrl": "/api/jobs/3f6c2a9e-8d41-4b7a-9c0e-5a2b1d7e4f10"
}

completed oznacza, że faktura jest zbudowana, zwalidowana zgodnie z EN 16931 i zapieczętowana. Nie ma czego odpytywać. Jeśli odpowiedź kiedykolwiek zwróci zamiast tego queued lub processing, węzeł SealDoc · Job · Get z tym samym jobId powie Ci, kiedy zadanie zostanie ukończone.

Krok 3: pobierz XML

Dodaj drugi węzeł SealDoc: Resource Invoice, Operation Get XML, Job ID {{ $('Generate invoice').item.json.jobId }}. Węzeł zwraca XML faktury elektronicznej jako plik binarny w polu data: factur-x.xml dla profilu Basic, xrechnung.xml dla XRechnung i peppol-ubl.xml dla Peppol BIS.

Krok 4: pobierz PDF/A-3

Dodaj węzeł HTTP Request:

Method: GET
URL: https://api.sealdoc.eu/api/download/{{ $('Generate invoice').item.json.jobId }}
Authentication: Generic Credential Type, a następnie Header Auth, z nazwą X-Api-Key i Twoim kluczem API jako wartością.
Response Format: File.

Wynikiem jest zapieczętowany PDF/A-3 z osadzonym XML.

Krok 5: zapisz wynik

Dodaj węzeł magazynowy pasujący do Twojego stosu: Google Drive, Dropbox, zasobnik zgodny z S3, SFTP do własnego serwera albo Write Binary File bezpośrednio na hoście n8n.

Od planu Starter każde zadanie ma też swój Legal Evidence Pack: GET /api/jobs/{id}/evidence-pack, z tym samym nagłówkiem X-Api-Key. SealDoc składa go zaraz po zakończeniu zadania; jeśli zapytasz w pierwszych chwilach, API odpowie kodem 409 z nagłówkiem Retry-After, więc wystarczy krótki węzeł Wait przed żądaniem.

Gdy coś pójdzie nie tak

Błędy wracają natychmiast, jako odpowiedź z polem code:

400 przy nieprawidłowych danych wejściowych, na przykład seller_required, currency_required lub invalid_vat_rate.
402 plan_feature_required, gdy Twój plan nie obejmuje danej funkcji.
403 seller_vat_mismatch, gdy numer VAT sprzedawcy różni się od numeru VAT Twojego obszaru roboczego.
409 quota_reached, gdy miesięczny limit został wykorzystany.
422 einvoice_invalid, gdy faktura nie przechodzi walidacji.

Domyślnie węzeł SealDoc zatrzymuje przepływ w razie błędu. Ustaw opcję On Error węzła tak, aby kontynuował z wyjściem błędu, i skieruj to wyjście do Slacka lub na e-mail, żeby człowiek zobaczył, co trzeba poprawić.

Co otrzymujesz

PDF/A-3, który każda przeglądarka PDF otwiera jako czytelną fakturę, z osadzonym XML dla oprogramowania księgowego importującego Factur-X lub ZUGFeRD. Token sygnatury czasowej RFC 3161 jest przechowywany razem z zadaniem i można go pobrać osobno (GET /api/jobs/{id}/timestamp). Wrzuć PDF do naszego bezpłatnego narzędzia Validator, aby samodzielnie zobaczyć werdykt i wszystkie ustalenia.

Następne kroki

Walidacja istniejących faktur: SealDoc · Validator · Check waliduje plik Factur-X lub ZUGFeRD, który już masz, bez generowania czegokolwiek.
Renderowanie innych dokumentów: SealDoc · Document · Generate zamienia Markdown lub HTML w zapieczętowany PDF/A-3 w jednym wywołaniu.
Odczyt tego, co zostało wystawione: SealDoc · Invoice · Get Summary zwraca numer faktury, profil, język i sumy VAT wygenerowanej faktury.

Pełna dokumentacja API, ze specyfikacją OpenAPI i przykładami curl, jest podlinkowana na naszej stronie dla deweloperów.