KSeF

v1.0.0

Last updated Mar 7, 2026

n8n community node for Poland's KSeF (Krajowy System e-Faktur) e-invoicing API — query, download, and manage invoices with token or certificate authentication

3 Weekly Downloads

71 Monthly Downloads

View on NPM GitHub Repository

Included Nodes

KSeF

Description

KSeF logo

n8n-nodes-ksef

The open-source n8n community node for Poland’s KSeF e-invoicing system

Authenticate with token or qualified certificate · Query invoice metadata · Download invoice XML · Manage sessions

—

✨ What Is This?

KSeF (Krajowy System e-Faktur) is Poland’s mandatory National e-Invoice System operated by the Ministry of Finance. This node lets you connect your n8n workflows directly to the KSeF API — no paid plugins, no license keys, fully open-source.

What can you do with it?

| | Operation | Description |
|—|—|—|
| 🔍 | Query Metadata | Search invoices by date range, role, and filters with automatic pagination |
| 📄 | Download Invoice | Fetch invoice XML by KSeF number, with optional JSON parsing |
| 🔐 | Start Session | Authenticate and verify your credentials |
| 📊 | Check Status | List all active sessions and their details |

—

🚀 Quick Start

Step 1 — Install the Node

In your n8n instance, go to Settings → Community Nodes → Install and enter:

n8n-nodes-ksef

Step 2 — Generate a KSeF Token

1. Go to the KSeF Taxpayer Portal (MCU)
2. Log in with your qualified certificate or Profil Zaufany
3. Navigate to Tokeny → Generuj nowy token
4. Select the permissions for the token:
– ✅ Odczyt faktur (Invoice Read) — required for querying and downloading
– ❌ Do not grant write permissions unless you need them — principle of least privilege
5. Copy the generated token (format: YYYYMMDD-XX-XXXXXXXXXX-XXXXXXXXXX-XX|nip-XXXXXXXXXX|hash)

Step 3 — Configure Credentials in n8n

1. In your n8n workflow, add a KSeF node
2. Click Create New Credential and fill in:

3. Click Test Credential — you should see a ✅ success message

Step 4 — Build Your First Workflow

Here’s a minimal 3-node workflow to fetch and process your invoices:

┌─────────────┐     ┌──────────────────────┐     ┌──────────────────────┐
│   Manual     │────▶│  KSeF: Query         │────▶│  KSeF: Download      │
│   Trigger    │     │  Invoice Metadata    │     │  Invoice             │
└─────────────┘     └──────────────────────┘     └──────────────────────┘

Node 1 — Manual Trigger (or Schedule Trigger for daily syncs)

Node 2 — KSeF: Query Invoice Metadata

Resource: Invoice
Operation: Query Metadata
Subject Type: Buyer (invoices TO you) or Seller (invoices FROM you)
Date From: {{ $now.minus(30, 'days').toISO() }} (last 30 days)
Date To: (leave empty for “now”)
Return All: ✅ Yes

Node 3 — KSeF: Download Invoice

Resource: Invoice
Operation: Download
KSeF Number: {{ $json.ksefNumber }} (auto-mapped from query results)
Parse XML: ✅ Yes (get structured JSON alongside raw XML)

Step 5 — Save to Your Favourite Destination

Chain additional nodes to store the results wherever you need:

—

📋 Operations Reference

Invoice → Query Metadata

Search for invoices within a date range. Returns flattened metadata for easy processing.

Output fields: ksefNumber, invoiceNumber, issueDate, invoicingDate, permanentStorageDate, sellerNip, sellerName, buyerNip, buyerName, netAmount, grossAmount, vatAmount, currency, invoiceType, and more.

Invoice → Download

Download the raw XML of an invoice, with optional parsing to JSON.

Output fields: ksefNumber, xml (always), parsed (when Parse XML is enabled).

Session → Start

Explicitly authenticate and return session info. All operations authenticate automatically — use this to verify your setup or warm up a session.

Session → Check Status

List active KSeF sessions for your NIP, including auth method, start date, and token redemption status.

—

🔐 Authentication

Token Authentication

The simplest method. Generate a token in the KSeF portal and paste it into the credentials.

> Note: n8n’s credential storage may transform pipe characters (|) in tokens. This node handles that automatically — just paste your token as-is.

Certificate Authentication (Qualified Seal / Signature)

For organizations using qualified electronic seals or signatures:

The node builds and signs an XAdES-BES (Basic Electronic Signature) XML request with your certificate — the same standard used by Poland’s qualified trust services.

How the Auth Flow Works Under the Hood

Your n8n workflow
       │
       ▼
   ┌───────────────┐     ┌───────────────┐     ┌───────────────┐
   │ Get Challenge  │────▶│ Encrypt Token │────▶│ Submit Auth   │
   │ POST /auth/    │     │ or Sign XML   │     │ Request       │
   │   challenge    │     │ (local crypto)│     │               │
   └───────────────┘     └───────────────┘     └───────────────┘
                                                       │
       ┌───────────────────────────────────────────────┘
       ▼
   ┌───────────────┐     ┌───────────────┐
   │ Poll Status   │────▶│ Redeem Tokens │──── access + refresh tokens
   │ (auto-retry)  │     │               │     cached & auto-refreshed
   └───────────────┘     └───────────────┘

Sessions are cached and tokens are automatically refreshed — subsequent operations in the same workflow execution reuse the existing session.

—

🔧 Environments

—

🛡️ Error Handling

The node provides human-readable error messages for all KSeF API error codes:

| Code | Meaning |
|——|———|
| 400 | Bad request — details extracted from KSeF response |
| 401 | Session expired — automatically re-authenticates on next run |
| 403 | Insufficient permissions — actionable suggestions included |
| 415 | No permissions assigned to the token |
| 429 | Rate limited — retry after the indicated delay |
| 450 | Token authentication failed |
| 460 | Certificate error |

All operations support n8n’s Continue On Fail mode for resilient workflows.

—

📦 Compatibility

—

📜 License

MIT — use it freely in personal and commercial projects.

—

Made with ❤️ by Greg Brzezinka @ Prosit AS
Need help? Reach out to me!