KSeF 2.0 expliqué : authentification, sessions, UPO, modes hors ligne, codes QR

KSeF 2.0 est la version du système national polonais de facturation électronique qui est la seule en vigueur depuis le 1er février 2026, date à laquelle KSeF 1.0 a été arrêté. Le logiciel s'authentifie avec une signature qualifiée ou un jeton KSeF et reçoit des jetons d'accès JWT, ouvre une session interactive ou par lots, envoie du XML FA(3) chiffré en AES, et obtient en retour un numéro KSeF de 35 caractères par facture et un accusé de réception officiel (UPO) par session. Les modes hors ligne, les codes QR et les certificats KSeF couvrent les cas où la facture parvient à l'acheteur en dehors du système.

Ce qui a changé de KSeF 1.0 à 2.0

KSeF 2.0 est un nouveau contrat d'API, pas un correctif : l'authentification a été séparée des sessions, les jetons JWT ont remplacé l'ancienne connexion liée à la session, le chiffrement est devenu obligatoire dans tous les modes, les noms ont été rendus RESTful et un module de certificats a été ajouté.

L'aperçu du ministère à l'intention des intégrateurs énumère les changements clés : l'authentification comme étape indépendante produisant des jetons réutilisables, rafraîchissables et révocables ; un modèle d'initialisation unique pour POST /sessions/online et POST /sessions/batch, chacun prenant un code de formulaire et une clé AES chiffrée ; le chiffrement obligatoire côté client de chaque facture avec RSA-OAEP (SHA-256, MGF1-SHA-256) protégeant la clé de session ; des identifiants cohérents (NIP, PESEL, empreinte) sous forme d'énumérations explicites ; et des certificats KSeF internes pour l'authentification et l'émission hors ligne. L'API est décrite en OpenAPI 3.0.4 avec une documentation interactive sur api.ksef.mf.gov.pl/docs/v2, et le ministère publie des bibliothèques clientes open source pour C# et Java.

Environnements : test, démo, production

Trois environnements publics existent, et seule la production a un effet juridique.

Le calendrier du ministère : les tests ouverts de l'API ont commencé le 30 septembre 2025, l'API de démo a ouvert le 15 octobre 2025, l'environnement de test de KSeF 1.0 a été fermé le 1er septembre 2025, et la production de KSeF 2.0 a démarré le 1er février 2026 après une interruption technique du 26 au 31 janvier. Les URL renvoyées par l'API pointent toujours vers l'environnement appelé. Des maintenances planifiées sur les environnements de test peuvent avoir lieu de 16 h à 18 h, et seuls les changements pertinents pour l'intégration sont annoncés dans le journal des modifications.

Authentification : signature, jeton KSeF, certificats

Chaque appel protégé nécessite un accessToken JWT. Pour l'obtenir, le client prouve qui il est (le sujet authentifiant) et pour qui il agit (le contexte, généralement un NIP), et KSeF vérifie que le sujet détient au moins une permission active dans ce contexte.

1. Défi. POST /auth/challenge renvoie un défi valable 10 minutes.
2. Preuve d'identité, de l'une des deux façons :
   • Signature XAdES. Le client construit un XML AuthTokenRequest (défi, identifiant de contexte — NIP, identifiant interne ou composite NIP-VAT-EU — et type d'identifiant de sujet certificateSubject ou certificateFingerprint, éventuellement une politique d'IP autorisées) et le signe. Signataires acceptés : un certificat qualifié de personne physique portant le PESEL ou le NIP, un cachet d'organisation qualifié portant le NIP, une signature Profil de confiance (Profil Zaufany), un certificat KSeF ou un certificat de prestataire de services Peppol. Les certificats auto-signés ne sont acceptés que sur TEST.
   • Jeton KSeF. Une requête JSON avec un jeton système généré au préalable. Les jetons sont générés avec POST /tokens après au moins une authentification XAdES, portent une liste de permissions telles que InvoiceRead, InvoiceWrite, CredentialsRead, CredentialsManage, et sont des secrets confidentiels.
3. Jetons. La réponse fournit un accessToken et un refreshToken ; les jetons d'accès expirent, peuvent être rafraîchis sans nouvelle authentification et sont révoqués automatiquement en cas de perte des permissions. Les sessions sont listées sous GET /auth/sessions et révoquées avec DELETE /auth/sessions/current ou par numéro de référence.

