ksefuj

Open source toolkit for Polish KSeF FA(3) e-invoicing.

• 100% free forever — no limits, no signup, no hidden costs
• Privacy-first — everything runs locally in your browser
• Official compliance — full XSD validation against Ministry of Finance schemas
• Multilingual — Polish, English, Ukrainian

🌐 ksefuj.to — free online validator 📦 @ksefuj/validator — npm package + CLI

What is KSeF?

KSeF (Krajowy System e-Faktur) is Poland's mandatory e-invoicing system. Starting April 1, 2026 (February 1, 2026 for large companies), all VAT taxpayers must issue structured XML invoices through KSeF using the FA(3) schema.

Features

Three-Layer Validation

• XSD Schema Validation — full compliance with official Ministry of Finance schemas
• MF Semantic Rules — catches errors that XSD can't express, per the official FA(3) information sheet
• Extra checks — tax calculation math, NBP currency rates, IBAN format: things KSeF won't catch

Privacy & Performance

• 100% client-side — your invoice data never leaves your browser
• Offline capable — bundled schemas, no network requests needed
• Fast validation — WebAssembly-powered, optimized for multiple validations

Developer Tools

• npm package — @ksefuj/validator with TypeScript support
• CLI tool — npx @ksefuj/validator invoice.xml
• Claude Skills — ready-made skills for generating e-invoices in Claude Projects
• Minimal dependencies — only libxml2-wasm for XSD validation, TypeScript, ESM modules

Quick Start

Web

Visit ksefuj.to, drop your XML file, done.

CLI

npx @ksefuj/validator invoice.xml

As a dependency

pnpm add @ksefuj/validator
# or npm install @ksefuj/validator
# or yarn add @ksefuj/validator

import { validate } from "@ksefuj/validator";

// Full validation with XSD + semantic rules (default)
const result = await validate(xmlString);

// With options
const result = await validate(xmlString, {
  locale: "en", // 'pl' (default) | 'en' | 'uk'
  enableXsdValidation: true, // default: true
  enableSemanticValidation: true, // default: true
});

if (!result.valid) {
  // Check XSD errors
  const xsdErrors = result.errors.filter((e) => e.source === "xsd");

  // Check semantic errors
  const semanticErrors = result.errors.filter((e) => e.source === "semantic");

  for (const error of result.errors) {
    console.error(`${error.source}: ${error.message}`, error.path);
  }
}

Repository Structure

ksefuj/
├── packages/
│   └── validator/       ← @ksefuj/validator (npm + CLI)
│       └── src/schemas/ ← Bundled XSD schemas from Ministry of Finance
├── apps/
│   └── web/             ← ksefuj.to (Next.js app)
├── scripts/
│   └── update-schemas.ts ← Schema maintenance tool
└── skills/
    └── ksef-fa3/        ← Claude skill for invoice generation

What the Validator Checks

XSD Schema Validation

Full validation against official Ministry of Finance FA(3) XSD schemas:

• libxml2-wasm — WebAssembly-powered validation in the browser
• Bundled schemas — no network requests, CORS-free, offline capable
• Official compliance — uses exact schemas from crd.gov.pl
• Detailed error reporting — line numbers, element paths, specific violations

Semantic Business Rules

44 comprehensive validation rules based on the official FA(3) information sheet from the Ministry of Finance:

Rule Categories

1. Podmiot Rules (8 rules) — Entity validation, JST/GV requirements, NIP placement
2. Fa Core Rules (5 rules) — P_15 requirement, mutual exclusions, currency handling
3. Adnotacje Rules (11 rules) — All mandatory fields, selection logic for exemptions/margin procedures
4. FaWiersz Rules (4 rules) — Tax rate validation, GTU format, decimal precision
5. Corrective Invoice Rules (2 rules) — KSeF number consistency, reverse charge validation
6. Payment & Transaction Rules (8 rules) — Payment dates, bank accounts, currency pairs, NBP rate validation
7. Format Rules (2 rules) — Number formatting, separator validation
8. Additional Business Logic Rules (4 rules) — Tax calculations, bank account format, line number uniqueness, negative quantities

Common Issues Caught

• Missing mandatory Adnotacje fields (P_16, P_17, P_18, P_18A, Zwolnienie, etc.)
• Incorrect JST/GV setup requiring specific Podmiot3 roles
• Polish NIP in wrong field (should be in NIP field, not NrVatUE)
• Wrong tax rates for foreign buyers ('np I'/'np II' vs 'oo')
• GTU format errors (<GTU>GTU_12</GTU> not <GTU_12>1</GTU_12>)
• Decimal precision violations (amounts >2, prices >8, quantities >6 decimals)
• Selection logic violations in Zwolnienie, NoweSrodkiTransportu, PMarzy
• Currency inconsistencies (foreign currency needs PLN conversions)
• Number formatting issues (thousand separators, wrong decimal separator)
• Tax calculation errors (incorrect VAT amounts, wrong totals)
• Invalid Polish bank account format (IBAN must be 28 chars: PL + 26 digits; NRB must be 26 digits)
• Duplicate invoice line numbers
• Negative quantities in non-corrective invoices

Claude Skills

The skills/ directory contains skills for Claude Projects:

• ksef-fa3 — generates FA(3) XML invoices from input data (PDF, text, form)

Installation: download the .skill file from Releases and add to your Claude Project.

Development

Requires Node.js 18+ and pnpm:

git clone https://github.com/ksefuj/ksefuj.git
cd ksefuj
pnpm install
pnpm dev              # runs web app on localhost:3000
pnpm build            # builds all packages
pnpm test             # runs tests in all packages
pnpm update-schemas   # updates XSD schemas from government sources

Schema Maintenance

The validator uses bundled XSD schemas to avoid CORS issues. To update them:

pnpm update-schemas

This downloads the latest schemas from crd.gov.pl, compares with existing files, and updates the bundle if changes are detected. Run this:

• Monthly to check for updates
• Before releases
• After Ministry of Finance announces schema changes

Roadmap

Phase 1: Validator ✅

• Full XSD schema validation (libxml2-wasm)
• Semantic business rules engine
• Bundled schemas (CORS-free, offline capable)
• Visual validation badges (XSD + semantic)
• CLI tool
• Web app with drag & drop
• npm package
• Schema update tool
• i18n setup (PL + EN + UK)
• Deploy to production

Phase 1.5: Launch Sprint (in progress)

• Validator UI improvements (multi-file upload, better error output)
• Human-readable error messages with fix instructions
• Landing page with trust signals and feature sections
• MDX content pipeline (docs, guides, blog)
• FAQ page (full MDX content, PL/EN/UK, JSON-LD FAQPage schema)
• Blog (first article live: KSeF od 1 kwietnia 2026)
• Sitemap, OG images, hreflang, Twitter cards across all content
• Behavioral analytics
• RSS feed
• Global validation counter (Vercel KV)
• Publish @ksefuj/validator to npm registry

Phase 2: Preview

• XML → HTML invoice visualization
• Autofix suggestions (one-click error fixes)
• PDF export (client-side via browser print / jsPDF)
• QR code generation (required for invoices sent outside KSeF)

Phase 3: Generator

• Form-based XML generation
• Auto NBP exchange rates
• Auto NIP lookup (GUS/VIES)

License

Apache 2.0

A permissive open source license that allows commercial use, modification, and distribution. Requires preservation of copyright and license notices.