KSeF TEST, DEMO et production : intégrer en toute sécurité

KSeF propose trois environnements d’API publics, chacun conçu pour un usage différent. TEST est un bac à sable d’intégration partagé qui sert à travailler sur des données synthétiques et à simuler les échecs. DEMO s’appuie sur une identité et des autorisations réelles pour valider le comportement dans des conditions proches de la production, mais le contenu des factures doit rester fictif. PRD émet des factures qui produisent des effets juridiques. Pour sécuriser une intégration, isolez les éléments d’authentification et les données propres à chaque environnement, puis faites passer une même version figée par ces trois frontières.

Ce guide a été vérifié le 28 août 2026 à partir de la documentation du ministère polonais des Finances et du CIRF. KSeF déploie les changements d’API environnement par environnement. Traitez donc le journal des modifications officiel et le contrat OpenAPI actif de chaque environnement comme des données d’entrée de chaque mise en production. Il s’agit de conseils techniques, et non fiscaux ou juridiques.

Quelles différences entre KSeF TEST, DEMO et PRD ?

La différence ne se limite pas au nom d’hôte. Chaque environnement possède son propre modèle de confiance, ses règles sur les données, ses éléments d’authentification, sa version d’API et les conséquences d’un envoi réussi.

Ces frontières sont décrites dans l’assistance du ministère aux intégrateurs et la matrice des environnements KSeF du CIRF. Mieux vaut connaître les alias, car les documents officiels emploient les deux formes : TEST s’appelle aussi TE ou environnement d’intégration, tandis que DEMO s’appelle également TR ou environnement de préproduction.

Une règle ne change pas d’une version à l’autre : ne transférez jamais les données ni les éléments d’authentification entre environnements. Faites passer le code testé et la structure de configuration, puis configurez l’environnement cible séparément.

Comment configurer les points d’accès des environnements KSeF ?

Sélectionnez un profil d’environnement autorisé plutôt qu’une URL arbitraire. Un processus de production ne doit jamais accepter un hôte de base fourni par un paramètre de requête, un champ de facture ou un réglage modifiable en base de données.

Une petite table de correspondance immuable rend le choix explicite :

KSEF_ENVIRONMENTS = {
  test: {
    api_base: "https://api-test.ksef.mf.gov.pl/v2",
    docs: "https://api-test.ksef.mf.gov.pl/docs/v2"
  },
  demo: {
    api_base: "https://api-demo.ksef.mf.gov.pl/v2",
    docs: "https://api-demo.ksef.mf.gov.pl/docs/v2"
  },
  production: {
    api_base: "https://api.ksef.mf.gov.pl/v2",
    docs: "https://api.ksef.mf.gov.pl/docs/v2"
  }
}.freeze

profile = KSEF_ENVIRONMENTS.fetch(ENV.fetch("KSEF_ENV").to_sym)

Il ne s’agit que de la partie publique du profil. Conservez les valeurs suivantes ensemble, dans un périmètre propre à chaque environnement :

• référence du certificat et de la clé privée ;
• stockage du jeton KSeF, du jeton d’accès et du jeton de renouvellement ;
• cache des clés publiques KSeF et publicKeyId sélectionné ;
• espace de noms de la base de données ou du stockage objet pour les fichiers XML et UPO ;
• file d’attente, budget de nouvelles tentatives et mécanisme de coordination des limites de débit ;
• tableaux de bord, alertes et libellés des journaux ;
• indicateur d’activation de la production et mécanisme d’arrêt d’urgence.

L’avis du ministère sur les éléments d’authentification en production est sans ambiguïté : les clés de production et les éléments d’authentification KSeF appartiennent à PRD. Un jeton, un certificat ou une clé de chiffrement provenant de TEST ou DEMO n’est pas un élément d’authentification de production. Le guide sur les clés publiques décrit également leur rotation. N’utilisez donc pas un cache de clé unique pour les trois environnements.

Ne réécrivez pas les URL renvoyées par KSeF

