← Zpět na všechny články

Jak generovat vyhovující e-fakturu pomocí n8n a SealDoc

SealDoc Team · · 5 min čtení

Generování vyhovující e-faktury zahrnuje více pohyblivých částí, než se zdá. Potřebujete platnou XML fakturu, správný profil EN 16931, kontejner PDF/A-3 s tímto XML vloženým uvnitř a ideálně časové razítko RFC 3161, než faktura putuje do archivu. Zabudovat to všechno do vlastní integrace je práce na týdny.

Tento tutoriál propojí stejný výsledek v n8n pomocí community uzlu n8n-nodes-sealdoc. Bez vlastního kódu. Workflow vygeneruje fakturu, načte XML i PDF/A-3 a obojí uloží.

Předpoklady

  • Self-hosted instance n8n se zapnutými community uzly.
  • Pracovní prostor SealDoc s přístupem k API: bezplatný plán Developer nebo kterýkoli placený plán. Viz ceník.
  • API klíč SealDoc. Vytvořte ho v aplikaci SealDoc v části Integration → API Keys. Hned ho zkopírujte: zobrazí se jen jednou.
  • Údaje o vaší firmě. Prodávajícím na faktuře je vaše vlastní firma a její DIČ se musí shodovat s DIČ vašeho pracovního prostoru SealDoc.

Nainstalujte uzel v n8n v části Settings → Community nodes → Install pod názvem balíčku n8n-nodes-sealdoc. Pokud uzly instalujete ručně, spusťte ve složce s uzly n8n (obvykle ~/.n8n/nodes) tento příkaz a restartujte n8n:

npm i n8n-nodes-sealdoc

Pak vytvořte přihlašovací údaje: Credentials → New → SealDoc API a vložte svůj klíč do pole API Key. Base URL ponechte na https://api.sealdoc.eu.

Co workflow dělá

  1. Trigger dodá data faktury jako JSON: webhook, řádek z databáze, odeslaný formulář nebo jakýkoli jiný zdroj v n8n.
  2. SealDoc · Invoice · Generate sestaví e-fakturu, zvaliduje ji a zapečetí do PDF/A-3. Děje se to v rámci jediného volání: uzel vrátí hotový job.
  3. SealDoc · Invoice · Get XML vrátí XML e-faktury jako soubor.
  4. Uzel HTTP Request stáhne PDF/A-3.
  5. Uzel úložiště uloží oba soubory do vašeho archivu.

Krok 1: nastavte trigger

Vytvořte nový workflow a přidejte trigger Webhook s HTTP metodou POST. Získáte tak URL, kterou může s daty faktury zavolat jakýkoli systém. Pro testování poslouží stejně dobře Manual Trigger s pevnými daty.

Minimální příklad toho, co může trigger dodat:

{
  "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
  }
}

Prodávající v tomto payloadu není. Je to vaše vlastní firma, takže ho nastavíte jednou přímo v uzlu.

Krok 2: přidejte Invoice · Generate

Přidejte uzel SealDoc, přejmenujte ho na Generate invoice a nastavte:

  • Resource: Invoice. Operation: Generate.
  • Invoice Number Source: Own Number. Invoice Number: {{ $json.invoiceNumber }}. Chcete, aby vaše faktury číslovala SealDoc? Zvolte místo toho SealDoc Numbering Series.
  • Invoice Date: {{ $json.invoiceDate }}. Due Date: {{ $json.dueDate }}.
  • Currency: EUR.
  • VAT Rate: 0.21. Sazba se zadává jako desetinný zlomek, takže 21 % je 0.21. VAT Category ponechte na “derive from the rate” a VAT Label nechte prázdné: u standardní sazby napíše SealDoc popisek DPH sám.
  • Seller: vaše firma s poli Name, VAT Number, Address, Postal Code, City a Country (dvoupísmenný kód).
  • Buyer Source: Buyer Details. Buyer: namapujte každé pole z triggeru, například {{ $json.buyer.name }} a {{ $json.buyer.postalCode }}. Zákazníky, které máte uložené v SealDoc, můžete použít přímo přes Buyer Profile.
  • Lines: přidejte řádek s Description {{ $json.line.description }}, Quantity {{ $json.line.quantity }}, Unit Hour a Unit Price (Excl. VAT) {{ $json.line.unitPriceExclVat }}.
  • Profile: Basic (Factur-X 1.0). Uzel nabízí také XRechnung DE, který vyžaduje Buyer Reference (Leitweg-ID) a kontakt prodávajícího, a Peppol BIS 3.0 (UBL 2.1), který vyžaduje identifikátory koncových bodů Peppol obou stran.
  • RFC 3161 Timestamp: zapnuto, což je výchozí nastavení.

