Structure XML FA(3) : le guide KSeF pour les développeurs

La structure XML FA(3) est le schéma utilisé par KSeF pour les factures structurées émises depuis le 1er février 2026. Traitez-la comme trois contrats distincts : le XSD définit la forme du XML, les règles polonaises de TVA déterminent les données obligatoires et la transaction active les branches conditionnelles. Validez les trois avant l’envoi. Seul le statut final de KSeF vaut acceptation, pas la réponse au téléversement.

Ce guide est technique et ne constitue pas un conseil fiscal. Faites confirmer le traitement de TVA et les mentions légalement requises pour chaque type de facture.

Qu’est-ce que la structure XML FA(3) ?

FA(3) est la structure logique du ministère polonais des Finances pour la facture structurée. Ce n’est ni une mise en page PDF ni un modèle visuel : ce contrat XML précise quels éléments sont admis, à quel endroit, combien de fois et sous quels types et formats.

Le manuel KSeF 2.0 pose une distinction essentielle. La structure régit ce que le XML doit ou peut contenir, tandis que l’article 106e de la loi sur la TVA continue de fixer les informations exigées sur une facture donnée. FA(3) offre aussi des champs facultatifs, tels que les coordonnées, que la loi fiscale n’impose généralement pas.

Ne réduisez pas ces niveaux à un booléen « XML valide ». minOccurs="0" signifie uniquement que le XSD autorise l’omission, pas que le droit l’autorise dans tous les cas. Inversement, un champ rempli dans un exemple officiel n’est pas obligatoire partout.

Quel espace de noms et quel en-tête FA(3) utiliser ?

Utilisez l’espace de noms cible du XSD FA(3) officiel :

http://crd.gov.pl/wzor/2025/06/25/13775/

La barre oblique finale compte. Le schéma qualifie les éléments : ajouter ensuite un emplacement de schéma ne transforme pas un <Faktura> sans espace de noms en document équivalent.

L’exemple officiel du client Java montre l’identité d’en-tête correspondante :

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>
    <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
    <WariantFormularza>3</WariantFormularza>
    <DataWytworzeniaFa>2026-08-28T09:30:00Z</DataWytworzeniaFa>
    <SystemInfo>YourApp 4.2</SystemInfo>
  </Naglowek>
  <!-- Remaining sections in XSD order -->
</Faktura>

Centralisez l’espace de noms, kodSystemowy, wersjaSchemy et la variante dans un sérialiseur versionné. Une future version du ministère doit déclencher un choix explicite de sérialiseur et de fixtures, pas un remplacement global de chaînes.

Générez du XML 1.0 en UTF-8 sans BOM. Les règles de vérification autorisent l’absence de déclaration XML, mais interdisent d’y déclarer un autre encodage. KSeF refuse aussi les instructions de traitement et certaines plages Unicode déconseillées. Normalisez le texte avant la sérialisation.

Quelles sont les huit sections principales de FA(3) ?

L’ordre fait partie du contrat. Le XSD place souvent les éléments dans sequence et choice ; un mappeur objet-XML peut donc produire toutes les bonnes valeurs dans le mauvais ordre. Déclarez l’ordre de sérialisation et couvrez-le par un test XSD.

Podmiot3, PodmiotUpowazniony, Stopka et Zalacznik ne sont pas du remplissage. Ajoutez-les seulement si le modèle métier comporte ce rôle ou cette fonction. Les annexes suivent en outre un parcours activé séparément, avec d’autres limites de taille et d’envoi.

À quoi ressemble le squelette d’une facture FA(3) ?

Ce squelette illustre les relations principales. Il est volontairement incomplet : il n’est ni prêt à copier-coller, ni minimal au sens du schéma, ni juridiquement suffisant.

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>
    <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
    <WariantFormularza>3</WariantFormularza>
    <DataWytworzeniaFa>2026-08-28T09:30:00Z</DataWytworzeniaFa>
    <SystemInfo>YourApp 4.2</SystemInfo>
  </Naglowek>
  <Podmiot1><DaneIdentyfikacyjne><NIP>1234567890</NIP><Nazwa>Example Seller sp. z o.o.</Nazwa></DaneIdentyfikacyjne></Podmiot1>
  <Podmiot2><DaneIdentyfikacyjne><NIP>9876543210</NIP><Nazwa>Example Buyer sp. z o.o.</Nazwa></DaneIdentyfikacyjne></Podmiot2>
  <Fa>
    <KodWaluty>PLN</KodWaluty><P_1>2026-08-28</P_1><P_2>FV/2026/08/1042</P_2><P_15>123.00</P_15>
    <Adnotacje><!-- Applicable markers and branches --></Adnotacje>
    <RodzajFaktury>VAT</RodzajFaktury>
    <FaWiersz><NrWierszaFa>1</NrWierszaFa><P_7>Software subscription</P_7><P_8A>szt.</P_8A><P_8B>1</P_8B><P_9A>100.00</P_9A><P_11>100.00</P_11><P_12>23</P_12></FaWiersz>
  </Fa>
</Faktura>

Le « minimum » varie selon le type de facture, les parties, la TVA, le paiement, les corrections et les acomptes. Un document conçu uniquement pour satisfaire les cardinalités XSD peut omettre des mentions légales. Partez d’un modèle de facture typé et de fixtures par scénario.

Comment mapper les identifiants du vendeur et de l’acheteur ?