KSeF peut renvoyer des URL signées pour le téléversement ou le téléchargement. Le CIRF précise que leur hôte correspond à l’environnement appelé. Vérifiez l’hôte renvoyé dans la liste d’autorisation de l’environnement sélectionné, puis utilisez l’URL complète telle quelle. Ne remplacez pas son hôte, n’ajoutez pas /v2 devant son chemin et ne joignez pas de jeton porteur de production à une URL de stockage.

Ce détail paraît mineur jusqu’à ce qu’un utilitaire conçu pour les routes d’API ordinaires reçoive une URL signée de stockage objet. Traitez les bases d’API et les URL de ressources renvoyées comme deux types distincts.

Que faut-il tester dans l’environnement KSeF TEST ?

TEST sert à prouver que le client gère les contrats et les échecs avec des données synthétiques. L’accès y est volontairement plus simple qu’en production. Il ne peut donc pas confirmer que l’identité ou les autorisations de production fonctionneront.

TEST accepte les certificats autosignés et les éléments d’authentification simulés. Ses points d’accès /testdata/* peuvent créer des personnes de test, des structures d’entités et des autorisations, activer des scénarios avec pièces jointes, bloquer un contexte, réduire la durée de validité d’un certificat et modifier les profils de limites. Le CIRF publie des exemples exécutables dans le guide des scénarios de données de test.

Servez-vous de ces commandes pour reproduire des états qu’il serait coûteux de déclencher naturellement :

1. authentification valide et invalide ;
2. autorisation refusée après la réussite de l’authentification ;
3. expiration et rotation des certificats ;
4. échec d’un envoi en ligne ou par lot ;
5. traitement du code HTTP 429 et suspension coordonnée du quota ;
6. redémarrage du processus alors qu’une facture est toujours en traitement asynchrone ;
7. champs de réponse inconnus et nouveaux en-têtes d’avertissement ;
8. récupération de l’UPO après la disparition du processus de traitement initial.

L’objectif ne consiste pas à valider une seule fois le parcours idéal. Il faut prouver que l’intégration atteint un état connu lorsque KSeF accepte, retarde, rejette ou limite une demande, ou ajoute un élément à sa réponse.

Pourquoi les données réelles sont dangereuses dans TEST

TEST n’est pas un environnement privé par client. Plusieurs intégrateurs pouvant s’authentifier dans le même contexte d’entreprise synthétique, des données risquent d’être visibles en dehors de votre exécution de test. Le CIRF demande aux intégrateurs d’utiliser des identifiants aléatoires et aucune donnée d’entité réelle.

Cet avertissement ne vise pas seulement les noms. N’envoyez ni vrais numéros de facture, ni adresses, ni descriptions de lignes, ni coordonnées bancaires, ni adresses e-mail, ni références client, ni fichiers XML de production dans lesquels seul le NIP aurait été remplacé. Générez un jeu de données entièrement synthétique. Recréez-le au besoin : les données de TEST sont supprimées périodiquement et aucune source officielle actuelle ne garantit de durée de conservation.

Un garde-fou lié à l’environnement doit rejeter les identifiants de clients de production et les préfixes connus des factures de production avant la sérialisation. Ce contrôle doit figurer dans le code de l’application, pas dans une liste de vérification de mise en production que quelqu’un pourrait ignorer.

Que faut-il valider dans KSeF DEMO ?

DEMO teste ce que TEST simule volontairement : l’identité d’authentification réelle, les rattachements réels aux entités et les chaînes d’autorisation effectives. C’est la répétition générale d’une version candidate à la production, et non un second bac à sable pour des identités arbitraires.

L’avis de lancement de DEMO du ministère indique que DEMO utilise des données d’authentification et des autorisations réelles, comparables à celles de la production. Vous y découvrirez l’écart entre « notre code XAdES fonctionne » et « ce certificat peut agir pour ce contribuable avec l’autorisation requise ». Le guide d’authentification KSeF présente ce parcours en détail.

DEMO doit répondre à cinq questions avant la mise en production :

• L’organisation réelle peut-elle s’authentifier avec le certificat prévu ?
• Les opérateurs et les systèmes concernés disposent-ils des autorisations KSeF effectives ?
• La version candidate fonctionne-t-elle avec les formats de facture pris en charge en production ?
• Reste-t-elle stable avec des limites de requêtes proches de la production ?
• Peut-elle reprendre l’interrogation de l’état et la collecte des preuves après un redémarrage ?

Utilisez exactement la version que vous prévoyez de mettre en production. Évitez les branches propres à DEMO et les correctifs manuels. Lorsqu’une différence de configuration s’impose, placez-la dans le profil d’environnement plutôt que dans du code qui modifierait discrètement le comportement.

Une connexion réelle n’autorise pas de vraies factures

DEMO associe une identité réelle à des données de facture fictives. Le ministère précise que les factures n’y produisent aucun effet juridique et sont supprimées par la suite. Il indique aussi que l’environnement peut contenir des données migrées ou issues de la production qui ne sont pas anonymisées et bénéficient d’une protection de niveau production.

Ces deux affirmations sont compatibles. Vos données de test doivent être fictives, alors que celles qui se trouvent déjà dans DEMO peuvent rester sensibles. Appliquez les contrôles d’accès de production et masquez les données sensibles dans les journaux. Ne présentez pas DEMO comme une base composée de données d’exemple inoffensives.

Pourquoi même un test minimal en PRD reste-t-il une vraie facture ?

PRD ne possède aucun mode de « facture de test » sans conséquence. Si KSeF accepte le document et lui attribue un numéro KSeF, la facture entre dans le circuit juridique.

Le manuel KSeF 2.0, partie II du ministère avertit qu’une facture de test envoyée par erreur en production peut avoir des conséquences en matière de TVA. L’article 108, paragraphe 1, de la loi polonaise sur la TVA est formel : l’émetteur qui indique la TVA sur une facture est tenu de la payer.

Votre première émission contrôlée doit donc correspondre à une véritable opération commerciale. Avant de la lancer :

• configurez les éléments d’authentification de production dans PRD au lieu de les copier depuis DEMO ;
• vérifiez le contexte du contribuable et les autorisations avec des appels qui n’émettent rien ;
• confirmez que la facture est réelle, approuvée et prête à être comptabilisée ;
• commencez avec une file d’attente vide ou maîtrisée ;
• demandez à un opérateur de surveiller l’état, le numéro KSeF et l’UPO ;
• sachez interrompre les nouveaux envois sans perdre les références déjà acceptées.

Ne créez jamais de repli automatique de TEST ou DEMO vers PRD. Une nouvelle tentative ne doit jamais changer l’environnement sélectionné. Enregistrez l’environnement avec chaque référence de session, référence de facture, numéro KSeF et clé d’objet UPO afin d’empêcher tout rapprochement entre deux environnements.

Le guide sur l’UPO et l’interrogation de l’état détaille les preuves à conserver pour chaque facture acceptée. Un code HTTP 202 ou une référence de session ne constitue pas une acceptation définitive.

Quel est l’effet du décalage des versions de l’API KSeF sur la mise en production ?

TEST peut précéder DEMO et PRD. Vous êtes ainsi averti plus tôt d’un changement, mais une validation réussie dans un environnement peut aussi porter sur un contrat différent de celui de l’environnement cible.

Le journal des modifications officiel indique que l’API 2.7.1 a été déployée dans TEST le 26 août 2026, et que les déploiements dans DEMO et PRD sont prévus respectivement les 15 et 23 septembre. À la date de vérification, la version 2.6.1 était la plus récente signalée comme déployée dans PRD. Cet état des versions deviendra vite obsolète ; le principe de déploiement progressif, lui, restera valable.

Avant chaque mise en production, consignez les éléments suivants :

Ne générez pas un client à partir de la branche main du dépôt en supposant qu’il correspond à la production. Figez le contrat que vous avez testé, acceptez les champs de réponse supplémentaires prévus par la documentation et exécutez les tests de compatibilité sur l’environnement cible avant le déploiement.

Les limites de débit illustrent bien ce risque. Un ancien texte officiel indiquait que les valeurs par défaut de TEST étaient dix fois supérieures à celles de la production. Le journal plus récent de l’API 2.5.0 précise qu’elles ont été alignées sur PRD, tandis que TEST a conservé ses points d’accès de simulation. La règle sûre consiste à consulter les limites effectives lors de l’exécution et à suivre le guide KSeF sur les nouvelles tentatives, au lieu d’inscrire un multiplicateur dans le code.

Quelle checklist suivre pour une mise en production KSeF sûre ?

Fondez la mise en production sur des preuves, pas sur des hypothèses. Cette liste de contrôle est une synthèse destinée aux équipes d’ingénierie, et non une procédure imposée par le ministère.

Lors des tests locaux et dans la CI

• Figez les schémas FA(3) et les jeux de données déterministes.
• Vérifiez les octets exacts que vous hachez, chiffrez et envoyez.
• Gardez le choix de l’environnement hors des données de facture.
• Rejetez tout hôte absent des trois listes d’autorisation officielles.
• Testez les champs inconnus et l’interruption du travail asynchrone.

Dans TEST

• Créez de nouvelles identités et de nouveaux jeux de données synthétiques.
• Testez les parcours de réussite, de rejet, de limitation, d’expiration et de redémarrage.
• Confirmez qu’aucun identifiant ni secret de production n’arrive dans les journaux ou le stockage.
• Conservez la version OpenAPI de TEST utilisée lors de l’exécution.

Dans DEMO

• Authentifiez-vous avec l’identité réelle prévue pour l’organisation.
• Vérifiez le graphe d’autorisations effectif.
• N’envoyez que des données de facture fictives ou anonymisées.
• Utilisez des limites proches de la production et la version candidate.
• Rapprochez l’état, les références et l’UPO après un redémarrage forcé.

Avant et pendant la bascule vers PRD

• Comparez le document OpenAPI actif de PRD avec le contrat figé du client.
• Configurez de nouveaux certificats, jetons, autorisations et un cache de clés publiques propres à PRD.
• Activez les garde-fous qui bloquent les clients et jeux de données synthétiques.
• Vérifiez d’abord les opérations qui n’émettent rien.
• Envoyez une véritable facture, puis rapprochez son état définitif et son UPO.
• Augmentez progressivement le volume tout en surveillant les codes 429, les échecs et l’ancienneté de la file d’attente.

Gardez le guide de la structure FA(3) à côté de cette liste. La validation XSD et TEST confirment la structure XML et le comportement du client, mais ni le traitement fiscal ni l’exhaustivité juridique d’une vraie facture. En cas d’échec, consultez le guide de résolution des erreurs de validation KSeF sans rejouer aveuglément un envoi ambigu.

Comment KSeF Kit gère-t-il la frontière entre environnements ?

Le changement d’environnement le plus sûr est celui que votre équipe n’a pas à maintenir. KSeF Kit est un produit distinct destiné aux équipes dont les factures proviennent de Stripe. Il convertit les factures Stripe finalisées au format FA(3), les envoie, attend le résultat KSeF, stocke l’UPO et reporte le numéro KSeF dans la donnée source.

Son guide de connexion public décrit la configuration de TEST et de la production. KSeF Kit constitue ainsi une solution ciblée pour les équipes qui utilisent Stripe et hésitent entre développer leur propre intégration et acheter un produit existant, sans prétendre couvrir tous les systèmes comptables, tous les types de facture ou toutes les décisions fiscales.

Que vous utilisiez une solution gérée ou votre propre client, conservez la même frontière : données synthétiques dans TEST, identité réelle associée à des factures fictives dans DEMO, et uniquement des factures authentiques et approuvées dans PRD. Faites passer le code d’un environnement à l’autre. Ne transférez jamais les secrets ni les données.