Vyberte své přihlašovací údaje SealDoc API a spusťte uzel. Odpověď vypadá takto:

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

completed znamená, že faktura je sestavená, zvalidovaná podle EN 16931 a zapečetěná. Není co pollovat. Pokud by odpověď někdy místo toho uváděla queued nebo processing, uzel SealDoc · Job · Get se stejným jobId vám řekne, kdy je hotovo.

Krok 3: načtěte XML

Přidejte druhý uzel SealDoc: Resource Invoice, Operation Get XML, Job ID {{ $('Generate invoice').item.json.jobId }}. Uzel vrátí XML e-faktury jako binární soubor v poli data: factur-x.xml pro profil Basic, xrechnung.xml pro XRechnung a peppol-ubl.xml pro Peppol BIS.

Krok 4: stáhněte PDF/A-3

Přidejte uzel HTTP Request:

  • Method: GET
  • URL: https://api.sealdoc.eu/api/download/{{ $('Generate invoice').item.json.jobId }}
  • Authentication: Generic Credential Type, pak Header Auth, s názvem X-Api-Key a vaším API klíčem jako hodnotou.
  • Response Format: File.

Výsledkem je zapečetěné PDF/A-3 s vloženým XML.

Krok 5: uložte výsledek

Přidejte uzel úložiště, který odpovídá vašemu stacku: Google Drive, Dropbox, bucket kompatibilní s S3, SFTP na váš vlastní server nebo Write Binary File přímo na hostiteli n8n.

Od plánu Starter má každý job také svůj Legal Evidence Pack: GET /api/jobs/{id}/evidence-pack se stejnou hlavičkou X-Api-Key. SealDoc ho sestaví hned po dokončení jobu; pokud se zeptáte v prvních okamžicích, API odpoví 409 s hlavičkou Retry-After, takže stačí krátký uzel Wait před požadavkem.

Když se něco pokazí

Chyby se vracejí okamžitě, jako odpověď obsahující code:

  • 400 pro neplatný vstup, například seller_required, currency_required nebo invalid_vat_rate.
  • 402 plan_feature_required, když váš plán danou funkci nezahrnuje.
  • 403 seller_vat_mismatch, když se DIČ prodávajícího liší od DIČ vašeho pracovního prostoru.
  • 409 quota_reached, když jste vyčerpali měsíční limit.
  • 422 einvoice_invalid, když faktura neprojde validací.

Ve výchozím nastavení uzel SealDoc při chybě workflow zastaví. Nastavte v uzlu volbu On Error na pokračování s chybovým výstupem a ten nasměrujte do Slacku nebo e-mailu, aby člověk viděl, co je potřeba opravit.

Co získáte

PDF/A-3, které libovolný prohlížeč PDF otevře jako čitelnou fakturu, s vloženým XML pro účetní software, který importuje Factur-X nebo ZUGFeRD. Token časového razítka RFC 3161 je uložený u jobu a lze ho stáhnout samostatně (GET /api/jobs/{id}/timestamp). Přetáhněte PDF do našeho bezplatného Validatoru a sami uvidíte verdikt i každé zjištění.

Další kroky

  • Validace existujících faktur: SealDoc · Validator · Check zvaliduje soubor Factur-X nebo ZUGFeRD, který už máte, aniž by cokoli generoval.
  • Renderování dalších dokumentů: SealDoc · Document · Generate převede Markdown nebo HTML na zapečetěné PDF/A-3 jediným voláním.
  • Zpětné načtení vystavených faktur: SealDoc · Invoice · Get Summary vrátí číslo faktury, profil, jazyk a součty DPH vygenerované faktury.

Na kompletní referenci API s OpenAPI specifikací a příklady curl vede odkaz z naší stránky pro vývojáře.

Ověřte vlastní fakturu, bez účtu →
← Zpět na všechny články