Les certificats KSeF sont émis par le système lui-même et ne sont pas des certificats qualifiés. Un certificat porte exactement un type : Authentication (usage de clé signature numérique) pour la connexion, ou Offline (usage de clé non-répudiation) pour signer le second code QR des factures hors ligne ; il ne peut pas faire les deux. La demande (/certificates/enrollments) n'est possible qu'après une authentification XAdES, au nom propre du sujet, avec une CSR PKCS#10, et un certificat est valable au plus deux ans. Limites par défaut : 300 demandes et 100 certificats actifs par NIP, 12 et 6 par PESEL ou empreinte.

Les permissions elles-mêmes sont accordées dans le système : une entreprise qui n'a pas de cachet qualifié désigne une personne physique sur le formulaire ZAW-FA, et cette personne accorde ensuite d'autres droits, par exemple à un comptable ou au certificat d'un intégrateur logiciel.

Sessions : interactives et par lots

Une session interactive envoie les factures une à une et convient aux logiciels de facturation ; une session par lots envoie un ZIP d'au plus 10 000 factures en parties chiffrées d'au plus 100 Mo et convient aux envois en masse. Les deux commencent par le même JSON : le code de formulaire (version du schéma) et la clé AES de la session chiffrée avec la clé publique du ministère.

Interactive

