Gérer la facturation électronique KSeF dans B2Brouter
KSeF (Krajowy System e-Faktur, « Système National de Factures électroniques ») est la plateforme obligatoire du Ministère des Finances polonais pour la facturation électronique B2B. Les entreprises polonaises assujetties à la TVA doivent envoyer chaque facture au format FA(3) à KSeF et en recevoir un identifiant officiel (Numer KSeF) avant de la distribuer au client.
B2Brouter prend en charge le cycle complet : signature avec le certificat fiscal, transformation en FA(3), envoi, réception du numéro KSeF et génération du QR et du reçu officiel (UPO).
Pour qui — Entreprises avec NIP polonais (Numer Identyfikacji Podatkowej). Les entreprises non polonaises ne peuvent pas activer KSeF ni le sélectionner comme transport dans un contact polonais — la facture ne serait pas envoyée.
Environnements KSeF — Le Ministère en publie trois : Production, Démo (mêmes données réelles mais sans effets fiscaux) et Test (sandbox ouvert pour les intégrations). L’instance de production de B2Brouter communique avec KSeF Production ; celle de staging communique avec KSeF Test ou Démo selon la configuration du certificat.
Production — Accédez au portail web officiel KSeF du Ministère des Finances polonais à ap.ksef.mf.gov.pl/web en vous identifiant avec votre système d’identité fiscale (Profil Zaufany, signature qualifiée ou similaire). Dans le portail, dans la section des certificats/identifiants, générez un certificat d’authentification lié à votre NIP et exportez-le au format PKCS#12 (.p12 ou .pfx) avec un mot de passe. Le fichier obtenu portera un nom similaire à <NIP>_Uwierzytelnianie.pfx (Uwierzytelnianie = Authentification).
Test (tests et intégrations) — Le portail web équivalent pour les tests est ap-test.ksef.mf.gov.pl/web. Vous pouvez générer un certificat autosigné avec OpenSSL ; le sujet doit inclure le NIP dans le champ serialNumber=TINPL-<NIP>. Avant de l’utiliser, enregistrez-le manuellement sur ce même portail : sans cette étape, KSeF Test rejettera toutes les signatures de ce certificat comme inconnues.
Seul PKCS#12 (.p12 / .pfx) est accepté — Un fichier .crtne convient pas : il contient uniquement la partie publique, pas la clé privée, et KSeF en a besoin des deux pour authentifier la signature. Si le portail vous donne autre chose, refaites l’export en choisissant explicitement PKCS#12 et en cochant «inclure la clé privée». En dernier recours uniquement, si vous disposez du .crt et de la .key séparément, vous pouvez les combiner avec OpenSSL :
openssl pkcs12 -export \
-in ksef_certificate.crt \
-inkey ksef_private_key.key \
-out ksef_certificate.p12 \
-name "<NOM_ENTREPRISE> <NIP>" \
-passout pass:<MOT_DE_PASSE>
Algorithme de chiffrement — 3DES ou AES — Si vous recevez l’erreur «Certificate password is invalid» malgré la saisie du bon mot de passe, le fichier est chiffré avec un algorithme obsolète (RC2-40bit, typique des exports effectués depuis un Windows ancien). KSeF et B2Brouter n’acceptent que 3DES ou AES. Ré-exportez avec OpenSSL :
Environnement — Production par défaut. Démo ou Test uniquement si vous êtes en phase de test.
Enregistrer.
Lors de l’enregistrement, B2Brouter se connecte à KSeF, valide le certificat et vérifie que le NIP du sujet correspond au NIP du compte (ou que l’entreprise y est autorisée via ZAW-FA). Si la validation est correcte, le certificat est enregistré et KSeF est activé pour votre compte.
Une fois KSeF actif, le tax report se génère automatiquement — Vous n’avez rien d’autre à faire. Chaque facture émise à un contact polonais via KSeF génèrera automatiquement son tax report et sera envoyée à KSeF dans le cadre du même flux d’émission. Si vous intégrez via API, configurez le tax_report_setting avec auto_generate: true et auto_send: true pour que le flux soit équivalent à celui de l’interface.
Si le sujet du certificat ne correspond pas au NIP du compte — Vous devez soumettre le formulaire ZAW-FA sur le portail officiel pour autoriser votre entreprise à émettre des factures avec ce certificat. Tant que ZAW-FA n’est pas approuvé, KSeF rejettera les factures avec l’erreur 450 ou similaire.
Avant d’émettre une facture à un client, celui-ci doit exister dans les contacts.
Contacts → Nouveau contact.
Sélectionnez le pays du client.
Saisissez l’identifiant fiscal — dépend du pays du client (voir le tableau ci-dessous).
Valider l’identifiant et continuer — pour les clients polonais, B2Brouter se connecte au registre du Ministère pour vérifier le NIP et compléter automatiquement la raison sociale.
Renseignez l’adresse (rue, code postal, ville).
Configurez la méthode de livraison et choisissez KSeF comme transport. Si l’option KSeF n’apparaît pas, changez le type de réseau pour afficher KSeF dans la liste (dans certains comptes, c’est un réseau ouvert qui regroupe plusieurs transports).
Enregistrer.
Trois structures d’identification selon le pays du client
KSeF exige de déclarer le client dans l’une de trois structures mutuellement exclusives. Si vous mélangez les formats (NIP avec préfixe, préfixe sans pays, etc.) pour le même compte, vous obtiendrez des erreurs intermittentes — certaines factures passent, d’autres sont rejetées.
Type de client
Identifiant à saisir
Comment KSeF le génère dans le XML
Polonais
NIP (exactement 10 chiffres, sans préfixe PL)
Podmiot2/DaneIdentyfikacyjne/NIP
Autre pays UE
Numéro de TVA sans préfixe de pays (ex. 123456789 pour DE123456789)
Ne mélangez pas les formats — Pour un même client, envoyez toujours le même type d’identifiant. Si dans une facture vous l’envoyez comme polonais (PL + NIP) et dans la suivante comme UE (DE + TVA), KSeF appliquera des règles de validation différentes et le résultat sera incohérent.
Grèce : code fiscal EL, pas GR — Dans le champ fiscal UE (dans KSeF, KodUE), la Grèce s’identifie avec EL. Pour l’adresse, GR est utilisé. Si le formulaire vous permet de choisir GR dans le champ fiscal, corrigez-le en EL ; sinon KSeF rejettera la facture avec l’erreur KodUE: 'GR' is not an element of the set {...}.
Devise — PLN pour les factures domestiques. Pour les devises étrangères, renseignez le taux de change en PLN à la date de facture : il sera envoyé au champ KSeF KursWalutyZ.
Notes — texte libre qui apparaîtra comme pied de facture (Stopka) dans le PDF officiel. Utile pour les clauses légales, les conditions contractuelles ou toute information qui ne s’inscrit dans aucun autre champ.
Opération exonérée (usage d’exonération de la Loi TVA)
Autoliquidation domestique
oo
Odwrotne obciążenie — reverse charge PL
Non assujetti UE
np I
Services transfrontaliers non assujettis (Art. 28b)
Lignes exonérées (zw) — fondement légal dans le Commentaire — Pour les lignes avec taux exonéré, indiquez le fondement légal (ex. «art. 43 ust. 1 pkt 37 ustawy VAT») dans le champ Commentaire de la ligne. Dans le PDF apparaîtront deux paragraphes : une annotation légale générique (automatique) et le commentaire que vous avez rédigé.
Pour une exportation hors UE en devise étrangère :
Taux de TVA : 0 EX.
Pays de l’acheteur : le pays non-UE.
Taux de change : celui de la veille de la date de TVA, selon le tableau de la BCE ou NBP.
N’utilisez pas zw (exonéré) pour les exportations — Une exportation est 0 EX (taux zéro pour exportation, P_13_6_3). Si vous utilisez zw, le montant est dupliqué entre les cases domestiques taux zéro et exonération, et KSeF rejette ou fausse la déclaration.
Dans la fiche d’une facture émise, vous verrez l’état actuel, le Numer KSeF une fois enregistrée, et le reçu UPO.
Sending → Registered → (QR + Numer KSeF + UPO)
↘ Error
Sending — B2Brouter a signé et envoyé le document. L’enregistrement effectif à KSeF peut prendre quelques minutes, notamment en heures de pointe ou à la clôture du mois.
Registered ✅ — KSeF a validé et attribué le Numer KSeF (NrKSeF). Le QR de la facture imprimée affiche désormais ce numéro et le justificatif officiel d’enregistrement est disponible (voir ci-dessous).
Error ❌ — KSeF a rejeté le document. Le motif apparaît dans la fiche (code + description en polonais).
Le QR apparaît immédiatement, mais cela ne signifie pas que KSeF a accepté la facture — B2Brouter génère le code QR localement à partir du hash cryptographique, du NIP et de la date : il est visible immédiatement, même si la facture se termine en erreur. Le seul indicateur fiable d’acceptation est l’état Registered. Si l’état est Error, la facture n’est pas enregistrée à KSeF indépendamment du QR ou du lien généré. Pendant que la facture est Sending, le QR porte l’étiquette OFFLINE.
Qu’est-ce que c’est. L’UPO (Urzędowe Poświadczenie Odbioru, en français Accusé Officiel de Réception) est le justificatif émis par KSeF lorsqu’il accepte et enregistre la facture. Il fonctionne comme un accusé de réception administratif : c’est la preuve légale, à valeur fiscale, que vous avez rempli l’obligation d’enregistrer la facture à KSeF à un moment précis.
Techniquement, c’est un document XML signé numériquement par le Ministère des Finances polonais. Il contient le Numer KSeF (NrKSeF) attribué à la facture, l’horodatage exact de l’enregistrement et la signature du Ministère. Ce n’est pas un PDF visuel — c’est une preuve légale lisible par machine.
D’où vient-il. Il est généré par KSeF au moment de valider et d’accepter la facture. Ce n’est pas B2Brouter ni vous qui le générez.
Comment confirmer l’enregistrement depuis B2Brouter. Lorsque la facture passe à Registered, ouvrez le tax report KSeF associé (lié depuis la fiche de la facture). Dans l’onglet Activité, vous verrez l’événement d’envoi correct avec le Numer KSeF attribué — confirmation que KSeF a reçu, validé et enregistré le document.
Comment obtenir le fichier XML de l’UPO pour votre archive comptable. Le fichier original est disponible par deux voies :
Depuis le portail officiel KSeF — ap.ksef.mf.gov.pl/web (ou ap-test.ksef.mf.gov.pl/web pour l’environnement de test). En accédant avec votre système d’identité fiscale, vous pouvez consulter et télécharger les UPOs de votre compte directement du Ministère — ce sont les originaux officiels.
Via l’API de B2Brouter — si vous intégrez avec l’API, l’UPO est disponible comme pièce jointe du tax report. Voir le Guide KSeF pour les développeurs.
Conservez les UPOs avec la facture — Ils ont une valeur juridique lors d’un contrôle fiscal. Téléchargez-les depuis KSeF ou via API et archivez-les avec la facture originale.
Ouvrez la facture et lisez le code + la description de l’erreur.
Corrigez les données problématiques (contact, NIP, montants…).
Renvoyez la facture. B2Brouter retente l’enregistrement à KSeF avec les données corrigées.
Exception — numéro de facture déjà vu par KSeF — Si le rejet est dû au fait que le numéro de facture a déjà été utilisé dans un envoi précédent, vous ne pourrez pas renvoyer le même document : supprimez-le, corrigez les données et créez une nouvelle facture avec un numéro différent.
Une facture rectificative (faktura korygująca) modifie une facture KSeF précédente. Le document lie l’original (DaneFaKorygowanej) et réexprime les lignes affectées avec indication de l’état avant et après.
Ouvrez la facture originale déjà enregistrée à KSeF.
Créer une facture rectificative — B2Brouter remplit automatiquement le numéro KSeF, le numéro de facture et la date de l’original.
Indiquez le Type d’effet (TypKorekty) :
1 — Effet à la date de la facture originale. Usage : corrections d’erreurs existantes à l’émission (montant mal calculé, taux de TVA erroné).
2 — Effet à la date de la facture rectificative. Usage : faits postérieurs (retours, remises post-vente).
3 — Effet à une date différente — indiquez-la explicitement.
Mettez à jour les lignes au nouvel état (quantités, prix, taux de TVA).
Si vous souhaitez ajouter un motif textuel de la correction (ex. «Korekta ilości — dostawa niepełna») ou tout texte légal associé, écrivez-le dans le champ Notes de la facture : il est envoyé au pied officiel du document (Stopka/Informacje/StopkaFaktury) et visible dans le PDF de KSeF.
Émettre et envoyer.
État «avant / après» — La rectificative que vous émettez depuis le formulaire porte directement les lignes avec les nouvelles valeurs ; c’est le cas habituel et suffisant pour la majorité des corrections. Si vous avez besoin de la représentation formelle avant/après (lignes originales annulées plus les nouvelles dans le même document, avec marqueur Stan przed par ligne), cette option n’est accessible que via API : voir le Guide pour les développeurs.
Pour rectifier une ZAL (acompte), utilisez une KOR_ZAL ; pour rectifier une ROZ (liquidation), utilisez une KOR_ROZ. La procédure est identique à une KOR normale.
Une fois KSeF activé dans le compte, votre NIP est enregistré comme destinataire et les fournisseurs polonais peuvent vous y envoyer des factures directement.
Dépenses → vous y trouverez toutes les factures KSeF reçues.
Ouvrez une facture pour en voir le détail.
Où se trouve le Numer KSeF d’une facture reçue — Le numéro KSeF officiel (NrKSeF) n’apparaît pas sur l’image du PDF d’aperçu, mais dans la section Activité de la facture reçue (format XXXXXXXXXX-AAAAMMDD-XXXXXXXXXXXX-XX). Le QR n’est visible dans le PDF que si le fournisseur l’a inclus dans son image.
Une facture que le fournisseur dit avoir émise mais qui n’apparaît pas dans Dépenses — Vérifiez d’abord que le PDF envoyé par le fournisseur porte un code QR de KSeF. Sans QR, la facture n’a pas été envoyée via KSeF — le fournisseur n’a peut-être pas complété l’enregistrement. S’il y a un QR, scannez-le et copiez l’URL : avec cette URL, nous pouvons vérifier si le document existe réellement à KSeF.
Nouvelle — reçue dans B2Brouter, en attente de votre examen.
Lue — vous l’avez ouverte au moins une fois.
Approuvée / Rejetée — l’état que vous lui avez attribué (aucun message n’est envoyé au fournisseur ; KSeF n’a pas de canal d’acceptation/rejet équivalent à celui de Peppol).
Certificat rejeté malgré le bon mot de passe — le PKCS#12 est chiffré avec un algorithme obsolète (RC2-40bit), typique des exports effectués depuis un Windows ancien. Ré-exportez avec 3DES ou AES (voir § 1).
450 - Nip nabywcy: '…' jest nieprawidłowy — NIP de l’acheteur invalide. Vérifiez 10 chiffres + chiffre de contrôle. Pour les contacts UE, utilisez le numéro de TVA UE sans préfixe (voir § 2).
KodUE: 'GR' is not an element of the set — La Grèce dans le champ fiscal UE doit être EL, pas GR. Modifiez le contact et corrigez.
«Contact Email can’t be blank» — le transport du contact est e-mail mais il n’y a pas d’adresse. Ajoutez un e-mail ou changez le transport.
État Error mais QR et URL ont été générés — normal. Le QR est calculé localement et ne dépend pas de l’acceptation de KSeF. L’état Error est autoritatif : la facture n’est pas enregistrée.
Facture que le fournisseur dit avoir émise mais qui n’apparaît pas dans Dépenses — vérifiez que le PDF du fournisseur porte le code QR de KSeF. Sans QR, elle n’a pas réellement été enregistrée.
Compte non polonais qui tente d’utiliser KSeF comme transport — KSeF n’est disponible que pour les comptes avec NIP polonais. Utilisez Peppol ou e-mail pour ce contact.
Récapitulatif de TVA affiche «23% lub 22%» — étiquette officielle du template du Ministère, qui combine le taux historique (22 %) et l’actuel (23 %) dans un seul champ. Ce n’est pas une erreur.
Champ «Nazwa banku» (nom de la banque) vide — KSeF n’exige pas le nom de la banque et B2Brouter ne le renseigne pas automatiquement. Si vous en avez besoin, ajoutez-le dans le champ Notes.
Ce manuel décrit l’interface utilisateur. Si vous intégrez B2Brouter via API, la référence officielle est le Guide KSeF pour les développeurs — il couvre les endpoints Tax Report Settings, Tax Reports, Invoices et Contacts, le mapping complet entre JSON et FA(3), les webhooks de suivi d’états et le téléchargement de l’UPO.
Authentification par clé API statique (en-tête X-B2B-API-Key) + version d’API (X-B2B-API-Version). Les fonctionnalités spécifiques à KSeF nécessitent la version 2025-10-13 ou ultérieure.
