Guide développeur API KSeF 2.0 : authentification, sessions, FA(3), UPO, offline

KSeF 2.0 est l'API REST du ministère polonais des Finances pour le système national de facturation électronique (Krajowy System e-Faktur). Une intégration s'authentifie avec un challenge signé par un certificat qualifié ou chiffré avec un token KSeF, échange le résultat contre un JWT de courte durée, ouvre une session avec une clé AES qu'elle a générée, soumet des factures XML FA(3) chiffrées avec cette clé, interroge leur statut et télécharge l'UPO — l'accusé de réception officiel qui donne à une facture son numéro KSeF et son existence légale. Ce guide suit cette séquence, puis traite de la soumission par lots, des modes offline, des limites et de la manière dont le module KSeF de KRONENWERK s'y rapporte.

Environnements

Trois environnements publics existent, et ils ne sont pas interchangeables. Tout ce qui suit s'applique aux trois ; l'URL de base détermine lequel.

La documentation de l'API est servie sous /docs/v2 sous chaque URL de base, et la même description OpenAPI, les guides et les bibliothèques clientes officielles (C# et Java) sont publiés par l'organisation CIRFMF du ministère sur GitHub. Depuis le 1er octobre 2025, les environnements de test ont des fenêtres de maintenance planifiées (16h00–18h00), pendant lesquelles les appels peuvent échouer. Ne soumettez jamais de factures de production ni de données d'entités réelles à TEST ou DEMO.

Authentification

Chaque appel protégé porte un jeton d'accès JWT. Son obtention suit un flux en cinq étapes dont la première et la dernière sont identiques quel que soit le moyen d'identification.

1. Challenge. POST /auth/challenge renvoie une valeur de challenge et un horodatage. Il est valable 10 minutes.
2. Prouver son identité, de l'une des deux manières suivantes :
   • Signature XAdES. Construisez un XML AuthTokenRequest contenant le challenge, l'identifiant de contexte (NIP, identifiant interne ou identifiant TVA UE de l'entité pour laquelle vous agissez) et le type d'identifiant du sujet, signez-le en XAdES avec un certificat qualifié (certificat qualifié personnel ou d'organisation, Profil de confiance, certificat KSeF ou certificat de prestataire Peppol), et envoyez-le à POST /auth/xades-signature.
   • Token KSeF. Concaténez {ksefToken}|{timestampMs}, chiffrez avec RSA-OAEP (SHA-256, MGF1) à l'aide de la clé publique publiée par le ministère, encodez en Base64 et envoyez le résultat avec le challenge et le contexte à POST /auth/ksef-token. Les tokens KSeF sont émis dans KSeF par une personne disposant déjà d'une autorisation pour l'entité ; ils conviennent aux intégrations sans intervention humaine.
   L'un ou l'autre appel renvoie un jeton d'authentification temporaire et un numéro de référence.
3. Interroger. GET /auth/{referenceNumber} avec le jeton temporaire jusqu'à ce que le statut soit définitif. La vérification est asynchrone — le système contrôle la signature et le certificat via OCSP/CRL.
4. Échanger. POST /auth/token/redeem échange le jeton temporaire, une seule fois, contre un accessToken (JWT, environ 15 minutes, la durée exacte figure dans sa revendication exp) et un refreshToken (environ 7 jours).
5. Rafraîchir. POST /auth/token/refresh avec le jeton de rafraîchissement renvoie un nouveau jeton d'accès portant les permissions actuelles de l'entité.

Les permissions sont accordées dans KSeF par entité et par rôle (émettre, lire, gérer les identifiants, etc.) ; un jeton d'accès reflète les permissions au moment de son émission et est invalidé lorsqu'elles sont retirées. Une politique d'autorisation peut restreindre un jeton à des adresses ou plages IP. Conservez les deux jetons comme des secrets.

Session interactive : soumission, statut, UPO

Une session interactive soumet les factures une par une, de façon synchrone sur le réseau et asynchrone dans le traitement. C'est le mode utilisé par la plupart des logiciels de facturation.

1. Préparer une clé. Générez une clé AES de 256 bits et un IV de 128 bits. Chiffrez la clé avec la clé publique RSA du ministère (RSAES-OAEP, MGF1 avec SHA-256). Les bibliothèques clientes du ministère comprennent un CryptographyService qui s'en charge.
2. Ouvrir. POST /sessions/online avec la version du schéma (FA(3) — le schéma de facture actuel ; FA(2) est encore mentionné dans la documentation) et la clé chiffrée. La réponse contient un referenceNumber de session et un validUntil. Une session vit 12 heures, et plusieurs peuvent être ouvertes en parallèle sous un même jeton d'accès.
3. Envoyer. POST /sessions/online/{referenceNumber}/invoices avec la facture chiffrée en AES-256-CBC avec padding PKCS#7 et encodée en Base64, plus le hachage SHA-256 et la taille du fichier en clair et du fichier chiffré. La réponse accuse réception ; la validation par rapport au schéma et aux règles métier démarre immédiatement et de façon asynchrone.
4. Interroger. GET /sessions/{referenceNumber}/invoices liste le statut de chaque facture : acceptée avec un numéro KSeF, ou rejetée avec un motif. Interrogez avec un délai croissant, pas dans une boucle serrée.
5. Fermer. POST /sessions/online/{referenceNumber}/close termine la session et déclenche la génération de l'UPO collectif.
6. Récupérer l'UPO. L'UPO (Urzędowe Poświadczenie Odbioru) est un document XML signé énumérant les factures acceptées avec leurs numéros KSeF et leurs horodatages d'acceptation. Conservez-le avec les factures : c'est la preuve que la facture a été émise au sens juridique.