1. Générer une clé AES de 256 bits et un IV de 128 bits ; chiffrer la clé avec RSA-OAEP en utilisant la clé publique courante obtenue via GET /security/public-key-certificates.
2. POST /sessions/online avec le code de formulaire (FA(3)) et la clé chiffrée. La réponse donne un referenceNumber et un validUntil ; une session vit 12 heures et plusieurs peuvent être ouvertes en parallèle.
3. POST /sessions/online/{referenceNumber}/invoices avec chaque facture chiffrée en AES-256-CBC (remplissage PKCS#7), son hachage et sa taille. La réponse renvoie un numéro de référence de document.
4. Interroger GET /sessions/{referenceNumber} et GET /sessions/{referenceNumber}/invoices pour le statut par facture, le numéro KSeF et l'UPO de facture.
5. POST /sessions/online/{referenceNumber}/close. La fermeture déclenche la génération asynchrone de l'UPO collectif de la session.

Par lots

Le client compresse les fichiers XML en ZIP, découpe le ZIP en parties binaires d'au plus 100 Mo avant chiffrement, chiffre chaque partie, décrit les parties dans fileParts à l'ouverture de POST /sessions/batch, les téléverse vers les URL renvoyées et ferme la session. Le ministère recommande d'enregistrer un hachage SHA-256 par XML d'origine afin de pouvoir rapprocher les statuts KSeF des documents locaux. Limites par défaut par contexte : 1 Mo par facture (3 Mo avec pièce jointe), 10 000 factures par session, 500 par identifiant collectif.

Numéro KSeF et UPO

Le numéro KSeF est la preuve qu'une facture existe ; l'UPO (Urzędowe Poświadczenie Odbioru) est l'accusé de réception officiel d'une session et de ses factures.

Le numéro fait toujours 35 caractères : NIP-YYYYMMDD-XXXXXXXXXXXX-CC — le NIP à dix chiffres du vendeur, la date à laquelle la facture a été acceptée pour traitement, une partie technique hexadécimale de douze caractères et une somme de contrôle CRC-8 de deux caractères (polynôme 0x07, valeur initiale 0x00). Un logiciel peut valider un numéro hors ligne en recalculant la somme de contrôle. Il ne doit pas être confondu avec le numéro de facture propre au vendeur dans le champ P_2.

Avant d'attribuer un numéro, KSeF vérifie deux choses : que le XML est conforme au schéma en vigueur et que l'expéditeur a le droit d'émettre dans ce contexte. Un fichier rejeté n'est pas une facture ; il est corrigé et resoumis, pas « corrigé » par un avoir. Pour une facture en ligne, la date d'émission est la date de transmission, tant que le champ P_1 lui correspond, même si le numéro arrive le lendemain.

Modes hors ligne

Quatre modes permettent de continuer à émettre lorsque la connexion ou le système n'est pas disponible ; trois d'entre eux exigent que la facture soit envoyée à KSeF ensuite, avec offlineMode: true, dans un délai légal.

Dans les modes hors ligne, la date d'émission est la date figurant dans P_1, pas la date de transmission. Sauf en mode d'urgence, l'acheteur reçoit la facture dans KSeF et ne se voit pas remettre de copie avant la transmission ; en mode d'urgence, le fichier FA(3) est remis à l'acheteur selon un mode convenu et numéroté ensuite. Si une panne annoncée tombe dans la fenêtre offline24 ou d'indisponibilité, le délai est reporté à 7 jours ouvrables après la fin de cette panne. Une facture émise hors KSeF ne doit jamais être réémise dans le système — cela crée deux factures pour une seule vente.

Codes QR sur les visualisations

Une visualisation remise en dehors de KSeF — PDF, impression, pièce jointe d'e-mail — porte un code QR permettant à quiconque de vérifier la facture dans le système ; les factures hors ligne en portent deux.

• KOD I renvoie à la page de vérification et permet au détenteur de vérifier et, avec des données supplémentaires, de télécharger la facture. En dessous figure le numéro KSeF lorsqu'il est connu, ou le mot OFFLINE avant l'attribution du numéro.
• KOD II confirme l'identité de l'émetteur pour les factures hors ligne. Il est signé avec un certificat KSeF Offline ; un certificat Authentication ne peut pas être utilisé. KSeF vérifie que le certificat existe, est valide, non révoqué et non bloqué, et que son sujet détient des droits d'émission actifs dans le contexte.

Les codes sont générés localement par le client à partir des données de la facture (ISO/IEC 18004:2024) et l'hôte du lien suit l'environnement. Une visualisation ne peut être remise à l'acheteur qu'une fois la facture enregistrée dans KSeF, sauf en mode d'urgence.

Recevoir des factures

Les acheteurs récupèrent les factures dans KSeF au lieu de les recevoir par e-mail. L'API propose des requêtes de factures et le téléchargement incrémental des factures nouvellement émises dans le contexte de l'acheteur, et le ministère confirme qu'un logiciel peut les récupérer automatiquement. Les acheteurs étrangers sans NIP ne peuvent pas se connecter et reçoivent à la place une copie avec le KOD I. Le fichier FA(3) qui revient est documenté sur la page du schéma FA(3).

Comment KRONENWERK gère cela

Pas encore prêt pour la transmission. Le module KSeF 2.0 de KRONENWERK — authentification par jeton, session interactive, soumission FA(3), récupération de l'UPO et réception — est développé et dépend de l'environnement, et il n'a pas été utilisé contre le KSeF de production. La génération FA(3) et la validation de schéma sont Pris en charge avec des limitations. KRONENWERK ne vend pas d'abonnements aux entreprises polonaises tant que la soumission en production n'a pas été prouvée ; voir le hub Pologne et la page pays Pologne.

La conception suit la règle qu'impose le système : une facture n'est pas « émise » dans KRONENWERK tant que KSeF n'a pas renvoyé de numéro, et une soumission dont la réponse a été perdue est rapprochée en demandant à KSeF ce qu'il détient plutôt que renvoyée, car une nouvelle tentative à l'aveugle créerait une seconde facture légale. Les développeurs qui intègrent leurs propres systèmes peuvent comparer cela avec l'intégration KSeF et le guide KSeF pas à pas. Cette page décrit le système du ministère ; ce n'est pas un conseil fiscal ou juridique.

Questions fréquentes

Ai-je besoin d'une signature qualifiée pour utiliser l'API KSeF ?

Pour la première authentification, oui — un certificat qualifié, un cachet qualifié, une signature Profil de confiance ou un certificat KSeF. Ensuite, le logiciel peut utiliser un jeton KSeF ou un certificat KSeF Authentication.

Quelle est la différence entre le numéro KSeF et l'UPO ?

Le numéro KSeF est l'identifiant de 35 caractères attribué à chaque facture acceptée ; l'UPO est l'accusé de réception officiel généré pour une session, disponible après sa fermeture, et également par facture.

Que signifie offline24 ?

Le contribuable émet une facture FA(3) sans connexion et doit la transmettre à KSeF au plus tard le jour ouvrable suivant ; l'acheteur la reçoit dans KSeF, et la visualisation porte deux codes QR.

Puis-je tester avec des données réelles sur l'environnement de test ?

Non. Le ministère indique que les données de TEST sont partagées entre intégrateurs et doivent utiliser des NIP aléatoires et des données anonymisées ; DEMO utilise de vrais identifiants mais n'a aucun effet juridique.

Chaque facture est-elle chiffrée ?

Oui. Dans KSeF 2.0, chaque facture, interactive ou par lots, est chiffrée côté client avec une clé AES elle-même chiffrée avec la clé publique du ministère à l'ouverture de la session.