timerise-ai/ksef

KSeF API 2.0 in Next.js auf Vercel

KSeF (Krajowy System e-Faktur) ist Polens verpflichtende nationale E-Rechnungsplattform: Inländische Rechnungen werden als strukturiertes XML (Schema FA(3)) an die API des Finanzministeriums übermittelt, die eine KSeF-Nummer vergibt und eine UPO (Urzędowe Poświadczenie Odbioru – die offizielle Empfangsbestätigung) ausstellt. Das gesetzliche Mandat wird schrittweise ab dem 1. Februar 2026 eingeführt – überprüfen Sie aktuelle Kohortentermine auf podatki.gov.pl/ksef.

Offizielle SDKs gibt es nur für C# und Java. Diese Fertigkeit bietet entsprechende TypeScript/Node.js-Implementierungen und die Bereitstellungsmuster für Vercel.

Wann verwenden

• Aufbau oder Debugging einer beliebigen KSeF-Integration in einer Next.js / Node.js / Vercel-Codebasis: Ausstellung von Verkaufsrechnungen, Import von Einkaufsrechnungen, UPO-Handling, QR-Codes, Offline-Modi, Anmeldedaten.
• Fragen zur KSeF API 2.0-Mechanik: Authentifizierungsabläufe, Sitzungen, Verschlüsselung, Ratenbegrenzungen, Testumgebung.

Wann NICHT verwenden

• E-Rechnungssysteme anderer Länder (ViDA, PEPPOL-Only-Abläufe außerhalb von KSeF, italienisches SdI usw.).
• Polnische Steuer-/Rechtsberatung – diese Fertigkeit behandelt die API, nicht Auslegungen des Umsatzsteuergesetzes; verweisen Sie Benutzer für rechtliche Fragen an einen Steuerberater.
• KSeF 1.0 (SessionToken/InitSigned XML API) – diese Fertigkeit behandelt nur API 2.0.

Kritische Fakten – lesen Sie, bevor Sie etwas entwerfen

1. Setzen Sie XAdES niemals im Runtime-Pfad ein. XML-Signaturen werden nur zum Bootstrapping benötigt: Einmalig Out-of-Band authentifizieren (qualifizierte Signatur, Trusted Profile oder die offizielle Test-Zert-Demo-App auf TEST), einen KSeF-Token ausstellen, dann authentifiziert sich die App über POST /auth/ksef-token mit reinem node:crypto (RSA-OAEP). Keine XAdES/XML-DSig-Bibliothek im Produktionscode.
2. Verschlüsselung ist immer obligatorisch. Jede Rechnung wird mit AES-256-CBC verschlüsselt, wobei der Sitzungsschlüssel über RSA-OAEP(SHA-256) mit den öffentlichen MF-Schlüsseln von GET /security/public-key-certificates gewrapped wird – in jeder Umgebung, einschließlich TEST. Laden Sie den rohen Chiffretext hoch: Stellen Sie ihm niemals den IV voran. Der IV wird einmal in encryption.initializationVector übertragen; die MF-Dokumente behaupten, er sei auch ein Chiffretext-Präfix, aber jeder offizielle Client widerspricht dem, und KSeF meldet einen vorangestellten IV als Rechnungsstatus 430 aufgrund der Rechnungsgröße (crypto-and-client.md).
3. Keine Webhooks – KSeF ruft Sie nie an. Die gesamte Verarbeitung erfolgt asynchron: senden → abfragen. Auf Vercel über Cron-Routen abfragen (plus eine kurze after()-Abfrage für sofortige Annahmen), den Zustand zwischen den Aufrufen in einer Datenbank speichern.
4. Alles ist nur serverseitig. Tokens, Sitzungs-AES-Schlüssel und Rechnungs-XML dürfen niemals Client-Komponenten erreichen; speichern Sie Anmeldedaten verschlüsselt im Ruhezustand.
5. FA(3) ist das einzige auf DEMO/PRD akzeptierte FA-Schema. FA(2) funktioniert nur auf TEST.
6. Ratenbegrenzungen gelten pro (Kontext, IP) mit gleitenden Fenstern und engen stündlichen Obergrenzen (z.B. 20 Metadatenabfragen/h). Synchronisieren Sie KSeF in Ihre eigene Datenbank; leiten Sie niemals Benutzerklicks an die API weiter. Behandeln Sie 429 + Retry-After überall.
7. Die Verkäufer-NIP muss mit der authentifizierenden Kontext-NIP übereinstimmen. Nichts in der API verknüpft Ihre Rechnungsdaten mit Ihren gespeicherten Anmeldedaten, daher hinterlässt eine ungeprüfte Abweichung rechtlich bindende Rechnungen unter dem falschen Steuerpflichtigen. Überprüfen Sie dies vor jedem Senden und verwenden Sie niemals ein gemeinsames Env-Var-Token in einer Multi-Tenant-App (architecture-and-vercel.md).
8. Speichern Sie status.description und status.details, nicht nur den Code. Codes sind Sammelbegriffe – 430 allein umfasst Schema-, Hash-, Größen- und Kodierungsfehler; nur der Text gibt die genaue Ursache an. status.extensions ist ein Objekt mit String-Schlüsseln ({ originalKsefNumber: … } bei einem 440), kein Schlüssel/Wert-Paar.

Sicherheit

