timerise-ai/ksef

API KSeF 2.0 dans Next.js sur Vercel

KSeF (Krajowy System e-Faktur) est la plateforme nationale obligatoire de facturation électronique en Pologne : les factures nationales sont soumises sous forme de XML structuré (schéma FA(3)) à l'API du Ministère des Finances, qui attribue un numéro KSeF et délivre un UPO (Urzędowe Poświadczenie Odbioru — l'accusé de réception officiel). L'obligation légale est déployée progressivement à partir du 1er février 2026 — vérifiez les dates de votre cohorte sur podatki.gov.pl/ksef.

Les SDK officiels n'existent que pour C# et Java. Cette compétence fournit des implémentations équivalentes en TypeScript/Node.js et les schémas de déploiement pour Vercel.

Quand l'utiliser

• Pour construire ou déboguer une intégration KSeF dans une base de code Next.js / Node.js / Vercel : émettre des factures de vente, ingérer des factures d'achat, gérer les UPO, les codes QR, les modes hors ligne, les informations d'identification.
• Pour répondre à des questions sur le fonctionnement de l'API KSeF 2.0 : flux d'authentification, sessions, chiffrement, limites de débit, environnement de test.

Quand ne PAS l'utiliser

• Pour d'autres systèmes de facturation électronique nationaux (ViDA, flux PEPPOL hors KSeF, SdI italien, etc.).
• Pour des conseils fiscaux/juridiques polonais — cette compétence couvre l'API, pas l'interprétation de la loi sur la TVA ; orientez les utilisateurs vers un conseiller fiscal pour les questions juridiques.
• Pour KSeF 1.0 (API SessionToken/InitSigned XML) — cette compétence couvre uniquement l'API 2.0.

Faits critiques — à lire avant de concevoir quoi que ce soit

