Ksef

ksef

A [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills) 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](https://github.com/timerise-ai/skills) 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