← Back to all articles

Jak generovat vyhovující Peppol fakturu pomocí n8n a SealDoc

SealDoc Team · · 5 min read

Generování vyhovující Peppol faktury zahrnuje více pohyblivých částí, než vypadá. Potřebujete platný CII XML dokument, správný profil EN 16931, kontejner PDF/A-3, vloženou přílohu XML a ideálně RFC 3161 časové razítko, než jde do archivu. Dělat to vše od nuly ve vlastní integraci je práce na týdny.

Tento tutoriál ukazuje, jak dosáhnout stejného výsledku v n8n přibližně za 30 minut pomocí community uzlu n8n-nodes-sealdoc. Bez vlastního kódu. Workflow pokrývá generování faktur, polling jobu a ukládání výsledků.

Předpoklady

Než začnete, potřebujete:

  • Instanci n8n verze 1.0 nebo novější, buď self-hosted nebo n8n Cloud. Community uzel funguje na obou.
  • Účet SealDoc na plánu Starter nebo vyšším. Funkce generování faktur a razítkování jsou dostupné od Starter.
  • API klíč SealDoc. Vygenerujte ho v dashboardu SealDoc v části Nastavení, pak API klíče. Zkopírujte ho okamžitě; zobrazujeme ho jen jednou.

Nainstalujte community uzel na instanci n8n:

npm i n8n-nodes-sealdoc

Po instalaci restartujte n8n. Nyní uvidíte uzel SealDoc dostupný v panelu uzlů v kategorii Community.

Co workflow dělá

Tento workflow přijme data faktury (prodávající, kupující, řádkové položky, částky) a vytvoří plně vyhovující Factur-X PDF/A-3 s vloženým CII XML. Kroky jsou:

  1. Trigger poskytne data faktury jako JSON (z webhooks, databázového dotazu, odeslání formuláře nebo jiného n8n zdroje).
  2. Uzel SealDoc Invoice.Generate odešle strukturovaná data do SealDoc API a vrátí ID jobu.
  3. Uzel SealDoc Job.Get polluje, dokud job nedokončí, a vrátí URL pro stažení generovaného dokumentu.
  4. Finální uzel uloží výsledek na vámi zvolené archivní místo.

Krok 1: nastavte trigger

Vytvořte nový workflow. Přidejte uzel trigger Webhook. Nastavte HTTP metodu na POST. Tím získáte URL, na které lze volat s daty faktury z libovolného systému schopného HTTP requestů.

Pro testování lze použít také Execute Workflow Trigger nebo Manual Trigger se statickými daty. Důležité je, aby trigger výstupy byly JSON objekt s poli faktury. V dalším kroku na tato pole odkážeme.

Minimální příklad dat faktury, která by měl váš trigger poskytnout:

{
  "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: přidejte uzel Invoice.Generate

Přidejte uzel SealDoc na plátno. Nastavte:

  • Resource: Invoice
  • Operation: Generate
  • Profile: EN 16931 (použijte EXTENDED, pokud váš kupující nebo nařízení vyžadují další pole)
  • Embed timestamp: ON (připojí RFC 3161 razítko k výstupnímu dokumentu)
  • Input data: mapujte z výstupu triggeru pomocí n8n výrazů, např. {{ $json.invoiceNumber }} pro číslo faktury, {{ $json.seller.vatNumber }} pro DIČ prodávajícího, a tak dále pro každé pole.

V části Credentials vyberte nebo vytvořte přihlašovací údaje SealDoc API. Vložte svůj API klíč do pole Secret.

Klikněte Execute Node pro testování. Pokud je API klíč platný a data faktury jsou kompletní, obdržíte odpověď jako:

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

Job byl zařazen do fronty. SealDoc API ho zpracovává asynchronně, takže pomalé renderování PDF neblokuje spuštění vašeho workflow.

Krok 3: přidejte uzel Job.Get s pollingem

Přidejte druhý uzel SealDoc. Nastavte:

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

Zabalte tento uzel do uzlu n8n Wait nastaveného na 3sekundový interval se smyčkou zpět, která kontroluje, zda status je completed nebo failed. Většina faktur se dokončí do 5 sekund. Nastavte maximální počet iterací na 10, aby nedocházelo k nekonečné smyčce při skutečně uvázlém jobu.

Když je status completed, odpověď Job.Get obsahuje:

  • downloadUrl: časově omezená URL (platná 10 minut) odkazující na generovaný dokument PDF/A-3.
  • evidencePackUrl: ZIP archiv obsahující původní vstupy, výstup PDF/A-3, vložené Factur-X XML, token RFC 3161 razítka a soubor s manifestovým hašem. To je to, co předáte auditorovi.
  • facturXProfile: skutečně použitý profil (potvrzuje EN 16931 nebo EXTENDED).
  • timestampedAt: UTC časové razítko tokenu RFC 3161, což je právně relevantní čas vzniku.

Pokud je status failed, zkontrolujte pole failureReason. Běžné hodnoty jsou validation_failed (ve vstupu chybělo povinné pole), unsupported_currency (SealDoc podporuje EUR, USD, GBP, CHF, PLN, CZK a rostoucí seznam) a quota_exceeded (byl dosažen váš měsíční limit jobů).

Krok 4: uložte výsledek

Přidejte libovolný uzel úložiště, který odpovídá vašemu stacku. Běžné možnosti:

  • Uzel HTTP Request pro PUT souboru do vlastního systému pro správu dokumentů nebo bucketu MinIO.
  • Uzel Google Drive nebo Dropbox, pokud pro archiv používáte cloudové úložiště.
  • Uzel FTP/SFTP pro on-premise úložiště.
  • Move Binary Data plus Write Binary File, pokud je n8n self-hosted a chcete zapisovat přímo na cestu v souborovém systému.

Použijte downloadUrl z odpovědi Job.Get pro načtení binárního souboru, pak ho předejte uzlu úložiště. Uložte také evidencePackUrl odděleně, pokud to vaše politika uchovávání vyžaduje, což by měla pro faktury nad určitou hodnotou nebo v regulovaných odvětvích.

Co získáte ve výstupu

Generovaný soubor je dokument PDF/A-3B. Jeho otevření v libovolném prohlížeči PDF zobrazí vykreslenou fakturu. Vložená příloha factur-x.xml obsahuje celé CII XML, čitelné účetním softwarem podporujícím import Factur-X nebo ZUGFeRD. RFC 3161 razítko je vloženo do slovníku informací o dokumentu PDF a je nezávisle ověřitelné.

Pokud výstup spustíte přes validátor (náš bezplatný nástroj Validator soubor přijímá přímo), uvidíte zelený výsledek pro shodu PDF/A-3B, platnost schématu EN 16931 a přítomnost přílohy Factur-X.

Další kroky

Tento tutoriál pokrývá základní flow generování. SealDoc API také podporuje:

  • Peppol lookup: před generováním faktury zkontrolujte, zda je kupující dosažitelný na Peppol prostřednictvím zdroje Peppol v uzlu SealDoc.
  • Pouze validace: odešlete existující soubor Factur-X nebo XRechnung pro validaci schématu bez generování nového dokumentu.
  • Dávkové generování: odešlete více payloadů faktur v jednom API volání pro scénáře s vysokým objemem.

Kompletní dokumentace API je na naší stránce pro vývojáře s OpenAPI specifikací a zkopírovatelnými curl příklady pro každý endpoint.

← Back to all articles