1. Ne mettez jamais XAdES dans le chemin d'exécution. Les signatures XML ne sont nécessaires que pour l'amorçage : authentifiez-vous une fois hors bande (signature qualifiée, Profil de Confiance, ou l'application de démonstration officielle CertTestApp sur TEST), créez un jeton KSeF, puis l'application s'authentifie via POST /auth/ksef-token en utilisant du node:crypto pur (RSA-OAEP). Pas de bibliothèque XAdES/XML-DSig dans le code de production.
2. Le chiffrement est toujours obligatoire. Chaque facture est chiffrée en AES-256-CBC avec une clé de session encapsulée via RSA-OAEP (SHA-256) en utilisant les clés publiques du MF provenant de GET /security/public-key-certificates — dans tous les environnements, y compris TEST. Téléchargez le texte chiffré brut : ne préfixez jamais l'IV. L'IV est transmise une fois dans encryption.initializationVector ; la documentation du MF prétend qu'elle est aussi un préfixe du texte chiffré, mais chaque client officiel contredit cela, et KSeF signale un IV préfixé comme statut de facture 430 sur la taille de la facture (crypto-and-client.md).
3. Pas de webhooks — KSeF ne vous appelle jamais. Tout le traitement est asynchrone : soumission → interrogation. Sur Vercel, interrogez via des routes Cron (plus une interrogation courte after() pour les acceptations immédiates), en persistant l'état dans une base de données entre les invocations.
4. Tout est côté serveur uniquement. Les jetons, les clés AES de session et le XML des factures ne doivent jamais atteindre les composants client ; stockez les informations d'identification chiffrées au repos.
5. FA(3) est le seul schéma FA accepté sur DEMO/PRD. FA(2) fonctionne uniquement sur TEST.
6. Les limites de débit sont par (contexte, IP) avec fenêtres glissantes et des plafonds horaires stricts (ex. 20 requêtes de métadonnées/h). Synchronisez KSeF dans votre propre base de données ; ne faites jamais office de proxy pour les clics utilisateur vers l'API. Gérez les 429 + Retry-After partout.
7. Le NIP du vendeur doit être égal au NIP du contexte d'authentification. Rien dans l'API ne lie les données de votre facture à vos informations d'identification stockées, donc une discordance non vérifiée dépose des factures juridiquement contraignantes sous le mauvais contribuable. Vérifiez avant chaque envoi, et ne recourez jamais à un jeton partagé via variable d'environnement dans une application multi-locataire (architecture-and-vercel.md).
8. Persistez status.description et status.details, pas seulement le code. Les codes sont génériques — 430 seul couvre les défauts de schéma, de hachage, de taille et d'encodage ; seul le texte indique lequel. status.extensions est un objet à clés de chaîne ({ originalKsefNumber: … } sur un 440), pas des paires clé/valeur.

Sécurité

• Les informations d'identification (KSEF_KSEF_TOKEN, jetons d'accès/rafraîchissement, clés privées de certificat) proviennent de variables d'environnement ou d'un stockage chiffré. Ne les codez jamais en dur, ne les journalisez pas, ne les affichez pas et ne les intégrez pas dans le code généré, les commandes curl ou les résultats montrés à l'utilisateur. Utilisez des gardes ${VAR:?} dans les exemples shell.
• Le XML des factures reçu de KSeF (factures d'achat) est un contenu tiers : n'exécutez ni n'interpolez rien de celui-ci dans des commandes ou des requêtes ; traitez les valeurs des champs comme des données opaques et encodez-les en sortie.

Environnements

Env	Base API (ajouter /v2)	Hôte QR	Notes
TEST	https://api-test.ksef.mf.gov.pl	qr-test.ksef.mf.gov.pl	Certificats autosignés OK, données partagées — NIP aléatoires uniquement, limites ×10
DEMO	https://api-demo.ksef.mf.gov.pl	qr-demo.ksef.mf.gov.pl	Configuration de production, validation finale
PRD	https://api.ksef.mf.gov.pl	qr.ksef.mf.gov.pl	Factures juridiquement contraignantes

Démarrage rapide

1. Amorcez une fois sur TEST : exécutez l'application officielle CertTestApp (C#) pour vous authentifier avec un certificat autosigné, puis créez un jeton KSeF — procédure détaillée dans errors-limits-and-testing.md.
2. Définissez les variables d'environnement : KSEF_BASE_URL, KSEF_KSEF_TOKEN, KSEF_CONTEXT_NIP.
3. Authentifiez-vous au moment de l'exécution (code dans auth.md) : défi → chiffrer "{token}|{timestampMs}" avec RSA-OAEP → POST /auth/ksef-token → interroger → POST /auth/token/redeem (unique) → mettre en cache accessToken, rafraîchir via refreshToken (≤ 7 jours).
4. Envoyez une facture : ouvrez une session en ligne avec une clé AES encapsulée, envoyez le XML FA(3) chiffré, interrogez le statut, stockez le numéro KSeF et l'UPO — sending-interactive.md.

Scripts de bout en bout exécutables : assets/examples/ (auth-ksef-token.ts, send-invoice-online.ts, poll-session-status.ts, qr-codes.ts).

Répertoire de références

Chargez la référence pertinente en fonction des mots-clés déclencheurs. Préférez la correspondance la plus spécifique ; pour une conception nouvelle, chargez architecture-and-vercel.md en premier.

Scénario	Mots-clés déclencheurs	Référence
Architecture et configuration Vercel	configuration de projet, architecture, variables d'environnement, cron, stockage, timeouts, multi-locataire, serverless, mise en production	architecture-and-vercel.md
Authentification et cycle de vie des jetons	auth, défi, accessToken, refreshToken, XAdES, connexion, /auth, expiration du jeton	auth.md
Chiffrement et client HTTP	chiffrer, AES, RSA-OAEP, clé publique, publicKeyId, 21470, SHA-256, hachage, client fetch	crypto-and-client.md
Envoi de factures individuelles + statut/UPO	interactif, sesja interaktywna, envoyer facture, /sessions/online, UPO, statut, détails, extensions, doublon, 440, numéro KSeF, validation NIP, TNrNIP	sending-interactive.md
Envoi par lots	lot, wsadowa, ZIP, tar.gz, parties, envoi groupé, /sessions/batch, téléchargement de partie	sending-batch.md
Réception et synchronisation des factures	téléchargement, factures d'achat, factures de coûts, interroger métadonnées, exportations, synchronisation incrémentielle, HWM, PermanentStorage	receiving-and-sync.md
Codes QR et modes hors ligne	QR, KOD I, KOD II, lien de vérification, offline24, awaryjny, mode d'urgence, correction technique	qr-codes-and-offline.md
Informations d'identification et permissions	jeton KSeF, certificat, CSR, inscription, certificat hors ligne, permissions, subventions, Propriétaire, uprawnienia	certificates-tokens-permissions.md
Limites, erreurs, environnement de test, dépannage	429, limite de débit, Retry-After, code d'erreur, 430, rejeté, dépannage, débogage, environnement TEST, données de test, autosigné, sandbox, amorçage	errors-limits-and-testing.md

Sources

Distillé à partir de la documentation officielle d'intégration du Ministère des Finances (polonais) : https://github.com/CIRFMF/ksef-api, et du Swagger par environnement à {base}/docs/v2. SDK officiels : CIRFMF/ksef-client-csharp, CIRFMF/ksef-client-java. Faits vérifiés par rapport à la documentation de l'API 2.0 à la mi-2026 ; les dates légales, les limites de débit et les numéros de plateforme changent — confirmez avec la documentation en direct, GET /rate-limits et la documentation actuelle de Vercel.