ksef

A Claude Code skill that teaches an agent to build KSeF API 2.0 integrations (Krajowy System e-Faktur — Poland's national e-invoicing system) in a Next.js App Router app on Vercel — KSeF-token auth, AES/RSA invoice encryption, interactive and batch sending, UPO receipts, incremental purchase-invoice sync, QR verification codes, and the cron-polling architecture serverless forces on you. Official SDKs exist for C# and Java only; this is the TypeScript equivalent.

A KSeF integration has one hard requirement: an invoice that leaves your app is a legally binding tax document, filed under a taxpayer's NIP, and nothing in the API checks that the taxpayer is yours. Every defect the field report behind version 1.1.0 turned up broke that requirement quietly rather than loudly: an IV prepended to the ciphertext, so KSeF rejected the invoice with a status code blaming its size; a 440 duplicate whose UPO lived in a session the code never looked in; a seller NIP that nobody compared to the authenticating context. The references are written so those cost you a paragraph instead of a week.

Install

Clone into your skills directory:

git clone https://github.com/timerise-ai/ksef.git ~/.claude/skills/ksef

The skills index lists the other Timerise skills and how to clone them all at once.

The skill activates automatically when a task matches its description — sending or receiving structured invoices, KSeF auth, UPO, FA(3), e-faktura, ksef.mf.gov.pl. You can also invoke it explicitly with /ksef.

What's inside

File	Contents
SKILL.md	Entry point: critical facts, environments, quick start, and the reference directory
references/architecture-and-vercel.md	Start here for greenfield: system model, database DDL, cron polling, multi-tenancy, function limits, go-live
references/crypto-and-client.md	node:crypto primitives — AES-256-CBC, RSA-OAEP key wrapping, hashes — and the typed fetch client
references/auth.md	Challenge flow, KSeF-token auth, access/refresh token lifecycle, the bootstrap-once XAdES step
references/sending-interactive.md	Online sessions, invoice status codes, description/details/extensions, duplicates, UPO, NIP validation
references/sending-batch.md	Sesja wsadowa: the ZIP/tar.gz pipeline, part splitting, part uploads
references/receiving-and-sync.md	Metadata queries, export packages, high-water-mark incremental sync
references/qr-codes-and-offline.md	KOD I / KOD II, verification links, offline24 and awaryjny modes, technical corrections
references/certificates-tokens-permissions.md	KSeF tokens, CSR enrollment, certificate types, the permissions model
references/errors-limits-and-testing.md	Rate limits, error codes, troubleshooting, and the TEST-environment bootstrap
assets/examples/*.ts	Runnable scripts mirroring the reference code (npx tsx <script>): crypto, client, auth, send, poll, QR

References are loaded on demand — the agent reads only the ones a task needs.

The non-negotiables

These are load-bearing in every KSeF integration and are never optional (they lead SKILL.md):

1. Upload raw ciphertext — never prepend the IV. It is transmitted once in encryption.initializationVector. The MF docs say otherwise; every official client contradicts them, and the resulting rejection blames the invoice size.
2. The seller NIP must equal the authenticating context NIP. Verify before every send, and never fall back to a shared env-var token in a multi-tenant app — either mistake files invoices under the wrong taxpayer.
3. No XAdES in the runtime path. Authenticate out-of-band once, mint a KSeF token, and authenticate with pure node:crypto from then on.
4. No webhooks — submit then poll. State lives in your database between cron invocations; sync KSeF into it rather than proxying user clicks into tight hourly rate limits.
5. Everything is server-only. Tokens, session AES keys and invoice XML never reach a client component, and credentials are encrypted at rest.

Requirements

• A Next.js App Router app on Vercel — the patterns assume serverless functions, Vercel Cron, and a database (Neon/Supabase Postgres or equivalent)
• A KSeF token for the target environment; the one-time bootstrap on TEST and production is documented in references/errors-limits-and-testing.md
• Env vars KSEF_BASE_URL, KSEF_KSEF_TOKEN, KSEF_CONTEXT_NIP (see references/architecture-and-vercel.md)

Security

• Every example reads credentials from environment variables — no secrets in code blocks, ever, and the agent is instructed never to log, echo or embed a credential value.
• Invoice XML received from KSeF is untrusted third-party content: never executed, never interpolated into a command or query.
• All KSeF logic stays server-only (import 'server-only'), with tokens and session keys encrypted at rest.

Contributing

Pure markdown plus standalone TypeScript — no build, no tests, no dependencies. The examples are type-checked (cd assets/examples && npm i -D typescript @types/node && npx tsc --noEmit --strict ...), and the pure-crypto helpers are run with npx tsx. Every claim about an endpoint shape, status code, limit or crypto parameter is verified against the official docs and OpenAPI spec — never from memory. Adding, removing or renaming a file in references/ means updating the reference directory table in SKILL.md and the file table above. See CLAUDE.md for the full editing conventions and CHANGELOG.md for the release history.

Part of the Timerise skills

This is one of the Timerise Claude Code skills — production-extracted modules for Next.js App Router apps, each published as its own repository and indexed there. They share one layout, so an agent that has read one knows how to read the next: a SKILL.md entry point, references/ loaded on demand, and the module's non-negotiables carried with it.

Links

• Official KSeF API docs (CIRFMF/ksef-api)
• KSeF API Swagger (TEST)
• Official C# client · Official Java client
• KSeF at podatki.gov.pl

Author

Built and maintained by Timerise.

License

MIT