Le numéro KSeF, et non votre numéro interne, est ce que l'acheteur voit dans sa propre boîte de réception KSeF et ce qu'une référence de paiement peut devoir citer. La date d'émission aux fins de la TVA est la date d'acceptation de la facture par KSeF, qui peut différer de la date figurant dans le FA(3) — un point qui nécessite une confirmation professionnelle pour tout cas précis.

Session par lots

Une session par lots soumet de nombreuses factures sous la forme d'un seul ZIP chiffré. Elle convient aux traitements de fin de mois et aux migrations.

1. Placez les fichiers XML FA(3) dans un ZIP.
2. Découpez le binaire ZIP en parties de 100 Mo au maximum, numérotées dans l'ordre.
3. Chiffrez chaque partie en AES-256-CBC avec le même schéma de clé que ci-dessus ; calculez le SHA-256 et la taille de chaque partie chiffrée.
4. POST /sessions/batch avec la clé chiffrée, les métadonnées du ZIP, la version du schéma et la liste des parties. La réponse renvoie un referenceNumber et, pour chaque partie, une URL de téléversement, une méthode et des en-têtes.
5. Téléversez chaque partie en binaire brut vers son URL. La fenêtre de téléversement est de 20 minutes par partie déclarée, mutualisées.
6. POST /sessions/batch/{referenceNumber}/close, puis interrogez le statut de la session et téléchargez l'UPO collectif comme pour une session interactive.

Les deux types de session acceptent jusqu'à 10 000 factures. Une facture peut peser au maximum 1 Mo, ou 3 Mo avec une pièce jointe.

Lire les factures

Le côté réception est symétrique. POST /invoices/query/metadata renvoie les métadonnées de factures pour un type de sujet (émetteur, destinataire, etc.) et une plage de dates, paginées avec pageOffset et pageSize. GET /invoices/ksef/{ksefNumber} télécharge une facture par numéro KSeF. Pour une récupération en masse, POST /invoices/exports démarre un export asynchrone sous une clé de chiffrement que vous fournissez, et GET /invoices/exports/{referenceNumber} rend compte de l'avancement et fournit le paquet chiffré. Une intégration qui doit voir chaque facture d'achat interroge la requête de métadonnées de manière incrémentale plutôt que d'exporter à répétition.

Modes offline

Trois modes permettent à un contribuable d'émettre hors KSeF et de soumettre ensuite. Chacun a son propre déclencheur et sa propre échéance, et chacun est juridiquement distinct.

Une facture offline est un FA(3) normal avec deux codes QR imprimés ou intégrés : le KOD I, qui permet à l'acheteur de vérifier la facture dans KSeF, et le KOD II, qui confirme l'identité de l'émetteur à partir de son certificat KSeF. Lors de sa soumission ultérieure, définissez offlineMode: true sur la requête d'envoi, dans l'un ou l'autre type de session. Si KSeF devient indisponible pendant la fenêtre de soumission, le délai redémarre et peut aller jusqu'à 7 jours ouvrables à compter de la fin de l'interruption.

Limites et erreurs

Le ministère documente les limites par contexte (l'entité pour laquelle vous agissez) et par moyen d'identification plutôt que par clé API : 10 000 factures par session, 1 Mo ou 3 Mo par facture, 100 Mo par partie de lot, et des plafonds sur les demandes de certificats et les certificats actifs par identifiant (pour un NIP, 300 demandes et 100 certificats actifs au moment de la lecture). Des limites de débit de requêtes existent — la documentation indique que le système restreint le nombre de requêtes pour protéger sa stabilité — et sont décrites dans un document distinct sur la limitation de débit ; concevez pour un HTTP 429 avec nouvelle tentative et délai croissant plutôt que pour un chiffre fixe.

Les erreurs reviennent sous la forme d'un statut HTTP avec un corps JSON décrivant le problème : 400 pour les requêtes mal formées, 401 pour un jeton manquant ou expiré, 403 pour une permission que le jeton ne porte pas, et des erreurs de validation par facture signalées dans le statut de session plutôt que sur l'appel d'envoi. Les échecs de schéma (le XML ne correspond pas à FA(3)) et les échecs sémantiques (un NIP inexistant, une date hors de la fenêtre autorisée, un doublon) apparaissent à des étapes différentes ; lisez l'entrée de statut de chaque facture plutôt que de vous fier à un 2xx sur le téléversement.

Comment KRONENWERK gère cela

PAS ENCORE PRÊT Le module KSeF 2.0 de KRONENWERK implémente le flux décrit ci-dessus : authentification par token (challenge, token KSeF chiffré, échange, rafraîchissement), session interactive avec une clé AES générée par session, génération et soumission de FA(3), interrogation du statut, récupération de l'UPO et lecture des factures reçues. Il dépend de l'environnement par configuration — le même code cible TEST, DEMO ou la production selon les paramètres — et il n'a pas été utilisé contre le KSeF de production. Pour cette raison, KRONENWERK ne vend actuellement pas d'abonnements aux entreprises polonaises, et rien sur cette page ne doit être lu comme une acceptation en production. La génération de FA(3) elle-même est PRISE EN CHARGE AVEC RESTRICTIONS : le XML est produit et vérifié par rapport au schéma à l'émission, mais la transmission ainsi que le numéro KSeF et l'UPO qui en résultent dépendent de la validation du module en production. L'API publique n'expose pas les opérations KSeF : POST /invoices/drafts crée un brouillon, l'émission a lieu dans le produit, et aucun endpoint ne soumet de FA(3), ne renvoie de numéro KSeF ni ne récupère d'UPO. Voir intégration KSeF pour ce que propose l'API, KSeF expliqué et FA(3) pour le format, ainsi que le hub Pologne et la page pays pour le statut actuel.