KSeF utilise Podmiot2/DaneIdentyfikacyjne/NIP pour rendre la facture disponible à l’acheteur polonais. Un NIP rangé dans NrID peut sembler plausible dans votre modèle tout en rompant cette mise à disposition.

Stockez séparément tax_identifier_kind, country_code, identifier et has_no_identifier. Validez les branches exclusives avant la sérialisation. Supprimez les séparateurs d’affichage d’un NIP sans « réparer » silencieusement une valeur ambiguë. KSeF vérifie aussi les clés de contrôle NIP en production, contrairement à TEST dans les mêmes conditions : validez-les vous-même.

Comment modéliser Fa, les totaux et les lignes ?

Fa porte la transaction : devise (KodWaluty), date d’émission (P_1), numéro attribué par le vendeur (P_2), totaux, mentions, type (RodzajFaktury), lignes FaWiersz et, selon le cas, paiement.

Ne faites pas des noms XML votre modèle métier. Représentez montants, catégories fiscales, quantités, dates, parties et type de facture avec des types métier, puis mappez-les vers FA(3). Pour chaque scénario, vérifiez la réconciliation des lignes et des totaux, la règle d’arrondi de TVA, P_15, les formats invariants, l’absence de date P_1 future et la stabilité de P_2.

La détection de doublon combine NIP vendeur, RodzajFaktury et P_2. Une relance doit réconcilier la même facture logique, pas inventer un nouveau numéro. Conservez une clé d’idempotence autour de la facture et de la référence KSeF.

Les mentions exigent des tests de scénario. Copier les marqueurs négatifs de l’exemple officiel peut produire un document valide mais factuellement faux. Dérivez chaque branche des faits et testez séparément exonération, autoliquidation, paiement fractionné, marge et autres cas pris en charge.

Comment valider FA(3) en local avant l’envoi ?

1. Figez un instantané typé du vendeur, de l’acheteur, des lignes, de la TVA, des totaux, des dates et du type.
2. Appliquez les règles métier et retournez des erreurs de champ compréhensibles.
3. Sérialisez de façon déterministe en XML 1.0, UTF-8 sans BOM, dans l’espace de noms et l’ordre exacts.
4. Validez avec le XSD épinglé et ses définitions importées ; conservez leur somme de contrôle et leur URL.
5. Figez les octets : calculez taille et hachage sur la séquence réellement chiffrée et envoyée.
6. Conservez le diagnostic : version du sérialiseur, instantané source, hachage, taille et résultat. Protégez le XML comme donnée financière sensible.

Les règles officielles limitent une facture sans annexe à 1 Mo et avec annexe à 3 Mo. Un test XSD local ne couvre pas les limites du service. Utilisez des fixtures par scénario : TVA nationale, acheteur UE, pays tiers, consommateur, correction, acompte, exonération et chaque régime réellement pris en charge.

Comment tester dans TEST, DEMO et la production ?

La matrice officielle des environnements présente TEST pour l’intégration, DEMO comme proche de la production et PRD comme l’environnement où les factures produisent leurs effets juridiques. N’envoyez aucune donnée réelle dans TEST ou DEMO. TEST accepte des certificats auto-signés et ses données ne doivent pas être considérées comme confidentielles : utilisez des identités et NIP synthétiques.

Testez d’abord le mapping et le XSD en local, envoyez les scénarios synthétiques dans TEST, vérifiez permissions, suivi de statut et UPO dans DEMO, puis promouvez exactement le même sérialiseur vers PRD sous surveillance. L’acceptation en TEST ne prouve pas la validité d’un NIP en production. Versionnez aussi les capacités par environnement, car une version d’API peut arriver dans TEST avant DEMO et PRD.

Quand une facture envoyée est-elle réellement acceptée ?

L’envoi en session en ligne est asynchrone. L’API peut accepter la mise en traitement et renvoyer une référence avant d’accepter la facture. Conservez cette référence immédiatement et passez la facture dans un état visible processing.

Le guide officiel du statut et de l’UPO décrit les statuts de session et de facture, les échecs et la récupération de l’UPO. Interrogez avec temporisation progressive, gardez les détails structurés et distinguez : générée et validée, envoyée avec référence, en traitement, rejetée, acceptée avec numéro KSeF, puis UPO stocké.

Seul le parcours accepté doit exposer le numéro KSeF comme preuve finale. Conservez l’UPO avec des métadonnées résistantes à l’altération et réconciliez les sessions longues. HTTP 202 signifie « mis en file », pas « facture réussie ».

Développer FA(3) ou utiliser KSeF Kit ?

Développez l’intégration si FA(3) est au cœur du produit, si vos sources dépassent Stripe ou si vous devez gérer des cas fiscaux spécialisés. Budgétez le suivi du schéma, les fixtures, les secrets, les environnements, la supervision et l’exploitation, pas seulement le XML.

Si Stripe est votre source, KSeF Kit convertit les factures Stripe finalisées en FA(3), les envoie à KSeF et conserve le numéro KSeF et l’UPO. Sa documentation de configuration couvre les connexions Stripe et KSeF ainsi que les parcours de test et de production.

Cela ne remplace pas des données fiscales exactes et ne garantit pas globalement la conformité. Cela retire cependant une surface d’intégration importante : sérialiseur, chiffrement, envoi, machine d’états asynchrone et remise des preuves. Dans les deux cas, exigez des faits métier exacts, un XML FA(3) valide, un traitement KSeF réussi et des preuves conservées. Retrouvez d’autres guides dans les archives d’ingénierie de la conformité.