Intégration KSeF : comment fonctionne le module KSeF 2.0 de KRONENWERK

KRONENWERK contient un module KSeF 2.0 qui s'authentifie avec le jeton KSeF d'un contribuable, ouvre une session en ligne, dépose des factures FA(3) chiffrées sous la clé du ministère, interroge le système jusqu'à obtenir le numéro KSeF, récupère l'UPO et lit les factures entrantes. Le module est construit et testé contre les environnements du ministère, mais il n'a pas été utilisé contre le KSeF de production, et KRONENWERK ne vend actuellement pas d'abonnements aux entreprises polonaises tant que cela n'est pas prouvé. Pour la transmission, le statut est PAS ENCORE PRÊT. Votre intégration utiliserait l'API ordinaire autour de lui — clients, brouillons, webhooks — et rien de spécifique à KSeF n'est exposé sur l'API.

Ce qu'est KSeF, en un paragraphe

KSeF (Krajowy System e-Faktur) est le système central de clearance de la Pologne : une facture structurée au schéma FA(3) est déposée dans le système du ministère des Finances, qui la valide, lui attribue un numéro KSeF et renvoie un accusé officiel (UPO, urzędowe poświadczenie odbioru). Tant que ce numéro n'existe pas, le fichier n'est pas juridiquement une facture. Cela distingue la Pologne de l'Allemagne, où un fichier conforme envoyé par n'importe quelle voie satisfait à l'obligation, et de la Belgique, où la voie est le réseau Peppol. Le contexte est sur KSeF expliqué ; le schéma sur FA(3) ; le hub sur facturation électronique en Pologne.

Ce que fait le module KSeF 2.0 de KRONENWERK

Le module implémente l'API KSeF 2.0 telle que publiée dans la spécification OpenAPI du ministère (chemins et noms de champs copiés de là, pas retenus de mémoire). Il fonctionne par contribuable : chaque appel est effectué dans le contexte d'un NIP avec le jeton KSeF de ce contribuable, et les jetons d'accès sont mis en cache par NIP et rafraîchis avant leur expiration.

Deux méthodes d'authentification du ministère existent ; le module utilise la méthode par jeton KSeF, dans laquelle un document JSON portant un jeton système obtenu au préalable est envoyé à la place d'une requête XML signée en XAdES. Le jeton appartient à l'entreprise et lui est délivré dans KSeF ; KRONENWERK le stocke scellé et ne l'utilise que pour s'authentifier. Le ministère documente les deux méthodes et précise que les certificats auto-signés ne sont acceptés que dans l'environnement de test.

Pourquoi il dépend de l'environnement et n'est pas encore prêt

Le ministère publie trois environnements, et le module est configuré contre exactement l'un d'eux à la fois :

Le module de KRONENWERK a été exercé contre les environnements hors production du ministère. Il n'a pas été utilisé contre le KSeF de production, où un dépôt est un acte juridique dont dépend la situation fiscale d'un tiers. Tant qu'un dépôt réel avec un UPO réel n'a pas été effectué et vérifié, KRONENWERK marque la transmission PAS ENCORE PRÊT et ne vend pas d'abonnements aux entreprises polonaises. C'est une affirmation sur la preuve, pas sur la couverture du code : la différence entre « le client passe ses tests » et « le ministère a accepté notre facture » est celle qui compte, et c'est celle qui reste à établir.

La génération FA(3) elle-même — produire le XML à partir des faits d'un brouillon et le valider contre le schéma — est PRIS EN CHARGE AVEC LIMITATIONS : le document est produit, mais un fichier FA(3) sans numéro KSeF n'est pas une facture, son utilité est donc bornée par le statut de transmission ci-dessus.

Comment un développeur utiliserait l'API autour de lui

Rien sur l'API KRONENWERK n'est spécifique à KSeF. Si la voie polonaise devient disponible, une intégration ressemble exactement à celle de n'importe quel autre pays : le travail KSeF est à l'intérieur de l'émission et de la transmission, qui restent toutes deux dans le produit.