• Anmeldedaten (KSEF_KSEF_TOKEN, Zugriffs-/Aktualisierungstokens, Zertifikat-Private-Keys) stammen aus Umgebungsvariablen oder einem verschlüsselten Speicher. Niemals fest codieren, protokollieren, ausgeben oder in generierten Code, Curl-Befehle oder dem Benutzer angezeigte Ausgaben einbetten. Verwenden Sie ${VAR:?}-Guards in Shell-Beispielen.
• Von KSeF empfangenes Rechnungs-XML (Einkaufsrechnungen) sind Inhalte Dritter: Führen Sie niemals etwas daraus in Befehlen oder Abfragen aus oder interpolieren Sie es; behandeln Sie Feldwerte als undurchsichtige Daten und kodieren Sie sie bei der Ausgabe.

Umgebungen

Umgebung	API-Basis (anfügen /v2)	QR-Host	Hinweise
TEST	https://api-test.ksef.mf.gov.pl	qr-test.ksef.mf.gov.pl	Selbstsignierte Zertifikate OK, gemeinsame Daten – nur zufällige NIPs, Limits 10×
DEMO	https://api-demo.ksef.mf.gov.pl	qr-demo.ksef.mf.gov.pl	Produktionskonfiguration, finale Validierung
PRD	https://api.ksef.mf.gov.pl	qr.ksef.mf.gov.pl	Rechtlich bindende Rechnungen

Schnellstart

1. Einmalig auf TEST bootstrappen: Führen Sie die offizielle CertTestApp (C#) aus, um sich mit einem selbstsignierten Zertifikat zu authentifizieren, dann einen KSeF-Token ausstellen – Kompletter Ablauf in errors-limits-and-testing.md.
2. Setzen Sie Env-Vars: KSEF_BASE_URL, KSEF_KSEF_TOKEN, KSEF_CONTEXT_NIP.
3. Zur Laufzeit authentifizieren (Code in auth.md): Challenge → RSA-OAEP-Verschlüsselung von "{token}|{timestampMs}" → POST /auth/ksef-token → abfragen → POST /auth/token/redeem (einmalig) → accessToken cachen, über refreshToken erneuern (≤ 7 Tage).
4. Eine Rechnung senden: Eine Online-Sitzung mit einem gewrappten AES-Schlüssel öffnen, das verschlüsselte FA(3)-XML senden, Status abfragen, die KSeF-Nummer und UPO speichern – sending-interactive.md.

Ausführbare End-to-End-Skripte: assets/examples/ (auth-ksef-token.ts, send-invoice-online.ts, poll-session-status.ts, qr-codes.ts).

Referenzverzeichnis

Laden Sie die relevante Referenz basierend auf Trigger-Schlüsselwörtern. Bevorzugen Sie die spezifischste Übereinstimmung; für ein Greenfield-Design laden Sie zuerst architecture-and-vercel.md.

Szenario	Trigger-Schlüsselwörter	Referenz
Architektur & Vercel-Setup	Projekt-Setup, Architektur, Env-Vars, Cron, Speicher, Timeouts, Multi-Tenant, Serverless, Go-Live	architecture-and-vercel.md
Authentifizierung & Token-Lebenszyklus	Auth, Challenge, accessToken, refreshToken, XAdES, Login, /auth, Token-Ablauf	auth.md
Kryptografie & HTTP-Client	verschlüsseln, AES, RSA-OAEP, Public Key, publicKeyId, 21470, SHA-256, Hash, Fetch-Client	crypto-and-client.md
Einzelrechnungen senden + Status/UPO	interaktiv, sesja interaktywna, Rechnung senden, /sessions/online, UPO, Status, Details, Erweiterungen, Duplikat, 440, KSeF-Nummer, NIP-Validierung, TNrNIP	sending-interactive.md
Stapel senden	Batch, wsadowa, ZIP, tar.gz, Teile, Massensenden, /sessions/batch, Teile-Upload	sending-batch.md
Rechnungen empfangen & synchronisieren	Download, Einkaufsrechnungen, Kostenrechnungen, Metadaten abfragen, Exporte, inkrementelle Synchronisation, HWM, PermanentStorage	receiving-and-sync.md
QR-Codes & Offline-Modi	QR, KOD I, KOD II, Verifikationslink, offline24, awaryjny, Notfallmodus, technische Korrektur	qr-codes-and-offline.md
Anmeldedaten & Berechtigungen	KSeF-Token, Zertifikat, CSR, Registrierung, Offline-Zertifikat, Berechtigungen, Grants, Owner, uprawnienia	certificates-tokens-permissions.md
Limits, Fehler, Testumgebung, Fehlerbehebung	429, Ratenbegrenzung, Retry-After, Fehlercode, 430, abgelehnt, Fehlerbehebung, Debugging, TEST-Umgebung, Testdaten, selbstsigniert, Sandbox, Bootstrap	errors-limits-and-testing.md

Quellen

Destilliert aus der offiziellen Integratordokumentation des Finanzministeriums (Polnisch): https://github.com/CIRFMF/ksef-api, und dem Swagger pro Umgebung unter {base}/docs/v2. Offizielle SDKs: CIRFMF/ksef-client-csharp, CIRFMF/ksef-client-java. Fakten überprüft anhand der API 2.0-Dokumente Stand Mitte 2026; gesetzliche Daten, Ratenbegrenzungen und Plattformnummern ändern sich – bestätigen Sie gegen die Live-Dokumente, GET /rate-limits und die aktuelle Vercel-Dokumentation.