n8n-nodes-ksef

n8n community node for KSeF — Krajowy System e-Faktur, the Polish national e-invoicing system. Safely ingest incoming invoices, fetch, search, and parse FA-3 invoices directly from your n8n workflows.

Built on top of ksef-client-ts. Outgoing FA-3 invoices are validated before sending, while incoming invoices are downloaded in the buyer role and their SHA-256 hash is verified before any Drive/PDF artifacts are produced.

Read-only by default. The credential setting that permits invoice issuing is disabled by default, and the node opens on Get Incoming. Enable issuing only in a dedicated credential after reviewing the workflow.

n8n is a fair-code licensed workflow automation platform.

Table of contents

• Installation
• Credentials
• Operations
• How validation works
• Compatibility
• Limitations & roadmap
• Development
• License

Installation

1. Open your n8n instance.
2. Go to Settings → Community Nodes.
3. Click Install, paste @app4you/n8n-nodes-ksef, and confirm.

Or via npm if you self-host:

npm install @app4you/n8n-nodes-ksef

See the official community node installation guide for details.

Credentials

The node uses one credential type — KSeF API — supporting three authentication methods. You always need a NIP and an environment.

| Field | Required | Description | | --- | --- | --- | | NIP | yes | NIP of the entity (10 digits, with checksum). Whitespace and dashes are stripped automatically. | | Environment | yes | Test (api-test.ksef.mf.gov.pl), Demo (api-demo.ksef.mf.gov.pl), or Production (api.ksef.mf.gov.pl). | | Auth method | yes | KSeF Token, Certyfikat .p12 (Base64), or Certyfikat PEM (Cert + Klucz). | | Timeout (ms) | optional | 0 = SDK default (~30s). |

Auth method: KSeF Token

Long-lived token generated in the official KSeF portal. Easiest for personal / single-NIP setups.

| Field | Description | | --- | --- | | KSeF Token | Token string from the MF portal. |

Auth method: Certyfikat .p12 (Base64)

PKCS#12 bundle (cert + private key). Useful if you have a qualified signature.

| Field | Description | | --- | --- | | Plik .p12 (Base64) | Base64-encoded .p12 bundle. On macOS: base64 cert.p12 \| pbcopy. | | Hasło .p12 | Password protecting the bundle. |

Auth method: Certyfikat PEM (Cert + Klucz)

Separate certificate and private key in PEM format.

| Field | Description | | --- | --- | | Certyfikat PEM | Full PEM cert (-----BEGIN CERTIFICATE-----...). | | Klucz Prywatny PEM | Private key PEM (-----BEGIN PRIVATE KEY----- or -----BEGIN ENCRYPTED PRIVATE KEY-----). | | Hasło Klucza | Required only if the key is encrypted. |

Note: credential fields are validated locally (including NIP checksum and token/base64/PEM shape), but remote KSeF authentication is verified only by the first real operation.

Operations

One resource — Invoice — with five operations.

Get Incoming

Safely ingest incoming purchase invoices for reconciliation and archiving. This operation hard-codes the two safety-critical KSeF filters so a workflow cannot accidentally switch them:

• subject type is always Subject2 (the company is the buyer),
• date type is always PermanentStorage, which is suitable for incremental polling.

For each result the node downloads the source XML, verifies its SHA-256 hash against KSeF metadata, and returns one n8n item containing:

• the complete KSeF metadata and source XML,
• a deterministic KSeF-number idempotency key,
• safe Drive file names for the PDF and XML,
• the target YYYY-MM folder,
• escaped, print-ready HTML with parties, invoice identifiers, line items, and totals,
• Unicode-safe plain text for a credential-free Google Docs → PDF export path.

KSeF does not return a PDF. Use either the HTML with an HTML-to-PDF node or the plain-text representation with Google Docs export. The XML remains the source document in both cases.

Create

Issue a new FA-3 invoice in KSeF and return the UPO (urzędowe poświadczenie odbioru).

Two input modes:

| Source | Description | | --- | --- | | Interaktywny formularz | Structured form auto-generated from the FA-3 XSD schema. Required-by-schema fields are marked, dropdowns come from official enumerations (currency codes, country codes, VAT rates, document types). Sums (P_13_, P_14_, P_15) are computed for you from line items. Validated against FA-3 Zod schema before XML build. | | Gotowy XML | Paste your own XML. Advanced bypass — the node still runs SDK schema validation before sending. |

Returns: parsed UPO (KSeF reference number, timestamps, signed acknowledgement).