1. Créez le client polonais avec POST /customers, en incluant country: "PL" et le NIP de l'acheteur dans vatId. FA(3) identifie l'acheteur par son NIP, et un client sans NIP ne peut pas être facturé via KSeF.
2. Démarrez le brouillon avec POST /invoices/drafts et un Idempotency-Key.
3. Une personne complète et émet le brouillon dans le produit. Le module polonais génère le XML FA(3) et le valide ; le numéro est consommé et invoice.issued est mis en file d'attente.
4. La personne transmet la facture émise depuis le produit. Le module s'authentifie avec le jeton KSeF de l'entreprise stocké dans Paramètres → Envoi, ouvre une session, dépose, interroge, clôture et stocke le numéro KSeF et l'UPO. Un résultat inconnu bloque tout renvoi jusqu'à ce qu'une requête de rapprochement ait demandé à KSeF s'il détient déjà le document.
5. Votre endpoint reçoit invoice.issued, puis invoice.paid ou invoice.cancelled. Le numéro KSeF, l'UPO et l'état de transmission sont affichés dans le produit et ne figurent pas sur l'API aujourd'hui.

Ce que l'entreprise doit configurer, lorsque la voie sera disponible : les données de base de l'entité juridique avec son NIP (dérivé du numéro fiscal), le jeton KSeF saisi dans Paramètres → Envoi — KRONENWERK le valide immédiatement en effectuant un appel authentifié avec le jeton même qu'il vient de stocker, et refuse de conserver un jeton qui ne fonctionne pas — et, pour votre intégration, une clé API avec customers:write, customers:read, invoices:write, invoices:read et companies:read plus un endpoint de webhook. Les mécanismes généraux de l'API sont sur la page de l'API comptable et la page de l'API de facturation.

Bases de l'API KSeF 2.0, avec sources

Si vous évaluez plutôt une intégration directe, la documentation du ministère est la source primaire et c'est par là qu'il faut commencer.

• Guide de l'intégrateur : le guide du ministère (daté du 5 mai 2026 dans sa révision actuelle) couvre l'authentification, les permissions, les certificats KSeF, les modes hors ligne, les codes QR, les sessions interactives et par lots, la récupération des factures, la récupération incrémentale, la gestion des jetons KSeF, les clés de chiffrement, les limites et les données de test, avec des exemples en C# et Java tirés de ses clients de référence open source. github.com/CIRFMF/ksef-docs.
• OpenAPI : chaque environnement sert sa propre spécification sous /docs/v2 ; celle de test est à api-test.ksef.mf.gov.pl/docs/v2. Les erreurs sont des documents « problem » RFC 7807 avec detail et une liste errors[].
• Authentification : obtenir un challenge (valable dix minutes), puis soit envoyer un AuthTokenRequest XML signé en XAdES avec un certificat qualifié ou un certificat KSeF, soit envoyer un document JSON avec un jeton KSeF ; interroger le statut ; obtenir un jeton d'accès JWT et un jeton de rafraîchissement. La partie qui s'authentifie doit détenir au moins une permission active pour le contexte choisi (un NIP, un identifiant interne ou un identifiant composite de TVA de l'UE). uwierzytelnianie.md.
• Sessions : une session interactive prend les factures une par une et renvoie un statut par facture ; la clôture de la session déclenche la génération d'un UPO collectif. Une session par lots est documentée séparément pour le dépôt en masse. Les clés publiques pour chiffrer la clé de session et le jeton KSeF sont publiées par le ministère et font l'objet d'une rotation.
• Environnements et maintenance : TEST et DEMO ne doivent jamais recevoir de factures de production ni de données réelles de parties ; le ministère planifie la maintenance des environnements de test de 16 h 00 à 18 h 00 et publie les modifications affectant l'API dans son changelog. srodowiska.md.

Le guide KSeF pour développeurs approfondit le schéma et le modèle de session.

Comment KRONENWERK gère cela

PAS ENCORE PRÊT pour la transmission. Le module KSeF 2.0 — authentification par jeton, session, dépôt FA(3), récupération de l'UPO et réception — est construit et dépendant de l'environnement, et il n'a pas été utilisé contre le KSeF de production. KRONENWERK ne vend actuellement pas d'abonnements aux entreprises polonaises tant que cela n'est pas prouvé, et rien sur cette page ne doit être lu comme impliquant une acceptation gouvernementale ou de production. La génération FA(3) est PRIS EN CHARGE AVEC LIMITATIONS. L'API n'expose aucun endpoint, événement ou champ spécifique à KSeF ; lorsque la voie sera prouvée, les intégrations utiliseront les mêmes appels de clients, de brouillons et de webhooks que partout ailleurs. La page pays Pologne se trouve sur Pologne ; le périmètre de facturation électronique du produit sur facturation électronique.