Get

Fetch a single invoice by KSeF number.

| Field | Description | | --- | --- | | KSeF Number | Format: NIP-YYYYMMDD-XXXXXXXXXXXX (12 hex chars). Validated client-side via the SDK. |

Returns: xml (raw FA-3 XML), hash (SHA-256), fields (extracted business fields when the XML matches FA-2/FA-3).

Get Many

Search invoices by date range and subject type. Two modes:

| Mode | Use case | | --- | --- | | Metadata (zalecane) | Lightweight metadata page-walk. Hard cap of 10 000 results. Returns invoices[], totalReturned, hasMore, isTruncated. | | Download (XMLs) | Full export package with invoice XMLs (extracted from the KSeS ZIP, base64-encoded per file). Suitable for bulk archives. |

Filters: subjectType (Subject1=sales, Subject2=purchases, Subject3, SubjectAuthorized), dateType (Issue / Invoicing / PermanentStorage), dateFrom, dateTo. Validated client-side: dateFrom <= dateTo, ISO 8601 with offset.

Parse

Validate and extract fields from a raw FA-3 XML you already have. No KSeF call.

| Field | Description | | --- | --- | | XML | FA-3 invoice XML to validate and parse. | | Skip Char Validity | Skip the Level 1a char-validity pre-parse (XML processing instructions and discouraged Unicode). |

Returns: isValid, schemaType, errors[], fields (when extractable).

How validation works

This node validates before any KSeF call, in three layers:

1. Compile-time (TypeScript). The form spec is a mapped type over the Faktura Zod schema generated from the FA-3 XSD. Adding a field that doesn't exist in FA-3 is a TS error. Operation enums (SubjectType, DateType, SortOrder) are as const satisfies against the SDK's literal types — if the SDK adds a new value, TS forces us to extend. Incoming ingestion additionally hard-codes buyer/permanent-storage filters and verifies downloaded XML hashes.
2. Startup (coverage check). When the node loads, the zod2n8n walker asserts that every required-by-Zod field is either present in the spec, omitted explicitly, or filled by compute. Spec drift is caught at boot, not at execute.
3. Runtime (per execution). Every operation pre-flights its input through Zod (Filters.safeParse for Get Many, fakturaForm.parse for Create, isValidKsefNumber for Get, SDK validate() for Parse). KSeF only ever sees data that already passed local validation.

src/schemas/fa3.xsd       (official FA-3 XSD, committed)
        │
        └─► xsd2zod   ──►  src/generated/fa3.ts   (Zod schema with .meta() value-docs)
                                  │
                                  └─►  zod2n8n walker
                                       │
                                       ├──► n8n form properties (auto-generated)
                                       └──► fakturaForm.parse() (pre-flight validator)
                                                  │
                                                  └──► ksef-client-ts → KSeF API

Regenerate the schema from the XSD:

pnpm run generate:schemas

When MF publishes a new FA version, the form, dropdowns, and validators all update from one regen.

Compatibility

• n8n: >=2.0.0 (tested against n8n 2.31.x).
• Node.js: >=18.10 (n8n requirement).
• KSeF API: v2.6.x. FA-3 invoices.
• TypeScript (for development): 5.9+.

Limitations & roadmap

Currently supported:

• Safe incoming-invoice ingestion with hash verification and PDF-ready HTML/plain text.
• Issue, fetch, search, parse FA-3 invoices.
• 3 auth methods (token, .p12, PEM).
• Test / Demo / Production environments.

Not yet supported (planned):

• Cancel session / cancel queued invoice (KSEF.cancel).
• Re-fetch UPO by KSeF number after the original Create output is lost.
• Send-without-close (multiple invoices in one online session).
• Cross-validation: warn when seller NIP in the invoice ≠ session NIP from credentials.
• Telemetry hooks.

Open an issue on GitHub for feature requests.

Development

pnpm install
pnpm dev          # starts n8n with the node hot-reloaded
pnpm build        # tsc + copy icon to dist
pnpm lint         # n8n-node lint
pnpm typecheck    # tsc --noEmit

The node lives in src/Ksef.node.ts, credentials in src/KsefApi.credentials.ts. Per-operation code in src/resources/invoice/actions/. The form auto-generator (zod2n8n) is in src/utils/zod2n8n/ and is intended to ship as a standalone npm package later.

See AUDIT.md for the archived pre-publication audit from 2026-05-08. Its original findings are retained for history and do not describe the current release state.

License

MIT © 2026 Dawid Wiewiórski